Agents

OpenAPI tools

Import a Swagger or OpenAPI document once so the agent can reach a whole API, and follow the import through its three states.

An OpenAPI tool is one imported Swagger or OpenAPI document. The whole API becomes a single row in the workspace tool library, and the agent finds the right operation inside it during a conversation. Import the document once instead of hand building one webhook tool per operation.

What you need

  • A Swagger or OpenAPI document as JSON, either as a file or at a public HTTPS URL. YAML is not accepted.
  • The base URL the API is actually served from. It is required, and it is where every call goes.
  • Membership of the workspace. Importing needs no further permission.
  • Any credential the API requires, saved first as an auth connection.

Steps

Step 1: Open the import form

On an agent, go to the Tools tab and press Add Tool, then pick the OpenAPI tab. The same dialog is on the Tool Library page, described there as "Create and manage reusable tools for your workspace."

Step 2: Name the tool

Name is required, unique in the workspace and capped at 120 characters. It is the row you will see in the library, so name it after the API rather than after one of its operations.

Step 3: Give the document

Two pill tabs choose the source, and you use exactly one of them.

Upload Json opens a drop zone reading "Drop a file here or click to browse" with "Up to 5 MB per file" underneath. The file is read in your browser before anything is sent, so a bad file is caught immediately.

URL takes a public HTTPS URL to the document. EchoNova fetches it under the same rules as any outbound call: HTTPS only, public hosts only, JSON only, 5 MB maximum and a 30 second timeout.

Step 4: Set the base URL

Base URL is required. The hint under it says why: "Base URL is required — the portal calls the API with it." The document's own servers entry is kept as a fallback, but the value you type is what every call uses, so a document whose servers block points at a staging host does not quietly send traffic there.

The value must be a full public HTTPS URL, matching the placeholder https://api.example.com. A trailing slash is stripped.

Step 5: Press Add

EchoNova reads the document and creates the library row, which lands with an endpoint count chip and a status pill.

Get it right

The agent finds an operation by matching what the caller said against the operation's description, so that description is what decides whether the operation is ever reached. Write it in the caller's words, not the API's.

Recommended

Check where a customer's order is. Use when the caller asks about delivery, a
missing parcel, a tracking number, or when an order will arrive.

Less effective

GET /v2/orders/{orderId}/shipment-status

What happens next

The tool appears in Workspace tools with its API title, an endpoint count and a status pill. Select it on an agent the same way as any workspace tool, and the agent can reach its operations from the next conversation onwards.

Open the row to see what was imported. The detail sheet lists every operation on its Endpoints tab, in a rail on the left, and shows the picked operation's parameters and request body on the right. That list, the per-operation auth modes and the enable switch are covered on OpenAPI tool operations.

The three import states

State Pill What it means
importing Importing The tool is still being prepared and the agent cannot reach its operations yet
ready Ready The agent can reach the operations
failed Failed The import broke. The detail sheet shows Import failed with the reason

An import is usually Ready by the time the dialog closes. While any tool in the list still shows Importing, the portal refreshes the list on its own until none do. A tool can also turn Failed after it first appeared, and the reason is shown on the row.

An import can also fail before any row is created, which is the common case: a document that cannot be read, a URL that does not answer, or a selection above the operation limit. Nothing is saved then, and the dialog shows the error.

How the agent reaches an operation

An imported API is not put in front of the agent as a list of operations. Webhook, integration and system tools are in front of it on every turn; imported operations are not. Each turn the agent searches your imported operations for the ones closest to what the caller just said, keeps the top 5, and ignores anything scoring below 0.5.

That is what makes a large API workable. A document with two hundred operations would drown the agent if all of them were listed, so it sees a handful of relevant ones instead, and asks a clarifying question when nothing clears the threshold.

It also changes what a missed call means. A webhook tool that never fires has a wording problem in its description. An imported operation has to win a search first, so it can also miss because the caller's phrasing appears nowhere in the operation's description.

