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
/workflow-definitionsSaves 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_idstringrequirednamestringrequireddescriptionstringoptionalstepsarrayrequiredsteps[].namestringrequiredinput_from.steps[].system_promptstringoptionalsteps[].modelstringoptionalsteps[].input_fromstringoptionalsteps[].toolsarrayoptionalGET /tools, such as connector:billing-api:get_invoice.steps[].approvalstringoptionalsteps[].approval_timeout_secondsintegeroptionalsteps[].kindstringoptionalllm (the default, a model step), branch, parallel, join or loop. See Workflow graphs.steps[].nextstring or nulloptionalnull ends the path. A definition with any kind or next is a graph, and its first step is the entry.steps[].conditionsarrayoptionalbranch: up to 20 {"when": <condition>, "next": <step>}, tried in order. else_next is taken when none holds.steps[].branchesarrayoptionalparallel: the first step of each lane, up to 8. join names the step where they meet.steps[].combinestringoptionaljoin: text or json.steps[].bodystringoptionalloop: the first step of the loop's path. With max_iterations (1 to 20) and an optional until condition.Response fields
idstringoptionaldefinition_id.namestringoptionalversionintegeroptionalstepsarrayoptionalref and schema.is_livebooleanoptionalResponses
List agents
/workflow-definitionsLists 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_idstringrequiredResponse fields
workflow_definitionsarrayoptionalis_live, live_version (id and version, or null) and evals./workflow-definitions/{definition_id}One version, with its steps and eval status.
/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
/toolsEvery 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_idstringrequiredResponse fields
tools[].refstringoptionalconnector:<connector_id>:<tool_name>.tools[].labelstringoptionaltools[].descriptionstringoptionalRun an agent
/agents/{agent_name}/runRuns 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_idstringrequiredinputstringrequiredvariablesobjectoptionalResponse fields
workflow_idstringoptionalGET /workflow-runs/{workflow_id}, and stop it with POST /workflow-runs/{workflow_id}/cancel.statusstringoptionalcompleted, awaiting_approval, rejected, canceled or running.resultobject or nulloptionalfinal (the answer), outputs (each step's output by name) and trace.result.tracearrayoptionalstep, model, tool_calls, iterations_used, max_iterations, hit_iteration_cap and, when reported, usage.pending_approvalsarrayoptionalPOST /workflow-runs/{workflow_id}/approvals/{approval_id}.rejectionobjectoptionalmessage, approval_id, tool_name, step, actor, reason and timed_out.workflow_definition_idstringoptionalversionintegeroptionalResponses
status.Chat with an agent
/agents/{agent_name}/chatLike 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_idstringrequiredmessagesarrayrequiredrole (user or assistant) and content. The last one must be a user turn.The response is the same as for a run.
/workflow-definitions/{definition_id}/runRuns one exact version. Body: input.
/workflow-definitions/{definition_id}/chatChats with one exact version. Body: messages.
Responses
messages is empty, or the last message is not from the user.List versions
/agents/{agent_name}/versionsEvery 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_idstringrequiredResponse fields
liveobject or nulloptionalworkflow_definition_id, version, set_by and set_at.versionsarrayoptionalid, version, description, created_at, created_by, is_live and gate.versions[].gateobjectoptionalrequired, allowed, reason and, per required suite, its latest run against this version.settingsobjectoptionalMake a version live
/agents/{agent_name}/livePoints 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_idstringrequiredoverride_reasonstringoptionaleval_gate_override.Response fields
liveobjectoptionalgateobjectoptionaloverriddenbooleanoptionalchangedbooleanoptionalfalse if the version was already live.Responses
override_reason is empty.detail.message says why and detail.gate has the verdict for each suite.Get release settings
/projects/{project_id}/agent-settingsThe project's release settings. Needs any role on the project.
Response fields
live_on_savebooleanoptionaltrue.require_passing_evalbooleanoptionalfalse.required_suite_idsarray or nulloptionalnull for every suite written for the agent.saves_go_livebooleanoptionalfalse while the gate is on.updated_atstring or nulloptionalupdated_bystring or nulloptional/projects/{project_id}/agent-settingsReplaces 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.