diff --git a/docs/griptape-cloud/index.md b/docs/griptape-cloud/index.md index d70f020bc..62086baf8 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 Agents with Tools + +Expand the capabilities of your agents with custom Tools they can use. These Tools allow them to call services or perform custom logic, bridging the gap between the LLM and your application. Tools can even be used to augment other applications like [OpenAI's GPTs via OpenAI Actions](https://platform.openai.com/docs/actions/introduction). See [Tools](tools/create-tool.md) to get started. + ## 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..4f51e62f6 --- /dev/null +++ b/docs/griptape-cloud/tools/create-tool.md @@ -0,0 +1,17 @@ +# Tools + +You can host your [Griptape framework Tools](../../griptape-tools/index.md) on Griptape Cloud. This allows you to run your Tools without needing to manage infrastructure. + +## 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..6add21214 --- /dev/null +++ b/docs/griptape-cloud/tools/run-tool.md @@ -0,0 +1,36 @@ +# Running a Tool + +Tools are run by sending HTTP POST requests to the Tool's activity endpoints. Activities are defined by decorating your tool's methods with the `@activity` decorator. The activity name is the name of the method. + +For example, if you deployed Griptape's provided [`CalculatorTool`](../../griptape-tools/official-tools/calculator-tool.md), the endpoint for the `calculate` activity would be `https://cloud.griptape.ai/api/tools/{tool_id}/activities/calculate`. The request body would be a JSON object with the key `expression` and the value as the expression to calculate. + +```json +{ + "expression": "10**5" +} +``` + +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](../../reference/griptape/tools/griptape_cloud_tool/tool#griptape.tools.griptape_cloud_tool.tool.GriptapeCloudToolTool.tool_id), 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..15dad5c2b --- /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 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 8f510064b..b7dae68d0 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: