import json, os, httpx
with httpx.stream(
"POST", "https://api.onecortex.io/v1/agents/agt_.../agui",
headers={"Authorization": f"Bearer {os.environ['ONECORTEX_API_KEY']}"},
json={"threadId": "user-42", "messages": [{"id": "m1", "role": "user", "content": "hello"}]},
) as response:
for line in response.iter_lines():
if line.startswith("data: "):
event = json.loads(line[6:])
if event["type"] == "TEXT_MESSAGE_CONTENT":
print(event["delta"], end="", flush=True)
elif event["type"] == "RUN_ERROR":
raise RuntimeError(event["message"])
import { HttpAgent } from '@ag-ui/client'
const agent = new HttpAgent({
url: 'https://api.onecortex.io/v1/agents/agt_.../agui',
headers: { Authorization: `Bearer ${process.env.ONECORTEX_API_KEY}` },
threadId: 'user-42',
})
agent.addMessage({ id: 'm1', role: 'user', content: 'hello' })
await agent.runAgent({}, {
onTextMessageContentEvent: ({ event }) => { process.stdout.write(event.delta) },
})
curl -N https://api.onecortex.io/v1/agents/agt_.../agui \
-H "Authorization: Bearer $ONECORTEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"threadId":"user-42","messages":[{"id":"m1","role":"user","content":"hello"}]}'
"data: {\"type\":\"RUN_STARTED\",\"threadId\":\"user-42\",\"runId\":\"run-1\"}"{
"error": {
"code": "invalid_request",
"message": "Send at least one user message, or a resume to answer a paused run.",
"requestId": "req_01K0000000000000000000000"
}
}{
"error": {
"code": "unauthenticated",
"message": "A valid Onecortex API key is required.",
"requestId": "req_01K0000000000000000000000"
}
}{
"error": {
"code": "not_found",
"message": "That agent does not exist.",
"requestId": "req_01K0000000000000000000000"
}
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"requestId": "<string>",
"details": {}
}
}Run an agent over AG-UI
AG-UI, for agent front ends such as CopilotKit. Send an AG-UI RunAgentInput and read a stream of AG-UI events: RUN_STARTED, text, tool call and step events, then RUN_FINISHED or RUN_ERROR. Every AG-UI run streams.
threadId is the agent’s session. The text of the last user message is the prompt, and the whole messages list reaches the agent; tools, state, context, forwardedProps and any other field reach it unchanged, as params.
A run that pauses ends with RUN_FINISHED and outcome.type interrupt. Answer it with resume on the same threadId.
A refusal before the stream starts answers with the same status and body as invoke. See AG-UI for the event mapping and the RUN_ERROR codes.
import json, os, httpx
with httpx.stream(
"POST", "https://api.onecortex.io/v1/agents/agt_.../agui",
headers={"Authorization": f"Bearer {os.environ['ONECORTEX_API_KEY']}"},
json={"threadId": "user-42", "messages": [{"id": "m1", "role": "user", "content": "hello"}]},
) as response:
for line in response.iter_lines():
if line.startswith("data: "):
event = json.loads(line[6:])
if event["type"] == "TEXT_MESSAGE_CONTENT":
print(event["delta"], end="", flush=True)
elif event["type"] == "RUN_ERROR":
raise RuntimeError(event["message"])
import { HttpAgent } from '@ag-ui/client'
const agent = new HttpAgent({
url: 'https://api.onecortex.io/v1/agents/agt_.../agui',
headers: { Authorization: `Bearer ${process.env.ONECORTEX_API_KEY}` },
threadId: 'user-42',
})
agent.addMessage({ id: 'm1', role: 'user', content: 'hello' })
await agent.runAgent({}, {
onTextMessageContentEvent: ({ event }) => { process.stdout.write(event.delta) },
})
curl -N https://api.onecortex.io/v1/agents/agt_.../agui \
-H "Authorization: Bearer $ONECORTEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"threadId":"user-42","messages":[{"id":"m1","role":"user","content":"hello"}]}'
"data: {\"type\":\"RUN_STARTED\",\"threadId\":\"user-42\",\"runId\":\"run-1\"}"{
"error": {
"code": "invalid_request",
"message": "Send at least one user message, or a resume to answer a paused run.",
"requestId": "req_01K0000000000000000000000"
}
}{
"error": {
"code": "unauthenticated",
"message": "A valid Onecortex API key is required.",
"requestId": "req_01K0000000000000000000000"
}
}{
"error": {
"code": "not_found",
"message": "That agent does not exist.",
"requestId": "req_01K0000000000000000000000"
}
}{
"error": {
"code": "validation_failed",
"message": "<string>",
"requestId": "<string>",
"details": {}
}
}Authorizations
An Onecortex API key, oc_live_..., from API keys in the dashboard.
Path Parameters
The agent's ID, from its page in the dashboard.
"agt_01K0000000000000000000000"
Body
An AG-UI RunAgentInput, at most 1 MB. Any field beyond threadId, runId, messages and resume reaches the agent unchanged, as params.
The conversation. The last user message's text is the prompt.
Show child attributes
Show child attributes
The agent's session. Generated when left out.
1 - 256Echoed on RUN_STARTED and RUN_FINISHED. Generated when left out.
Answers every interrupt a paused run ended with.
Show child attributes
Show child attributes
Reaches the agent as params.
Reaches the agent as params.
Reaches the agent as params.
Reaches the agent as params.
Response
The run, as a stream of AG-UI events.
One unnamed data: frame per AG-UI event. A : ping comment arrives every 15 seconds while the agent is silent.
data: {"type":"RUN_STARTED","threadId":"user-42","runId":"run-1"} data: {"type":"TEXT_MESSAGE_START","messageId":"01K...","role":"assistant"} data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"01K...","delta":"You said: hello"} data: {"type":"TEXT_MESSAGE_END","messageId":"01K..."} data: {"type":"RUN_FINISHED","threadId":"user-42","runId":"run-1","result":"You said: hello","outcome":{"type":"success"}}
"data: {\"type\":\"RUN_STARTED\",\"threadId\":\"user-42\",\"runId\":\"run-1\"}"