Skip to main content

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.

EndpointWhat it does
POST /v1/agents/{name}/chat/completionsRuns the agent on a conversation and answers in the Chat Completions shape. stream: true answers as server-sent events.
POST /v1/agents/{name}/runsStarts 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/threadsStarts 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.

  1. Open the agent and go to its Connect section.
  2. Enter a label and choose Create key. A key made here can call only this agent.
  3. 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:

  • model is ignored. The live version picks its own model. The answer's model is 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 tools and pass them to the agent's own code.
  • Sampling parameters, such as temperature, are ignored for console-made agents.
  • user is 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 orchestrate field 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 vois field.

When a run waits or stops​

The call waits up to two minutes for the answer.

SituationResponse
The run finished200 with the answer.
The run is waiting for a person to approve a tool call202 with the run. Poll GET /v1/runs/{run_id} for the answer.
A person rejected the tool call, or it expired409 with code and the run id.
A guardrail refused the request, for example as a prompt injection422 with code set to prompt_injection_refused and the reason. The run is recorded as refused.
The run failed502 with code and the run id.
A budget, rate limit or key scope refused the call429 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 a t more 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.

Was this page helpful?
On this page
Talk to our teamQuestions about licensing or sizing VoisX Orchestrate for your site? We can help.Talk to sales →