> ## Documentation Index > Fetch the complete documentation index at: https://docs.onecortex.io/llms.txt > Use this file to discover all available pages before exploring further. # 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](/call/ag-ui) for the event mapping and the `RUN_ERROR` codes. ## OpenAPI ````yaml /openapi.yaml post /v1/agents/{agentId}/agui openapi: 3.1.0 info: title: Onecortex API version: '1' description: >- Call a deployed agent over invoke, AG-UI or A2A, and read its public A2A Agent Card. This is the whole public API. servers: - url: https://api.onecortex.io security: - apiKey: [] paths: /v1/agents/{agentId}/agui: post: summary: Run an agent over AG-UI description: > 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](/call/ag-ui) for the event mapping and the `RUN_ERROR` codes. operationId: runAgentAgui parameters: - $ref: '#/components/parameters/AgentId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AguiRequest' example: threadId: user-42 runId: run-1 messages: - id: m1 role: user content: hello responses: '200': description: The run, as a stream of AG-UI events. headers: X-Request-Id: $ref: '#/components/headers/RequestId' X-RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' content: text/event-stream: schema: type: string description: > One unnamed `data:` frame per AG-UI event. A `: ping` comment arrives every 15 seconds while the agent is silent. ```text 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"}} ``` example: >- data: {"type":"RUN_STARTED","threadId":"user-42","runId":"run-1"} '400': description: No user message and no `resume`, or the body is not valid. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: error: code: invalid_request message: >- Send at least one user message, or a resume to answer a paused run. requestId: req_01K0000000000000000000000 '401': $ref: '#/components/responses/Unauthenticated' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' x-codeSamples: - lang: python label: Python source: | 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"]) - lang: typescript label: TypeScript source: | 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) }, }) - lang: bash label: curl source: | 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"}]}' components: parameters: AgentId: name: agentId in: path required: true description: The agent's ID, from its page in the dashboard. schema: type: string example: agt_01K0000000000000000000000 schemas: AguiRequest: type: object additionalProperties: true description: >- An AG-UI `RunAgentInput`, at most 1 MB. Any field beyond `threadId`, `runId`, `messages` and `resume` reaches the agent unchanged, as `params`. required: - messages properties: threadId: type: string minLength: 1 maxLength: 256 description: The agent's session. Generated when left out. runId: type: string description: Echoed on RUN_STARTED and RUN_FINISHED. Generated when left out. messages: type: array description: The conversation. The last `user` message's text is the prompt. items: type: object additionalProperties: true required: - role properties: id: type: string role: type: string example: user content: description: Text, or content parts whose `text` parts are joined. oneOf: - type: string - type: array items: type: object additionalProperties: true resume: type: array description: Answers every interrupt a paused run ended with. items: type: object required: - interruptId - status properties: interruptId: type: string status: type: string enum: - resolved - cancelled payload: {} tools: type: array items: {} description: Reaches the agent as params. state: description: Reaches the agent as params. context: type: array items: {} description: Reaches the agent as params. forwardedProps: description: Reaches the agent as params. ErrorBody: type: object required: - error properties: error: type: object required: - code - message - requestId properties: code: type: string enum: - validation_failed - invalid_request - unauthenticated - forbidden - organization_suspended - not_found - agent_not_ready - agent_not_deployed - agent_deleted - payload_too_large - rate_limited - internal_error - agent_error - upstream_error - service_unavailable - agent_unavailable - capacity_exceeded message: type: string details: type: object additionalProperties: true requestId: type: string headers: RequestId: description: The request's ID, `req_...`. Quote it to support. schema: type: string RateLimitRemaining: description: Requests left in the organization's burst allowance. schema: type: integer responses: Unauthenticated: description: The API key is missing, unknown, revoked or expired. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: error: code: unauthenticated message: A valid Onecortex API key is required. requestId: req_01K0000000000000000000000 NotFound: description: >- No such agent in your organization, or the key is scoped to another agent. content: application/json: schema: $ref: '#/components/schemas/ErrorBody' example: error: code: not_found message: That agent does not exist. requestId: req_01K0000000000000000000000 RateLimited: description: Over a rate limit. Wait for `Retry-After`, then retry. headers: Retry-After: description: Whole seconds to wait. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorBody' securitySchemes: apiKey: type: http scheme: bearer description: An Onecortex API key, `oc_live_...`, from API keys in the dashboard. ````