Agent API
The Agent API is how an application, rather than a person in the console, calls a project's agents. It is OpenAI-compatible, so an OpenAI client pointed at an agent's address works unchanged.
| Endpoint | What it does |
|---|---|
POST /v1/agents/{name}/chat/completions | Runs the agent on a conversation and answers in the Chat Completions shape. stream: true answers as server-sent events. |
POST /v1/agents/{name}/runs | Starts a run and returns at once. Poll it, or be called back by a webhook. |
GET /v1/runs/{run_id} | A run's status and final answer, including a run that waited for an approval. |
POST /v1/threads | Starts a conversation that Orchestrate keeps, so you send only the new message each turn. |
GET /v1/threads/{thread_id}, DELETE /v1/threads/{thread_id} | Read or delete a thread. |
These endpoints are on the API service, the same host as the console's API. See the API reference for every field.
Get a project API key
Every Agent API call takes a project API key, and the Agent API takes nothing else.
- Open the agent and go to its Connect section.
- Enter a label and choose Create key. A key made here can call only this agent.
- Copy the key. It starts with
vcpj_and is shown once. The webhook signing secret for async runs is shown with it.
A key for every agent of the project, or one with an expiry date, is made with POST /projects/{project_id}/api-keys.
You need the admin role on the project to create one, because the key acts for the whole project and outlives your membership. Developers can list and revoke keys.
A project key works only on the /v1 agent routes. It is refused by the Model Gateway and by the rest of the API. A key restricted to one agent reaches only that agent, its threads and its runs. Project admins can also give a key a budget, rate limits and a list of agents it may call. See Usage controls.
Chat completions
from openai import OpenAI
client = OpenAI(
base_url="https://orchestrate-api.example.com/v1/agents/support-triage",
api_key="vcpj_...",
)
reply = client.chat.completions.create(
model="support-triage", # accepted and ignored: the path names the agent
messages=[{"role": "user", "content": "My invoice shows the wrong address."}],
)
print(reply.choices[0].message.content)
Where the Agent API differs from OpenAI's:
modelis ignored. The live version picks its own model. The answer'smodelis the agent's name.- System and developer messages are dropped. The agent's instructions are part of its definition, and a caller can't override them.
- Client-side tools are refused for console-made agents. Their tools run on the platform, under the approval gate. Code agents accept
toolsand pass them to the agent's own code. - Sampling parameters, such as
temperature, are ignored for console-made agents. useris read as your application's id for the person you are calling for. A connector that acts as each user uses that person's own connection. See Act as each user.
Streaming
With stream: true the answer is a stream of chat.completion.chunk events ending with data: [DONE].
- Console-made agents send progress chunks while the run works. Each has an empty delta and a
orchestratefield that says which step is running, which tool is being called, or which approval is pending. The whole answer then arrives as one content chunk. Token-by-token streaming isn't available for these agents yet, because each model call runs inside a durable workflow step. - Code agents stream token by token, with tool events in a
voisfield.
When a run waits or stops
The call waits up to two minutes for the answer.
| Situation | Response |
|---|---|
| The run finished | 200 with the answer. |
| The run is waiting for a person to approve a tool call | 202 with the run. Poll GET /v1/runs/{run_id} for the answer. |
| A person rejected the tool call, or it expired | 409 with code and the run id. |
| A guardrail refused the request, for example as a prompt injection | 422 with code set to prompt_injection_refused and the reason. The run is recorded as refused. |
| The run failed | 502 with code and the run id. |
| A budget, rate limit or key scope refused the call | 429 or 403. See Usage controls. |
Threads
Without a thread, you send the whole conversation every turn. With one, Orchestrate keeps the turns:
# Start a thread with the agent
curl -X POST https://orchestrate-api.example.com/v1/threads \
-H "Authorization: Bearer $ORCHESTRATE_PROJECT_KEY" \
-H "Content-Type: application/json" \
-d '{ "agent_name": "support-triage" }'
# Send only the new message, with the thread id
curl -X POST https://orchestrate-api.example.com/v1/agents/support-triage/chat/completions \
-H "Authorization: Bearer $ORCHESTRATE_PROJECT_KEY" \
-H "Content-Type: application/json" \
-d '{ "thread_id": "thread_...", "messages": [{ "role": "user", "content": "And the VAT number?" }] }'
GET /v1/threads/{thread_id} returns the turns, tool calls included. Turns are stored redacted, and the next turn on a thread sees the redacted record of earlier turns. Threads are deleted after 30 days without activity by default.
Async runs and webhooks
For work that may take a while, or wait for an approval, start a run and come back for it:
curl -X POST https://orchestrate-api.example.com/v1/agents/support-triage/runs \
-H "Authorization: Bearer $ORCHESTRATE_PROJECT_KEY" \
-H "Content-Type: application/json" \
-d '{ "input": "Refund order 1182", "webhook_url": "https://hooks.example.com/orchestrate" }'
The answer is 202 with the run's id. GET /v1/runs/{run_id} returns its status (running, awaiting_approval, completed, rejected, refused or failed), the output once there is one, usage and citations.
With webhook_url, Orchestrate posts the same body to that address when the run ends:
- Only hosts your operator allows. The destination must be on the list in
agentApi.webhookAllowedHosts. With the list empty, the default, webhooks are refused. See Configuration. - Signed. Each delivery carries
X-Orchestrate-Signature: t=<unix seconds>,v1=<hex>, an HMAC-SHA256 of<t>.<raw body>. The signing secret is returned beside the project key when you create it. Compare in constant time, and refuse atmore than a few minutes old. - At least once. A non-2xx answer is retried with backoff, from 10 seconds up to an hour between tries. Each delivery has
X-Orchestrate-Run-Id, so you can drop a repeat. - No redirects are followed.
Feedback
Your application can pass on a person's rating of an answer with POST /v1/runs/{run_id}/feedback, {"rating": "up" | "down", "comment": "...", "user_id": "<your id for the person>"}. See Online evals and feedback.
Console calls and the older routes
POST /agents/{name}/run and POST /agents/{name}/chat still work with a Keycloak access token, for scripts that act as a person. New integrations should use the Agent API. See the Agents API.