From d6e4b54ae34897978c10a4cf5d10a6ad08229daf Mon Sep 17 00:00:00 2001 From: matt Date: Fri, 20 Dec 2024 10:47:34 -0500 Subject: [PATCH] tool docs --- docs/griptape-cloud/index.md | 4 ++ .../structures/structure-config.md | 2 + docs/griptape-cloud/tools/create-tool.md | 17 +++++ docs/griptape-cloud/tools/run-tool.md | 26 ++++++++ docs/griptape-cloud/tools/tool-config.md | 62 +++++++++++++++++++ mkdocs.yml | 4 ++ 6 files changed, 115 insertions(+) create mode 100644 docs/griptape-cloud/tools/create-tool.md create mode 100644 docs/griptape-cloud/tools/run-tool.md create mode 100644 docs/griptape-cloud/tools/tool-config.md diff --git a/docs/griptape-cloud/index.md b/docs/griptape-cloud/index.md index d70f020bc..605b1e417 100644 --- a/docs/griptape-cloud/index.md +++ b/docs/griptape-cloud/index.md @@ -10,6 +10,10 @@ Connect to your data with our [Data Sources](data-sources/create-data-source.md) Have Griptape code? Have existing code with another LLM framework? You can host your Python code using [Structures](structures/create-structure.md) whether it uses the Griptape Framework or not. +## Augment LLM requests with Tools + +Create custom actions that LLMs can perform with [Tools](tools/create-tool.md). Tools in the cloud are instances of [Griptape Framework Tools](/griptape-tools/index.md) and can be run from anywhere with a simple API call or through Griptape Framework's [GriptapeCloudToolTool](/griptpe-tools/official-tools/griptape-cloud-tool-tool.md). + ## Store Configuration for LLM Agents [Rules and Rulesets](rules/rulesets.md) enable rapid and collabortive iteration for managing LLM behavior. [Threads and Messages](threads/threads.md) allow for persisted and editable conversation memory across any LLM invocation. diff --git a/docs/griptape-cloud/structures/structure-config.md b/docs/griptape-cloud/structures/structure-config.md index 1891591a3..3e059934c 100644 --- a/docs/griptape-cloud/structures/structure-config.md +++ b/docs/griptape-cloud/structures/structure-config.md @@ -4,6 +4,8 @@ Structure repositories require a configuration file which informs Griptape Cloud ## Structure Config File Schema +All relative paths are based off of the directory in which the `structure_config.yaml` file is located. + The schema for the configuration file is as follows: ```yaml diff --git a/docs/griptape-cloud/tools/create-tool.md b/docs/griptape-cloud/tools/create-tool.md new file mode 100644 index 000000000..604f2b896 --- /dev/null +++ b/docs/griptape-cloud/tools/create-tool.md @@ -0,0 +1,17 @@ +# Tools + +Tools can be used to execute arbitrary actions in a request/response format. They can be given to an LLM so the LLM can take appropriate action based on the metadata of the Tool. + +## Create a Tool + +1. [Connect Your GitHub Account in your Griptape Cloud account](https://cloud.griptape.ai/account) +1. Install the [Griptape Cloud GitHub app to your GitHub account or organization](https://github.com/apps/griptape-cloud/installations/new/) + - Be sure to allow the app access to `All Repositories` or select the specific repositories you need +1. Ensure your repository has a Tool Config YAML file + - To learn more see [Tool Config YAML](tool-config.md) + +You can now [create a Tool in the Griptape Cloud console](https://cloud.griptape.ai/tools/create) by providing your GitHub repository information. + +### Quickstart With Samples and Templates + +To get started with Tools in the Cloud, deploy one of the [griptape-sample-tools from GitHub](https://github.com/griptape-ai/griptape-sample-tools/tree/main). diff --git a/docs/griptape-cloud/tools/run-tool.md b/docs/griptape-cloud/tools/run-tool.md new file mode 100644 index 000000000..8ec13340c --- /dev/null +++ b/docs/griptape-cloud/tools/run-tool.md @@ -0,0 +1,26 @@ +# Running a Tool + +Once your Tool is created and deployed, you can run your Tool one of three ways outlined below. + +## From the Cloud Console + +Go to the `Test` tab of your Tool to open the generated OpenAPI spec. From there, the Swagger UI can be used to create test requests. + +## From the API + +The API route for Tool activities is in the form of `https://cloud.griptape.ai/api/tools/{tool_id}/activities/{activity_name}`, where `tool_id` is the resource UUID of your created Tool, and `activity_name` is the name of the activity as defined in your `BaseTool` class. The activity routes will only accept an http POST method. + +To fetch the OpenAPI schema, the route is `https://cloud.griptape.ai/api/tools/{tool_id}/openapi`. + +```bash +export GT_CLOUD_API_KEY="" +export GT_CLOUD_TOOL_ID="" +export TOOL_ACTIVITY_URL="https://api.griptape.com/v1/tools/${GT_CLOUD_TOOL_ID}/activities/my_activity" + +response=$(curl -X POST -H "Authorization: Bearer ${GT_CLOUD_API_KEY}" --json '{"my_key": "my_value"}' ${TOOL_ACTIVITY_URL}) +echo "my_activity response: ${response}" +``` + +## Using the Griptape Framework + +The Griptape framework provides a [`GriptapeCloudToolTool`](../../griptape-tools/official-tools/griptape-cloud-tool-tool.md) for interacting with your deployed Tools. Simply pass your Tool resource UUID as the `tool_id` kwarg, and the schema and activity methods will be dynamically set on the Tool. diff --git a/docs/griptape-cloud/tools/tool-config.md b/docs/griptape-cloud/tools/tool-config.md new file mode 100644 index 000000000..b76aa486a --- /dev/null +++ b/docs/griptape-cloud/tools/tool-config.md @@ -0,0 +1,62 @@ +## Overview + +Tool repositories require a configuration file which informs Griptape Cloud of your Managed Tool's dependencies and how it needs to build and run. + +## Tool Config File Schema + +All relative paths are based off of the directory in which the `tool_config.yaml` file is located. + +The schema for the configuration file is as follows: + +```yaml +version: 1.0 +runtime: python3 +runtime_version: 3.12 +build: + pre_build_install_script: scripts/my-pre-build-install-script.sh + post_build_install_script: scripts/my-post-build-install-script.sh + requirements_file: requirements.txt + cache_build_dependencies: + enabled: false + watched_files: + - requirements.txt + - scripts/my-pre-build-install-script.sh + - scripts/my-post-build-install-script.sh +run: + init_tool_function: init_tool + init_tool_file: tool.py + tool_file: tool.py +``` + +### Configuration Fields + +#### version + +The Tool Config schema version number. + +#### runtime + +The runtime environment to use for the Tool. + +#### runtime_version + +The specific version of the runtime environment for the Tool. + +#### build (OPTIONAL) + +The build-time configuration for the Tool. + +- **pre_build_install_script** - The path to your pre_build_install_script, for running during the Tool build prior to dependency installation. This path is relative to the structure configuration file. Or absolute from the repository root if a forward slash is used: `/my-pre-build-install-script.sh`. +- **post_build_install_script** - The path to your post_build_install_script, for running during the Tool build after dependency installation. This path is relative to the structure configuration file. Or absolute from the repository root if a forward slash is used: `/my-post-build-install-script.sh`. +- **requirements_file** - The path to your Tool's requirements.txt file. +- **cache_build_dependencies** - Defines the configuration for caching build dependencies in order to speed up Deployments + - **enabled** - Defines whether the build dependency caching is on or off + - **watched_files** - Defines the particular files that will trigger cache invalidation, resulting in a full rebuild of the Tool and dependencies + +#### run (REQUIRED) + +The run-time configuration for the Tool. + +- **tool_file**: The file that contains the Griptape `BaseTool`-derived class. The default value is `tool.py`. +- **init_tool_file**: The file that contains your `init_tool` function. The default value is `tool.py`. +- **init_tool_function**: The function that will be called. The function takes no arguments and returns an instance of your `Tool`. diff --git a/mkdocs.yml b/mkdocs.yml index d48b3622c..93d24bed2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -89,6 +89,10 @@ nav: - Structure Config YAML: "griptape-cloud/structures/structure-config.md" - Running Your Structure: "griptape-cloud/structures/run-structure.md" - Structure Run Events: "griptape-cloud/structures/structure-run-events.md" + - Tools: + - Create a Tool: "griptape-cloud/tools/create-tool.md" + - Tool Config YAML: "griptape-cloud/tools/tool-config.md" + - Running Your Tool: "griptape-cloud/tools/run-tool.md" - Rules: - Create a Ruleset: "griptape-cloud/rules/rulesets.md" - Threads: