Skip to main content

Agents

In the API, an agent version is a workflow definition. Every save of an agent creates a new row with the same name and the next version. Calls by agent name run the live version. Calls by definition_id run exactly that version.

These endpoints need a Keycloak access token. API keys are not accepted. Applications call agents through the Agent API with a project key instead. See Authentication.

Create an agent version​

POST/workflow-definitions

Saves a new version of an agent. If no agent with this name exists in the project, it is version 1. Tool refs are resolved into full tool schemas when you save, so later changes to a connector's list of tools do not change a saved version.

Needs the developer or admin role on the project.

Body​

project_idstringrequired
The project.
namestringrequired
The agent's name. Calls by name use it.
descriptionstringoptional
What the agent is for.
stepsarrayrequired
One or more steps, run in order. The console creates agents with one step.
steps[].namestringrequired
The step's name. Later steps refer to it with input_from.
steps[].system_promptstringoptional
The step's instructions. The current date and time is added at run time.
steps[].modelstringoptional
The model reference to call. Leave it out only if a fallback external provider is set up.
steps[].input_fromstringoptional
Use the output of the named earlier step as this step's input, instead of the user's message.
steps[].toolsarrayoptional
Tool refs from GET /tools, such as connector:billing-api:get_invoice.
steps[].approvalstringoptional
policy (the default), always or never. See Human approval.
steps[].approval_timeout_secondsintegeroptional
How long a tool call waits for approval before it is rejected. Defaults to 3600.
steps[].kindstringoptional
For a workflow graph: llm (the default, a model step), branch, parallel, join or loop. See Workflow graphs.
steps[].nextstring or nulloptional
For a graph: the step after this one. null ends the path. A definition with any kind or next is a graph, and its first step is the entry.
steps[].conditionsarrayoptional
branch: up to 20 {"when": <condition>, "next": <step>}, tried in order. else_next is taken when none holds.
steps[].branchesarrayoptional
parallel: the first step of each lane, up to 8. join names the step where they meet.
steps[].combinestringoptional
join: text or json.
steps[].bodystringoptional
loop: the first step of the loop's path. With max_iterations (1 to 20) and an optional until condition.

Response fields​

idstringoptional
The new version's definition_id.
namestringoptional
The agent's name.
versionintegeroptional
The version number.
stepsarrayoptional
The steps as stored, with each tool resolved to ref and schema.
is_livebooleanoptional
Whether this save made the version live. It depends on the project's release settings.

Responses​

200
Saved.
400
No steps, an unknown approval mode, a tool ref that cannot be resolved, or two tools with the same function name in one step.
403
You are not a developer or admin on the project.

List agents​

GET/workflow-definitions

Lists the newest version of each agent in a project, with its live version and eval status. Needs any role on the project.

Query parameters​

project_idstringrequired
The project.

Response fields​

workflow_definitionsarrayoptional
One entry per agent name: the newest version's fields, plus is_live, live_version (id and version, or null) and evals.
GET/workflow-definitions/{definition_id}

One version, with its steps and eval status.

DELETE/workflow-definitions/{definition_id}

Deletes one version. Needs the developer or admin role. Returns 409 when it is the live version and the project saves drafts or requires evals. See Delete a version.

List available tools​

GET/tools

Every tool the project's connectors give agents. Use the ref values in a step's tools. Needs any role on the project.

Query parameters​

project_idstringrequired
The project.

Response fields​

tools[].refstringoptional
The tool ref, connector:<connector_id>:<tool_name>.
tools[].labelstringoptional
The connector's name and the tool name.
tools[].descriptionstringoptional
What the tool does, as the model sees it.

Run an agent​

POST/agents/{agent_name}/run

Runs the live version of an agent with one input and waits up to two minutes for the result. The run carries on after that, and the response says it is still running or waiting for approval.

Needs the developer or admin role on the project.

Body​

project_idstringrequired
The project the agent is in.
inputstringrequired
The user's message.
variablesobjectoptional
Run variables for a workflow graph's conditions, as names and string values.

Response fields​

workflow_idstringoptional
The run. Read it later with GET /workflow-runs/{workflow_id}, and stop it with POST /workflow-runs/{workflow_id}/cancel.
statusstringoptional
completed, awaiting_approval, rejected, canceled or running.
resultobject or nulloptional
When completed: final (the answer), outputs (each step's output by name) and trace.
result.tracearrayoptional
One entry per step: step, model, tool_calls, iterations_used, max_iterations, hit_iteration_cap and, when reported, usage.
pending_approvalsarrayoptional
When awaiting approval: the open requests. Approve them with POST /workflow-runs/{workflow_id}/approvals/{approval_id}.
rejectionobjectoptional
When rejected: message, approval_id, tool_name, step, actor, reason and timed_out.
workflow_definition_idstringoptional
The version that ran.
versionintegeroptional
Its version number.

Responses​

200
The run started. See status.
403
You are not a developer or admin on the project.
404
The project has no agent with this name.
409
The agent has no live version.

Chat with an agent​

POST/agents/{agent_name}/chat

Like Run an agent, but with a conversation. Send the whole transcript, oldest first, ending with the user's new message. Orchestrate does not store the conversation between calls. Each call resolves the live version again.

Body​

project_idstringrequired
The project the agent is in.
messagesarrayrequired
Turns with role (user or assistant) and content. The last one must be a user turn.

The response is the same as for a run.

POST/workflow-definitions/{definition_id}/run

Runs one exact version. Body: input.

POST/workflow-definitions/{definition_id}/chat

Chats with one exact version. Body: messages.

Responses​

400
messages is empty, or the last message is not from the user.

List versions​

GET/agents/{agent_name}/versions

Every version of one agent, newest first, which one is live, and what the release gate says about each. Needs any role on the project.

Query parameters​

project_idstringrequired
The project.

Response fields​

liveobject or nulloptional
The live version: workflow_definition_id, version, set_by and set_at.
versionsarrayoptional
Each version's id, version, description, created_at, created_by, is_live and gate.
versions[].gateobjectoptional
required, allowed, reason and, per required suite, its latest run against this version.
settingsobjectoptional
The project's release settings.

Make a version live​

POST/agents/{agent_name}/live

Points the agent at one version. Needs the developer or admin role on the project. Overriding the release gate needs the admin role.

Body​

workflow_definition_idstringrequired
The version to make live.
override_reasonstringoptional
Makes the version live even if the release gate refuses it. Project admins only. Recorded in the audit log as eval_gate_override.

Response fields​

liveobjectoptional
The new live version.
gateobjectoptional
The release gate's verdict.
overriddenbooleanoptional
Whether the gate was overridden.
changedbooleanoptional
false if the version was already live.

Responses​

200
Done.
400
override_reason is empty.
404
No such version of this agent.
409
The release gate refuses this version. detail.message says why and detail.gate has the verdict for each suite.

Get release settings​

GET/projects/{project_id}/agent-settings

The project's release settings. Needs any role on the project.

Response fields​

live_on_savebooleanoptional
Whether saving makes a new version live. Default true.
require_passing_evalbooleanoptional
Whether the release gate is on. Default false.
required_suite_idsarray or nulloptional
The suites the gate requires, or null for every suite written for the agent.
saves_go_livebooleanoptional
What actually happens on save. Always false while the gate is on.
updated_atstring or nulloptional
When they were last changed.
updated_bystring or nulloptional
Who changed them.
PUT/projects/{project_id}/agent-settings

Replaces the release settings. Needs the admin role on the project. Send live_on_save, require_passing_eval and required_suite_ids. Each named suite must be in the project and must name its agent. Changes are recorded in the audit log.

Was this page helpful?