From f7a4bab53eb4c97047f533959df7dd2ae7ae9458 Mon Sep 17 00:00:00 2001 From: Arsenii Shatokhin Date: Wed, 18 Dec 2024 17:56:22 +0400 Subject: [PATCH] Finished openapi schemas page --- .../additional-features/openapi-schemas.mdx | 71 ----------- docs_new/core-framework/agents.mdx | 29 +++++ .../tools/custom-tools/best-practices.mdx | 20 ++- .../custom-tools/pydantic-is-all-you-need.mdx | 2 +- .../core-framework/tools/openapi-schemas.mdx | 116 ++++++++++++++++++ docs_new/mint.json | 4 +- 6 files changed, 155 insertions(+), 87 deletions(-) delete mode 100644 docs_new/additional-features/openapi-schemas.mdx create mode 100644 docs_new/core-framework/tools/openapi-schemas.mdx diff --git a/docs_new/additional-features/openapi-schemas.mdx b/docs_new/additional-features/openapi-schemas.mdx deleted file mode 100644 index e092253a..00000000 --- a/docs_new/additional-features/openapi-schemas.mdx +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: "OpenAPI Schemas" -description: "Integrate OpenAPI schemas into your agents for seamless API interaction." -icon: "brackets-curly" ---- - -OpenAPI schemas enable your agents within the Agency Swarm framework to interact with external APIs in a structured, reliable manner. By converting OpenAPI schemas into tools, agents can perform API calls with proper parameter validation and error handling, significantly enhancing their capabilities without compromising on robustness. - -### How to Integrate OpenAPI Schemas - -Agency Swarm offers built-in support for converting OpenAPI schemas into tools that your agents can use directly. This automatic conversion makes agents aware of API endpoints, parameters, and expected data types as defined in the OpenAPI specifications. - -#### Option 1: Using the Schemas Folder - -A straightforward way to integrate OpenAPI schemas is by specifying a `schemas_folder` when initializing your agent. Agency Swarm will automatically scan this folder and convert any OpenAPI schemas it finds into `BaseTool` instances. - -```python -from agency_swarm import Agent - -agent = Agent( - name='MyAgent', - schemas_folder='schemas', - api_params={'api_schema.json': {'param1': 'value1'}}, - api_headers={'api_schema.json': {'Authorization': 'Bearer token'}} -) -``` - -In this example: - -- `schemas_folder`: Designates the directory containing your OpenAPI schema files. -- `api_params`: Provides additional parameters for specific schemas. -- `api_headers`: Allows custom headers, such as authentication tokens, to be included in API calls. - - -By automatically converting OpenAPI schemas into tools, your agents perform type checking on all API parameters **before** making API calls, reducing errors and improving reliability. - - -#### Option 2: Using the ToolFactory Class - -Alternatively, you can use the `ToolFactory` class to convert OpenAPI schemas from local files or URLs. - - -```python -from agency_swarm.tools import ToolFactory - -with open("schemas/api_schema.json") as f: - tools = ToolFactory.from_openapi_schema(f.read()) -``` - - - -```python -from agency_swarm.tools import ToolFactory -import requests - -response = requests.get("https://api.example.com/openapi.json") -tools = ToolFactory.from_openapi_schema(response.json()) -``` - - -### Best Practices - - -- **Keep Schemas Updated**: Regularly update your OpenAPI schema files to align with the latest API definitions. -- **Secure API Access**: Use `api_headers` to securely manage authentication tokens and sensitive information. -- **Implement Error Handling**: Ensure your agents gracefully handle failed API calls and provide fallback responses. - - - -When integrating external APIs, be cautious of rate limits, authentication requirements, and data privacy considerations. - diff --git a/docs_new/core-framework/agents.mdx b/docs_new/core-framework/agents.mdx index cadf279f..893ee81e 100644 --- a/docs_new/core-framework/agents.mdx +++ b/docs_new/core-framework/agents.mdx @@ -272,3 +272,32 @@ from AgentName import AgentName agent = AgentName() ``` + +Agency Swarm comes with several built-in tools to enhance agent capabilities: + + +- **Purpose**: Allows agents to execute code within a Jupyter Notebook environment (without internet access). +- **Integration**: + ```python + from agency_swarm.tools import CodeInterpreter + + agent = Agent( + name="DataAnalyst", + tools=[CodeInterpreter], + # Other agent parameters + ) + ``` + + + +- **Purpose**: Enables Retrieval-Augmented Generation (RAG) by allowing agents to search files. +- **Integration**: + ```python + from agency_swarm.tools import FileSearch + + agent = Agent( + name="Researcher", + tools=[FileSearch], + # Other agent parameters + ) + ``` \ No newline at end of file diff --git a/docs_new/core-framework/tools/custom-tools/best-practices.mdx b/docs_new/core-framework/tools/custom-tools/best-practices.mdx index b870fa1a..a657c03e 100644 --- a/docs_new/core-framework/tools/custom-tools/best-practices.mdx +++ b/docs_new/core-framework/tools/custom-tools/best-practices.mdx @@ -6,8 +6,6 @@ icon: "code" Although the tool interface is straightforward and simple to use, there are actually quite a few practices and tricks that you can use to get significantly better results. -## Tips & Tricks - ### Use Chain-of-Thought Prompting for Complex Tools Use chain-of-thought prompting to allow the agent to think and plan before executing a complex tool. @@ -52,7 +50,7 @@ class QueryDatabase(BaseTool): return context ``` -### Use Shared State to Control Tool Flow +### Use Shared State to Control the Tool Flow Use `shared_state` to validate previous actions taken by this or other agents, before allowing it to proceed with the next action. @@ -67,7 +65,7 @@ class Action2(BaseTool): return "Success. The action has been taken." ``` -### Use Enumerations or Literal Types +### Use Special Types Restrict the agent to only use specific values for a field, instead of letting it wander by itself. @@ -91,7 +89,7 @@ class RunCommand(BaseTool): raise ValueError("Invalid command") ``` -or use special Pydantic types like `EmailStr. +or use special Pydantic types like `EmailStr`. ```python from pydantic import EmailStr @@ -100,11 +98,9 @@ class EmailSender(BaseTool): recipient: EmailStr = Field(..., description="Email recipient's address.") ``` -## Common Patterns - -### Method Composition +### Combine Multiple Methods -Combine multiple methods to handle complex operations. +Combine multiple methods to make your execution flow more readable. ```python class CompositeTool(BaseTool): @@ -136,7 +132,7 @@ class CompositeTool(BaseTool): ``` -### Testing Tools +### Include a Test Case Include test cases at the bottom of each tool file. @@ -149,9 +145,9 @@ if __name__ == "__main__": subject="Project Update", body="The project is on track." ) - print(email_sender.run()) # Expected output: 'Email sent successfully.' + assert email_sender.run() == "Email sent successfully." ``` ## Next Steps -We highly recommend you explore the resources in the [Pydantic is all you need](/core-framework/tools/custom-tools/pydantic-is-all-you-need) section. \ No newline at end of file +We highly recommend you explore the resources provided in the [Pydantic is all you need](/core-framework/tools/custom-tools/pydantic-is-all-you-need) section. \ No newline at end of file diff --git a/docs_new/core-framework/tools/custom-tools/pydantic-is-all-you-need.mdx b/docs_new/core-framework/tools/custom-tools/pydantic-is-all-you-need.mdx index 46e0a0dc..ea5e28c3 100644 --- a/docs_new/core-framework/tools/custom-tools/pydantic-is-all-you-need.mdx +++ b/docs_new/core-framework/tools/custom-tools/pydantic-is-all-you-need.mdx @@ -20,7 +20,7 @@ To really understand why it's such a game changer, we recommend watching this vi ## Learn more -To take your tools to the next level, we recommend the following resources: +To take your tools to the next level, we highly recommend the following resources: - [Pydantic Models Documentation](https://docs.pydantic.dev/latest/concepts/models/) - [Instructor Concepts](https://python.useinstructor.com/concepts/) diff --git a/docs_new/core-framework/tools/openapi-schemas.mdx b/docs_new/core-framework/tools/openapi-schemas.mdx new file mode 100644 index 00000000..b492b7c8 --- /dev/null +++ b/docs_new/core-framework/tools/openapi-schemas.mdx @@ -0,0 +1,116 @@ +--- +title: "OpenAPI Schemas" +description: "Convert OpenAPI schemas into tools." +icon: "brackets-curly" +--- + +Agency allows you to easily convert OpenAPI schemas into tools so your agents can interact with any external APIs. For example, by adding the Google Calendar API schema, your agent will be able to create, update, delete, and retrieve events from Google Calendar. + + +It is still recommended to create custom tools and wrap each API call into a `BaseTool` class, even if you have the OpenAPI schema. OpenAPI schemas allow you to get started quickly, however, for production, you might want to add some custom data validation, error handling, data processing or even combine multiple API calls into a single tool. + + +## How to find OpenAPI schemas + +The recommended way to create OpenAPI schemas is to use [Actions GPT](https://chatgpt.com/g/g-TYEliDU6A-actionsgpt). Simply ask it to create a schema for the API you want to use and which actions you want to perform. + +**If your API is public and well known**, it should be able to create a schema for you on the first try, without any extra documentation. + +``` +Create a schema for the Google Calendar API and include the following actions: create, update, delete, and get events. +``` + +**If your API is public but not well known**, we recommend searching for the API documentation manually and then sending a link to your API into the prompt: + +``` +Create a schema for the following API: https://api.example.com/openapi.json and include the following actions: create, update, delete, and get events. +``` + +**If you your API is private**, you can attach your API documentation in a file: + +``` +Create a schema for the API documentation attached in the file. Include the following actions: create, update, delete, and get events. +``` + +## How to use OpenAPI schemas + +Below are the two ways to use OpenAPI schemas in your agents: + +#### Option 1: Using the `schemas_folder` + +The first way to integrate OpenAPI schemas is by placing all your OpenAPI schema files in a folder, and then initializing your agent with the `schemas_folder` parameter. Agency Swarm will then automatically scan this folder and convert any OpenAPI schemas it finds into `BaseTool` instances. + +```python +from agency_swarm import Agent + +agent = Agent( + name='MyAgent', + schemas_folder='schemas', + api_params={'api_schema.json': {'param1': 'value1'}}, + api_headers={'api_schema.json': {'Authorization': 'Bearer token'}} +) +``` + +In this example: + +- `schemas_folder`: Directory where your OpenAPI schema files are stored. +- `api_params`: Extra parameters for specific schemas. +- `api_headers`: Custom headers for API calls, like authentication tokens. + + + +#### Option 2: Using the ToolFactory Class + +Alternatively, you can use the `ToolFactory` class to convert OpenAPI schemas from local files or URLs. + +```python +from agency_swarm.tools import ToolFactory + +tools = ToolFactory.from_openapi_schema( + "", + headers={'api_schema.json': {'Authorization': 'Bearer token'}}, + params={'api_schema.json': {'param1': 'value1'}}, + strict=False +) +``` + + +```python +from agency_swarm.tools import ToolFactory + +with open("schemas/api_schema.json") as f: + tools = ToolFactory.from_openapi_schema(f.read()) +``` + + + +```python +from agency_swarm.tools import ToolFactory +import requests + +response = requests.get("https://api.example.com/openapi.json") +tools = ToolFactory.from_openapi_schema(response.json()) +``` + + +Argument descriptions: + +- `schema`: The OpenAPI schema to convert. +- `headers`: Custom headers for API calls, like authentication tokens. +- `params`: Extra parameters for specific schemas. +- `strict`: Whether to use strict OpenAI mode. + +To add your tools to your agent with the 2nd option, simply pass the `tools` list to your agent: + +```python +agent = Agent( + name='MyAgent', + tools=tools +) +``` + +With this approach, you have more control over the tools you are adding to your agent, and you can still modify the `ToolConfig` of each tool. See the [ToolConfig documentation](/core-framework/tools/custom-tools/configuration) for more information. + + +With any of these methods, Agency still converts your schemas into PyDantic models, so your agents will perform type checking on all API parameters **before** making API calls, reducing errors and improving reliability. + \ No newline at end of file diff --git a/docs_new/mint.json b/docs_new/mint.json index e7eb3760..62c5d09b 100644 --- a/docs_new/mint.json +++ b/docs_new/mint.json @@ -98,8 +98,7 @@ "core-framework/tools/custom-tools/configuration" ] }, - - "core-framework/tools/tool-factory" + "/core-framework/tools/openapi-schemas" ] }, "core-framework/agents", @@ -112,7 +111,6 @@ "pages": [ "additional-features/asynchronous-execution", "additional-features/shared-state", - "additional-features/openapi-schemas", "additional-features/few-shot-examples", "additional-features/output-validation", "additional-features/streaming",