Database questions are searched in the same pass, so an agent with both a database and an imported API is choosing between them each turn.

Testing what the agent would reach

Open the tool from an agent's Tools tab, then open its Tests tab. Type what a caller might say and press Run. The hint explains the point: "Type what a caller might say. This runs the same semantic search the agent runs each time, so you can detect an incorrect match before launch."

Results are ranked with a score, which is a similarity rather than a probability. Nothing above the threshold is a result too: "There is no match above the specified minimum threshold. The agent will ask a clarifying question instead of calling an endpoint."

Two conditions have to hold or there is nothing to search. The tool must be Ready, and it must be selected on the agent you are testing from. The standalone Tool Library page has no agent in scope, so the test is offered on an agent's Tools tab only.

Updating a changed document

An imported tool keeps the operations it was created with. A document that gains, loses or renames an operation needs a fresh import:

  1. Import the new document as a new tool.
  2. Select it on the agents that need it.
  3. Check it on its Tests tab.
  4. Delete the old row.

Deleting removes the tool and its operations and unselects it from every agent that used it, so do it last. The auth connection is reusable and is not deleted with the tool.

Two changes do not need a fresh import: switching an operation off and on again, and changing the credential the tool uses.

Limits

Limit Value Applies to
Document size 5 MB Uploaded files and URL fetches alike
Document format JSON object OpenAPI 3.x and Swagger 2.0
URL fetch timeout 30 seconds URL sources
URL scheme HTTPS only, public hosts only URL sources and the base URL
Operations per import 2000 Refused above it, before anything is saved
Tool name 120 characters, unique in the workspace Import
Tool description 500 characters Import
Operations reached per turn Top 5, score threshold 0.5 Shared with database questions
Base URL Fixed at import A different host means a fresh import

Troubleshooting

"The OpenAPI file must be 5 MB or smaller."

The file picker refuses anything larger before it is read. A document that big usually carries generated examples. Export it without them, or import a trimmed document covering the operations the agent needs.

"Choose a JSON OpenAPI document." or "The selected file is not a valid OpenAPI object."

The file is not JSON, or it reads as something other than a JSON object, such as an array. Convert a YAML document to JSON first.

"The URL did not return a JSON OpenAPI document"

The URL answered, but the body was not a JSON object. Point at the raw document rather than at a documentation page that renders it.

"Fetching the OpenAPI document failed with status 404"

The URL answered with a non-success status, which appears in the message. The URL is fetched without any credentials, so a document behind authentication has to be uploaded as a file instead.

"Fetching the OpenAPI document failed or timed out"

The host did not answer inside 30 seconds, or it is not publicly reachable over HTTPS.

"Base URL is required"

The field was empty or whitespace. An API cannot be imported without knowing where to call it.

"This import would persist 2400 operations, which exceeds the 2000-operation limit"

The document is larger than one tool may hold. Import a document that covers fewer paths. Importing a subset of a document's operations is not available from the portal today.

The row shows Failed

Open it and read the reason under Import failed. The tool stays in the library and stays selectable, but the agent cannot reach any of its operations. Fix the document and import it again.

FAQ

Does one import equal one tool?

Yes. One document becomes one library row holding the whole API, and a large document cannot outgrow that row.

Are all the operations imported?

Yes. Importing a subset of a document's operations is not available from the portal today. To stop the agent calling an operation after the import, switch that operation off.

Can the agent call an API over plain HTTP?

No. The base URL, the document URL and every outbound call are HTTPS only and public hosts only.

Is the document kept?

The operations EchoNova read are kept, with their parameters and request body fields, so the detail sheet can show a contract without going back to the document. Deleting the tool removes them.

Why does the agent ask a clarifying question instead of calling the API?

Nothing cleared the threshold for that turn. Run the same sentence on the tool's Tests tab. If it scores below the threshold, the operation's description is the thing to change.

Can I change the base URL later?

The base URL is fixed when you import. To move the API to a different host, import the document again as a new tool, select it on the agents that need it, and delete the old row.