Run an agent
For a person, named by a trusted issuer's token or by Nylorun-Subject. The thread is one session per person, agent and thread, created on its first run with forwardedProps.nylorun.session. The trailing user message starts a turn (its id is the idempotency key); its media parts are files: bytes sent inline (data, at most 20 MiB each) are stored as artifacts of the session, a file source with provider nylorun names an artifact, and a URL is refused. resume answers interrupts. A busy session is a RUN_ERROR in the stream; any file type is accepted, and the agent's harness decides how its model sees it.
AuthorizationBearer <token>An application key of the Tenant (PUT /v1/tenant/keys/{keyId}), or Studio's key, derived from the admin key. With Nylorun-Subject and Nylorun-Scopes, it acts for that person, narrowed to those scopes. Never accepted from a browser (Origin).
agentId*stringNylorun-Protocol*stringThe protocol version, 18
Nylorun-Subject?stringThe person an application key acts for
Nylorun-Scopes?stringThe subject's space-separated scopes; required with a subject
traceparent?stringW3C trace context: the turn this request starts joins the caller's trace (feature traces). A malformed value is ignored
tracestate?stringW3C trace context, kept with traceparent
application/json- body
threadId*stringrunId*stringprotocolVersion?stringparentRunId?stringstate?unknown|nullmessages*array<||||||>tools?array<>[]context?array<>[]forwardedProps?unknownresume?array<>[key: string]?unknownThe run's events, from RUN_STARTED to its end
text/event-streamcurl -X POST "https://example.com/v1/ag-ui/agents/string" \ -H "Nylorun-Protocol: string" \ -H "Content-Type: application/json" \ -d '{ "threadId": "string", "runId": "string", "messages": [ { "id": "string", "role": "developer", "content": "string", "property1": null, "property2": null } ], "property1": null, "property2": null }'Follow turns as they change GET
The turn index's change feed (Host feature `turns`): each turn's status, times, totals and A2A context and task, in the order the turns changed, a turn again each time it changes. Pass the page's `cursor` as `changedAfter` to read on; it is returned even when no turn changed. With `sessionId`, one session's turns, oldest first. An application key reads the whole Tenant; acting for a person, only theirs.
Reattach to a run GET
The rest of a run after a dropped connection, from `Last-Event-ID` or `cursor`.