This article is auto-synced from its in-app version in Tai.
An agent's REST API channel lets your own systems call the agent over HTTP and get back a structured JSON answer, in a shape you define in a versioned contract.
When you'd use this
Set it up when a backend, a scheduled job or another system needs one structured answer from an agent rather than a chat — for example, a booking system that asks a risk-check agent for a typed verdict on every new booking. You set up the agent here in the Workbench; your integration team then calls it as described in the Agent REST API guide.
Steps
Make the agent a Company agent
API keys and OAuth clients can only call a Company agent. If the agent is Personal, a Company Admin opens it and clicks Release to company. If its REST API channel is on but doesn't yet accept both API keys and OAuth clients, the confirmation offers to add them — leave that ticked.
Switch on the channel
In the Workbench sidebar, click Agents and open the agent.
On the Configuration tab, go to Channels and switch on REST API.
Under Accepted authentication, choose who may call the agent. A server-to-server integration needs API key or OAuth client; both are on by default for a new agent. Tick Workbench user or TripBuilder FIT (Federated Identity Token) only if signed-in users should call the agent directly too.
Draft and publish a contract
A contract version pins the input parameters an integration sends and the JSON Schema its answer satisfies.
Under Contract versions, click New draft version.
Under Input parameters, click Add parameter for each input. Give it a Name (the key integrations send), a Label and a Type. Required is ticked for a new parameter; untick it for an optional input. A Description is shown to integrators and on the Test API tab, but not to the agent: it sees each input's label, name and value, so explain an input in its label or in the system prompt.
Under Output JSON Schema, replace the default
{"type": "object"}with the shape the agent's answer must satisfy. TAI checks every answer against it and gives the agent one chance to correct an answer that doesn't match.Click Publish on the version and confirm.
Click Save changes. Publishing only takes effect when you save; until then, Undo takes it back.
A published version is frozen: its parameters and schema can no longer be edited. You can keep several drafts at once, and click Remove on a draft you no longer need.
Test a call
Open the agent's Test API tab.
Choose the Contract version, fill in the inputs, and click Run.
Check the Result: the agent's JSON answer, the Version used and how long the call took.
The tab tests the agent as last saved, not unsaved edits. If it shows a notice instead of the form, save the agent with the channel switched on and a published version, and make sure the agent is active.
Hand it over to your integration
Your integration needs three things:
The agent's Agent ID, shown on the agent's page with a copy button.
The contract version to pin, for example
1.An API key or OAuth client with this agent under Allowed agents. If you narrow its Allowed channels or Permissions, keep REST API and Invoke agents; left empty, both are allowed. A Company Admin creates it under Settings → API Keys.
The Agent REST API guide covers the rest: authenticating, calling the agent, long-running runs and error codes.
Change a published contract
To change what the agent takes or returns, publish a new version and retire the old one:
Under Contract versions, click New draft from v1 (named after your latest published version). The draft starts as a copy of it.
Make your changes and click Publish.
If the new version isn't compatible with the old one — for example, it adds a required input — click Deprecate on the old version and pick a Sunset date, the last day it accepts calls. Saving refuses an incompatible new version while the old one is still Active.
Click Save changes.
Integrations pinned to a deprecated version keep working until the sunset date. Every answer from it carries Deprecation and Sunset headers and names the version to move to, and your company's admins get an email within about a week of one of your API keys calling it, and again as the sunset date approaches. After the sunset date, a call pinned to it fails.
Switch the channel off
Under Configuration → Channels, switch off REST API and click Save changes. New calls are refused straight away. Calls that were queued but hadn't started are stopped and not billed; a call already running finishes its current step, which is billed.
Tips and limits
Browsing agents is open to all users; switching on the channel, publishing and deprecating contract versions requires permission to edit the agent — the Company Admin role for your company's agents.
Draft versions can never be called. Only a published version answers: Active, or Deprecated until its sunset date.
Version numbers only go up: a draft can be published only if its number is higher than every version already published.
Once saved, a publish or a deprecation can't be undone. Check the Sunset date before you save.
Built-in agents are set up by Nezasa: you can't change their channels or contracts.
Test calls are real calls: they run the agent and are billed like any other call.
To give one agent its own request limit, set it under Settings → Rate limits. The agent appears there once its REST API channel is switched on and saved with a contract version.
Related