Skip to content

Commit

Permalink
Finished openapi schemas page
Browse files Browse the repository at this point in the history
  • Loading branch information
VRSEN committed Dec 18, 2024
1 parent bdc479c commit f7a4bab
Show file tree
Hide file tree
Showing 6 changed files with 155 additions and 87 deletions.
71 changes: 0 additions & 71 deletions docs_new/additional-features/openapi-schemas.mdx

This file was deleted.

29 changes: 29 additions & 0 deletions docs_new/core-framework/agents.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -272,3 +272,32 @@ from AgentName import AgentName

agent = AgentName()
```

Agency Swarm comes with several built-in tools to enhance agent capabilities:

<Accordion title="Code Interpreter" icon="code">
- **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
)
```
</Accordion>

<Accordion title="File Search" icon="magnifying-glass">
- **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
)
```
20 changes: 8 additions & 12 deletions docs_new/core-framework/tools/custom-tools/best-practices.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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.

Expand All @@ -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.

Expand All @@ -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
Expand All @@ -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):
Expand Down Expand Up @@ -136,7 +132,7 @@ class CompositeTool(BaseTool):
```


### Testing Tools
### Include a Test Case

Include test cases at the bottom of each tool file.

Expand All @@ -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.
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.
Original file line number Diff line number Diff line change
Expand Up @@ -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/)
Expand Down
116 changes: 116 additions & 0 deletions docs_new/core-framework/tools/openapi-schemas.mdx
Original file line number Diff line number Diff line change
@@ -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.

<Tip>
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.
</Tip>

## 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(
"<your OpenAPI schema here>",
headers={'api_schema.json': {'Authorization': 'Bearer token'}},
params={'api_schema.json': {'param1': 'value1'}},
strict=False
)
```

<Accordion title="Converting from a Local Schema File">
```python
from agency_swarm.tools import ToolFactory

with open("schemas/api_schema.json") as f:
tools = ToolFactory.from_openapi_schema(f.read())
```
</Accordion>

<Accordion title="Converting from a Remote Schema URL">
```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())
```
</Accordion>

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.

<Info>
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.
</Info>
4 changes: 1 addition & 3 deletions docs_new/mint.json
Original file line number Diff line number Diff line change
Expand Up @@ -98,8 +98,7 @@
"core-framework/tools/custom-tools/configuration"
]
},

"core-framework/tools/tool-factory"
"/core-framework/tools/openapi-schemas"
]
},
"core-framework/agents",
Expand All @@ -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",
Expand Down

0 comments on commit f7a4bab

Please sign in to comment.