OpenAPI Tools Integration

Integrate external REST APIs dynamically using OpenAPI specifications. This integration enables automatic generation of tools from API definitions, allowing AI agents to invoke external services in real time.

Overview

OpenAPI Tools provide a powerful mechanism for dynamic tool generation. By supplying a valid OpenAPI specification (in JSON format), the system parses the spec and exposes selected API operations as callable tools for agents.

Key Benefits

Automatic Tool Generation from OpenAPI 3.0/3.1 specs
Fine-grained Control via filters for methods, paths, tags, or operation IDs
Flexible Authentication options (Bearer, API Key, Basic Auth, etc.)
Customizable Naming of generated tools for optimal AI usability

Use Cases

Access external business services (e.g., CRM, ERP, analytics APIs)
Query public APIs (e.g., weather, finance, shipping)
Automate custom workflows via internal APIs

Configuration Reference

Below is a complete list of environment variables and their descriptions used to configure the OpenAPI tool generation:

Variable	Name	Description	Required	Default
`OPENAPI_INTEGRATION_CODE`	Integration Code	Unique integration code to distinguish multiple OpenAPI specifications attached to the same agent. Required when using more than one OpenAPI source per agent.	❌	—
`OPENAPI_URL`	OpenAPI Specification URL	URL to the OpenAPI specification file (JSON format). Supports HTTP/HTTPS URLs and `file://` URLs. `{VAR_NAME}` placeholders are resolved from environment variables at runtime.	✅	—
`OPENAPI_BASE_URL`	API Base URL	Base URL for the API endpoints. Used as the root URL for all API calls when servers are not specified in the OpenAPI spec.	✅	—
`OPENAPI_AUTH_TYPE`	Authentication Type	Type of authentication to use. Allowed values: `none`, `bearer`, `basic`, `api_key`, `api_key_query`, `custom`. If not specified, authentication is auto-detected from the OpenAPI spec.	❌	—
`OPENAPI_BEARER_TOKEN`	Bearer Token	Bearer token for Bearer authentication. Required when `auth_type` is `bearer`.	❌	—
`OPENAPI_API_HEADER`	API Key Header Name	Header name for API key authentication. Used when `auth_type` is `api_key`.	❌	`x-api-key`
`OPENAPI_API_KEY_VALUE`	API Key Value	API key value for API key authentication. Required when `auth_type` is `api_key` or `api_key_query`.	❌	—
`OPENAPI_API_QUERY_PARAM`	API Key Query Parameter	Query parameter name for API key authentication via query string. Used when `auth_type` is `api_key_query`.	❌	`key`
`OPENAPI_USERNAME`	Basic Auth Username	Username for Basic authentication. Required when `auth_type` is `basic`.	❌	—
`OPENAPI_PASSWORD`	Basic Auth Password	Password for Basic authentication. Required when `auth_type` is `basic`.	❌	—
`OPENAPI_VERIFY_SSL`	SSL Verification	Whether to verify SSL certificates during HTTPS requests. Allowed values: `true`, `false`.	❌	`false`
`OPENAPI_TIMEOUT_SEC`	Request Timeout	Request timeout in seconds. If not specified, no timeout is applied.	❌	—
`OPENAPI_OPERATIONS_IDS`	Operation IDs Filter	Comma-separated list of operation IDs to include. Only endpoints with these operation IDs will be generated as tools.	❌	—
`OPENAPI_PATHS`	Path Patterns Include	Comma-separated list of path patterns to include. Only endpoints whose paths contain these patterns will be generated.	❌	—
`OPENAPI_EXCLUDE_PATHS`	Path Patterns Exclude	Comma-separated list of path patterns to exclude. Endpoints whose paths contain these patterns will be excluded.	❌	—
`OPENAPI_TAGS`	Tags Include Filter	Comma-separated list of tags to include. Only endpoints tagged with these tags will be generated.	❌	—
`OPENAPI_EXCLUDE_TAGS`	Tags Exclude Filter	Comma-separated list of tags to exclude. Endpoints tagged with these tags will be excluded.	❌	—
`OPENAPI_METHODS`	HTTP Methods Filter	Comma-separated list of HTTP methods to include. Allowed values: `get`, `post`, `put`, `patch`, `delete`. Only endpoints using these methods will be generated.	❌	—
`OPENAPI_NAME_TRANSFORMER`	Name Transformer Rule	Comma-separated list of transformations to apply to OpenAPI operation names when generating tool names. Supported transformations: `capitalize` (First letter uppercase), `pascal` (PascalCase), `camel` (camelCase), `snake` (snake_case), `kebab` (kebab-case), `upper` (UPPERCASE), `lower` (lowercase), `title` (Title Case), `s/pattern/replace/flags` (regex substitution with sed-like syntax). Transformations are applied sequentially.	❌	—

Filtering Example

To restrict tool generation to specific paths, use the OPENAPI_PATHS variable. For example:

OPENAPI_PATHS=/dashboard/profile,/dashboard/channels

This setting will include only endpoints whose paths contain one of the specified patterns. It would match:

/v1/external/users/{user_id}/dashboard/profile
/v1/external/users/{user_id}/dashboard/channels

Filtering and Name Transformation Examples

When operationId is not explicitly defined in the OpenAPI spec, it is generated using the pattern:

f"{method}_{path.replace('/', '_').replace('{', '_').replace('}', '_')}"

For example, the path /dashboard/profile/v1/external/users/{user_id}/dashboard/profile with method get will generate:

get_dashboard_profile_v1_external_users__user_id__dashboard_profile_get

To make these names cleaner and more meaningful, you can apply transformations using the OPENAPI_NAME_TRANSFORMER variable. For instance:

s/^(.*?)_v[0-9]+.*$/\1/i,pascal

This rule will strip the version suffix and apply PascalCase, turning the above example into:

GetDashboardProfile

You can combine multiple transformations using commas, and they will be applied sequentially.

Syntax Reference

Transformers may include:

capitalize – Capitalize the first letter
pascal – Convert to PascalCase
camel – Convert to camelCase
snake – Convert to snake_case
kebab – Convert to kebab-case
upper – Convert to UPPERCASE
lower – Convert to lowercase
title – Convert to Title Case
s/pattern/replace/flags – Regular expression substitution (sed-style)
- pattern: a regular expression
- replace: replacement string (use \1, \2, etc. for capture groups)
- flags: optional regex flags (e.g., i for case-insensitive, g for global)

Example:

s/^(.*?)_v[0-9]+.*$/\1/i,pascal

This applies two transformers:

Remove version suffix using regex substitution (e.g., get_foo_v1_bar → get_foo)
Apply PascalCase transformation (get_foo → GetFoo)

Transformers are executed in the given order from left to right.

Summary

OpenAPI Tools integration extends your AI agents with powerful capabilities by turning any OpenAPI-compliant service into a usable toolset — with minimal configuration and full customization control.

Overview​

Key Benefits​

Use Cases​

Configuration Reference​

Filtering Example​

Filtering and Name Transformation Examples​

Syntax Reference​

Summary​