Skip to main content
OpenAPI tools provide a quick way to consume remote web services that include an OpenAPI specification file. For watsonx Orchestrate to use an OpenAPI tool, the following conditions must be met:
  • Endpoints must accept and return JSON.
  • The specification must include a servers block with exactly one URL. This URL cannot contain parameterization.
  • Each path that exposes an endpoint must include an operationId. This value becomes the tool name. For best results, use snake_case for operationId values.
  • Each path that exposes an endpoint must include a description. The agent uses this description to decide when to use the tool and what the tool does.
  • The OpenAPI version must be 3.0.
Here is an example of a minimal OpenAPI specification:
YAML
servers:
- url: mytoolserver
paths:
/:
   get:
      operationId: my_tool
      description: The description of the tool that clearly explains it's purpose to an llm
      requestBody:
         ...
      responses:
         ...

​
Importing OpenAPI based tools

To import an OpenAPI tool, run:
BASH
orchestrate tools import -k openapi -f <file-path> -a <app-id>

​
Additional features of OpenAPI tools

OpenAPI tools are fully compatible with the watsonx Orchestrate Connections framework. A connection represents a dependency on an external service and provides a way to associate credentials with a tool. Supported authentication methods include Basic, Bearer, API Key, OAuth, and IDP SSO flows.Connections are referenced using an application ID (app_id), which serves as the unique identifier for a connection. Each OpenAPI tool can be associated with only one connection app_id.For more information, see Connections.
OpenAPI tools are one of the two tool types that support asynchronous operations. These tools perform an action and then poll a status endpoint until the long-running process completes. Unlike synchronous tools, asynchronous tools can exceed the 40-second execution timeout in the UI.To create an asynchronous OpenAPI tool, your OpenAPI specification must include a callbackUrl header parameter as defined in the OpenAPI Callback Specification.
  • Use callbackUrl exactly as the header parameter name; other names are not supported.
  • The only supported content type for the callback response is application/json.
YAML
servers:
  - url: mytoolserver
paths:
/:
   post:
      operationId: myTool
      summary: myName
      description: the description
      parameters:
        - in: header
          name: callbackUrl
          description: The callback URL
          required: true
          schema:
            type: string
      requestBody:
         ...
      callbacks:
        callback:
          '{$request.header.callbackUrl}':
            post:
              requestBody:
              ...
              responses:
              ...

​
Limitations and considerations

Using OpenAPI tools with your agents is straightforward, but default OpenAPI specifications often perform poorly as agent tools for the following reasons. If any of these issues apply to your use case, consider adjusting your OpenAPI specification or using Python tools instead.
  1. OpenAPI endpoints are designed for developers, not agents.
    • Developers can rely on context from other endpoints and external documentation to understand an endpoint’s purpose. Agents cannot. All necessary context must be included within the endpoint itself.
    • OpenAPI endpoints often include large sets of input arguments. In contrast, tools should have focused inputs and outputs that resolve a single task. For more information, see Designing agents and tools for best performance .
  2. Agents require a highly descriptive semantic layer.
  3. OpenAPI tools do not support x-ibm- extensions used in older watsonx Orchestrate Skills.