mirror of
https://github.com/google/adk-docs.git
synced 2026-09-14 16:16:59 +08:00
Joe Fernandez
f12068a4bb
* docs: add language support tags to pages - replace img.shield tags - add language support tags where missing * update Agents page with general tags * update language and version tagging - response to review comments - rename css styles to avoid style name conflicts * add tags to api-server page
85 lines
5.1 KiB
Markdown
85 lines
5.1 KiB
Markdown
# Integrate REST APIs with OpenAPI
|
|
|
|
<div class="language-support-tag">
|
|
<span class="lst-supported">Supported in ADK</span><span class="lst-python">Python v0.1.0</span>
|
|
</div>
|
|
|
|
ADK simplifies interacting with external REST APIs by automatically generating callable tools directly from an [OpenAPI Specification (v3.x)](https://swagger.io/specification/). This eliminates the need to manually define individual function tools for each API endpoint.
|
|
|
|
!!! tip "Core Benefit"
|
|
Use `OpenAPIToolset` to instantly create agent tools (`RestApiTool`) from your existing API documentation (OpenAPI spec), enabling agents to seamlessly call your web services.
|
|
|
|
## Key Components
|
|
|
|
* **`OpenAPIToolset`**: This is the primary class you'll use. You initialize it with your OpenAPI specification, and it handles the parsing and generation of tools.
|
|
* **`RestApiTool`**: This class represents a single, callable API operation (like `GET /pets/{petId}` or `POST /pets`). `OpenAPIToolset` creates one `RestApiTool` instance for each operation defined in your spec.
|
|
|
|
## How it Works
|
|
|
|
The process involves these main steps when you use `OpenAPIToolset`:
|
|
|
|
1. **Initialization & Parsing**:
|
|
* You provide the OpenAPI specification to `OpenAPIToolset` either as a Python dictionary, a JSON string, or a YAML string.
|
|
* The toolset internally parses the spec, resolving any internal references (`$ref`) to understand the complete API structure.
|
|
|
|
2. **Operation Discovery**:
|
|
* It identifies all valid API operations (e.g., `GET`, `POST`, `PUT`, `DELETE`) defined within the `paths` object of your specification.
|
|
|
|
3. **Tool Generation**:
|
|
* For each discovered operation, `OpenAPIToolset` automatically creates a corresponding `RestApiTool` instance.
|
|
* **Tool Name**: Derived from the `operationId` in the spec (converted to `snake_case`, max 60 chars). If `operationId` is missing, a name is generated from the method and path.
|
|
* **Tool Description**: Uses the `summary` or `description` from the operation for the LLM.
|
|
* **API Details**: Stores the required HTTP method, path, server base URL, parameters (path, query, header, cookie), and request body schema internally.
|
|
|
|
4. **`RestApiTool` Functionality**: Each generated `RestApiTool`:
|
|
* **Schema Generation**: Dynamically creates a `FunctionDeclaration` based on the operation's parameters and request body. This schema tells the LLM how to call the tool (what arguments are expected).
|
|
* **Execution**: When called by the LLM, it constructs the correct HTTP request (URL, headers, query params, body) using the arguments provided by the LLM and the details from the OpenAPI spec. It handles authentication (if configured) and executes the API call using the `requests` library.
|
|
* **Response Handling**: Returns the API response (typically JSON) back to the agent flow.
|
|
|
|
5. **Authentication**: You can configure global authentication (like API keys or OAuth - see [Authentication](/adk-docs/tools/authentication/) for details) when initializing `OpenAPIToolset`. This authentication configuration is automatically applied to all generated `RestApiTool` instances.
|
|
|
|
## Usage Workflow
|
|
|
|
Follow these steps to integrate an OpenAPI spec into your agent:
|
|
|
|
1. **Obtain Spec**: Get your OpenAPI specification document (e.g., load from a `.json` or `.yaml` file, fetch from a URL).
|
|
2. **Instantiate Toolset**: Create an `OpenAPIToolset` instance, passing the spec content and type (`spec_str`/`spec_dict`, `spec_str_type`). Provide authentication details (`auth_scheme`, `auth_credential`) if required by the API.
|
|
|
|
```python
|
|
from google.adk.tools.openapi_tool.openapi_spec_parser.openapi_toolset import OpenAPIToolset
|
|
|
|
# Example with a JSON string
|
|
openapi_spec_json = '...' # Your OpenAPI JSON string
|
|
toolset = OpenAPIToolset(spec_str=openapi_spec_json, spec_str_type="json")
|
|
|
|
# Example with a dictionary
|
|
# openapi_spec_dict = {...} # Your OpenAPI spec as a dict
|
|
# toolset = OpenAPIToolset(spec_dict=openapi_spec_dict)
|
|
```
|
|
|
|
3. **Add to Agent**: Include the retrieved tools in your `LlmAgent`'s `tools` list.
|
|
|
|
```python
|
|
from google.adk.agents import LlmAgent
|
|
|
|
my_agent = LlmAgent(
|
|
name="api_interacting_agent",
|
|
model="gemini-2.0-flash", # Or your preferred model
|
|
tools=[toolset], # Pass the toolset
|
|
# ... other agent config ...
|
|
)
|
|
```
|
|
|
|
4. **Instruct Agent**: Update your agent's instructions to inform it about the new API capabilities and the names of the tools it can use (e.g., `list_pets`, `create_pet`). The tool descriptions generated from the spec will also help the LLM.
|
|
5. **Run Agent**: Execute your agent using the `Runner`. When the LLM determines it needs to call one of the APIs, it will generate a function call targeting the appropriate `RestApiTool`, which will then handle the HTTP request automatically.
|
|
|
|
## Example
|
|
|
|
This example demonstrates generating tools from a simple Pet Store OpenAPI spec (using `httpbin.org` for mock responses) and interacting with them via an agent.
|
|
|
|
???+ "Code: Pet Store API"
|
|
|
|
```python title="openapi_example.py"
|
|
--8<-- "examples/python/snippets/tools/openapi_tool.py"
|
|
```
|