In this guide, you can learn how to convert an OpenAPI 3.0 document to agent tools. Use the agentengine agent create-tool command to compile the document into connector files. When you build your agent, the Atlas Agent Engine creates the connector from those files so that your agent can call the OpenAPI agent tools.
Note
The agentengine agent create-tool command is experimental. The flags, output format, and generated file formats might change without notice.
About This Task
The agentengine agent create-tool command generates two files in the folder you specify:
tool_defs.yaml: The catalog of tools that the command compiles from the OpenAPI document. The catalog includes tool names, input schemas, and the HTTP method and path for each operation.tool.yaml: The authoring file that binds the catalog to your API endpoint and credential, and selects which tools your agent exposes. The command scaffolds this file. When you regenerate the catalog, the command doesn't overwrite your edits to the file.
When the agent calls a connector tool, the tool runs in an isolated Tool Pod. The call goes through the same Orchestration Engine approval gate as other tools. Credential values are never written to the generated files, and the files reference the name of a workspace secret instead.
You must pass exactly one of the following inputs to the command:
--spec: Compiles an OpenAPI 3.0 document into a catalog and scaffolds atool.yamlfile if none exists. The value can be a local file or an HTTPS URL.--tool-defs: Scaffolds only thetool.yamlfile for an existing local catalog. The command doesn't rewrite the catalog.--config: Regenerates a locally owned catalog from thetool.yamlfile that declares thesource.specfield.
To view all flags, see the agentengine_create-tool CLI documentation.
Before You Begin
Before you begin, ensure that you have the following resources:
The
agentengineCLI installed and authenticated. To learn more, see Install and Authenticate.A valid agent project with an
agent.yamlfile. To learn more, see Create a Project.Docker running locally.
An OpenAPI 3.0 document, either a local file or an HTTPS URL, for the REST API that you want to call.
An authentication bearer token for the REST API.
Steps
Generate the connector files.
From your agent project directory, run the agentengine agent create-tool command with the connector name and the --spec flag. The following example compiles a specification into the connectors/orders folder and configures bearer token authentication:
agentengine agent create-tool orders \ --spec <openapi-document-url-or-path> \ --out-dir connectors/orders \ --auth bearerThe command names the workspace secret for the bearer token after the connector. For the orders connector, the secret name is ORDERS_TOKEN. If you omit the --auth flag, the command generates the auth block in the tool.yaml file from the security schemes that the document declares.
The command uses the first non-templated server in the document as the base URL. If the document doesn't declare a server, or if you want to call a different endpoint, add the --base-url flag to the command.
If the document contains operations that the generator can't represent, the command fails and prints the name of the operation. To exclude those operations instead, add the --skip-unsupported flag to the command. The command prints every skipped operation and records it in the catalog.
Review the tool.yaml file.
Open the connectors/orders/tool.yaml file. The comment at the top of the file names the endpoint destination and the credential secret that your agent must declare.
To limit which tools your agent can call, list specific tool names in the expose.allow field. If you omit this list, the agent can call every generated tool. The following example shows a tool.yaml file that exposes one tool:
name: orderstool_defs: tool_defs.yamlsource: type: openapi base_url: https://api.example.comexpose: allow: [orders_getOrder]auth: bearer: ORDERS_TOKENStore the API credential as a workspace secret.
Create a secret with the name that the auth block in the tool.yaml file references. In this example, the secret name is ORDERS_TOKEN. To learn how to store secrets, see Provision Cloud Secrets.
Grant the tool sandbox access to the secret and the API.
The comment at the top of the tool.yaml file reports requirements only and doesn't grant any permissions. In your agent.yaml file, add the secret to the sandboxes.tool.secrets field and the API hostname to the sandboxes.tool.network.egress field. Keep the secrets and destinations that your other tools already use. The following example adds the ORDERS_TOKEN secret and the api.example.com host:
sandboxes: tool: secrets: - ORDERS_TOKEN network: egress_mode: allow_list egress: - fqdn: api.example.com ports: [443]Replace api.example.com and 443 with the hostname and port of the base URL in your tool.yaml file. To learn more, see Agent YAML Schema and Manage Network Egress Policies.
Build and deploy your agent.
Build and deploy your agent as usual. The build creates the connector from your tool.yaml and tool_defs.yaml files. To learn more, see Build the Agent Image.
Behavior and Limitations
Review the following behavior and limitations for generated connector tools:
The base URL in the
tool.yamlfile applies to every operation. The generator ignores path-level and operation-levelserversentries in the OpenAPI document.The generator reads local files. The CLI downloads documents that you specify by URL under the platform transport policy.
The generator supports bearer tokens, API keys, and HTTP Basic authentication. The following are outside the generation boundary:
OAuth token acquisition and refresh
Interactive or session login
Per-request signing
mTLS-only authentication
Multipart file uploads
A connector truncates responses larger than 200,000 decoded bytes and marks them as truncated.
Each tool invocation times out after 30 seconds.
Learn More
See the following documentation to learn more about OpenAPI tools:
agentengine_create-tool