{
"openapi": "3.1.0",
"info": {"title": "Agent Runtime API", "version": "4.0.0", "description": "Native Agent Tasks with OpenAI Responses and Claude Messages compatibility adapters."},
"security": [{"bearerAuth": []}],
"paths": {
"/livez": {"get": {"security": [], "responses": {"200": {"description": "Process is live"}}}},
"/readyz": {"get": {"security": [], "responses": {"200": {"description": "Runtime is ready"}, "503": {"description": "Dependency is not ready"}}}},
"/v1/agent/tasks": {
"post": {
"description": "Create an asynchronous Agent Task. Idempotency-Key is optional but recommended.",
"parameters": [{"name": "Idempotency-Key", "in": "header", "required": false, "schema": {"type": "string", "minLength": 1, "maxLength": 256}}],
"requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CreateAgentTaskRequest"}}}},
"responses": {"202": {"description": "Task accepted", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AgentTask"}}}}, "200": {"description": "Idempotent task replay"}, "400": {"$ref": "#/components/responses/Error"}}
}
},
"/v1/agent/tasks/{taskId}": {
"get": {"parameters": [{"$ref": "#/components/parameters/TaskId"}], "responses": {"200": {"description": "Current Task snapshot", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AgentTask"}}}}, "404": {"$ref": "#/components/responses/Error"}}}
},
"/v1/agent/tasks/{taskId}/events": {
"get": {"description": "Replay committed observability events after an exclusive sequence cursor.", "parameters": [{"$ref": "#/components/parameters/TaskId"}, {"name": "after", "in": "query", "schema": {"type": "integer", "minimum": 0}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 1000}}], "responses": {"200": {"description": "Committed Task event page"}}}
},
"/v1/agent/tasks/{taskId}/stream": {
"get": {"description": "Replayable SSE. Event IDs are committed Journal sequence numbers; reconnect with after or Last-Event-ID.", "parameters": [{"$ref": "#/components/parameters/TaskId"}, {"name": "after", "in": "query", "schema": {"type": "integer", "minimum": 0}}, {"name": "Last-Event-ID", "in": "header", "schema": {"type": "string", "pattern": "^[0-9]+$"}}], "responses": {"200": {"description": "Agent Task SSE", "content": {"text/event-stream": {"schema": {"type": "string"}}}}}}
},
"/v1/agent/tasks/{taskId}/ws": {
"get": {"description": "Authenticated Task-scoped WebSocket. Supports resume cursor, input, cancel, ACK, heartbeats, and committed observability events.", "parameters": [{"$ref": "#/components/parameters/TaskId"}, {"name": "after", "in": "query", "schema": {"type": "integer", "minimum": 0}}], "responses": {"101": {"description": "WebSocket protocol switch"}}}
},
"/v1/agent/tasks/{taskId}/inputs": {
"post": {"parameters": [{"$ref": "#/components/parameters/TaskId"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/SubmitInputRequest"}}}}, "responses": {"200": {"description": "Task input committed"}}}
},
"/v1/agent/tasks/{taskId}/cancel": {
"post": {"parameters": [{"$ref": "#/components/parameters/TaskId"}], "responses": {"200": {"description": "Task cancellation committed"}}}
},
"/v1/responses": {
"post": {"description": "OpenAI Responses-compatible adapter. `model` addresses a Runtime ID unless agent.runtimeId is supplied.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/OpenAIResponseRequest"}}}}, "responses": {"200": {"description": "OpenAI Response or SSE stream"}, "400": {"description": "OpenAI error envelope"}}}
},
"/v1/responses/{responseId}": {
"get": {"parameters": [{"$ref": "#/components/parameters/ResponseId"}], "responses": {"200": {"description": "OpenAI Response snapshot"}}}
},
"/v1/responses/{responseId}/cancel": {
"post": {"parameters": [{"$ref": "#/components/parameters/ResponseId"}], "responses": {"200": {"description": "Canceled OpenAI Response snapshot"}}}
},
"/v1/messages": {
"post": {"description": "Claude Messages-compatible adapter. Requires anthropic-version; `model` addresses a Runtime ID unless agent.runtimeId is supplied.", "parameters": [{"name": "anthropic-version", "in": "header", "required": true, "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ClaudeMessageRequest"}}}}, "responses": {"200": {"description": "Claude Message or SSE stream"}, "400": {"description": "Claude error envelope"}}}
}
},
"components": {
"securitySchemes": {"bearerAuth": {"type": "http", "scheme": "bearer"}},
"parameters": {
"TaskId": {"name": "taskId", "in": "path", "required": true, "schema": {"type": "string", "minLength": 1, "maxLength": 256}},
"ResponseId": {"name": "responseId", "in": "path", "required": true, "schema": {"type": "string", "minLength": 1, "maxLength": 256}}
},
"responses": {"Error": {"description": "Runtime error", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ApiError"}}}}},
"schemas": {
"RuntimeInput": {"oneOf": [
{"type": "object", "additionalProperties": false, "required": ["type", "text"], "properties": {"type": {"const": "user_message"}, "text": {"type": "string", "minLength": 1, "maxLength": 1048576}}},
{"type": "object", "additionalProperties": false, "required": ["type", "messages"], "properties": {"type": {"const": "messages"}, "messages": {"type": "array", "minItems": 1, "maxItems": 256, "items": {"type": "object", "additionalProperties": false, "required": ["role", "text"], "properties": {"role": {"enum": ["system", "developer", "user", "assistant"]}, "text": {"type": "string", "minLength": 1, "maxLength": 1048576}}}}}},
{"type": "object", "additionalProperties": false, "required": ["type", "requestId", "approved"], "properties": {"type": {"const": "tool_approval"}, "requestId": {"type": "string"}, "approved": {"type": "boolean"}}},
{"type": "object", "additionalProperties": false, "required": ["type", "requestId", "text"], "properties": {"type": {"const": "elicitation_response"}, "requestId": {"type": "string"}, "text": {"type": "string"}}}
]},
"ExecutionOptions": {"type": "object", "additionalProperties": false, "properties": {"deadlineSeconds": {"type": "integer", "minimum": 1, "maximum": 604800, "default": 900}, "maxModelTurns": {"type": "integer", "minimum": 1, "maximum": 256, "default": 64}, "maxToolCalls": {"type": "integer", "minimum": 1, "maximum": 2048, "default": 256}}},
"ModelGenerationOptions": {"type": "object", "additionalProperties": false, "properties": {"maxOutputTokens": {"type": "integer", "minimum": 1}, "temperature": {"type": "number", "minimum": 0, "maximum": 2}, "stopSequences": {"type": "array", "maxItems": 4, "items": {"type": "string", "minLength": 1, "maxLength": 1024}}, "responseFormat": {"type": "object"}, "toolChoice": {"type": "object", "additionalProperties": false, "required": ["type"], "properties": {"type": {"enum": ["auto", "none"]}}}}},
"CreateExecutionRequest": {"type": "object", "additionalProperties": false, "required": ["runtimeInstanceId", "input"], "properties": {"runtimeInstanceId": {"type": "string"}, "conversationId": {"type": "string"}, "input": {"$ref": "#/components/schemas/RuntimeInput"}, "workspaceId": {"type": "string"}, "model": {"type": "string"}, "instructions": {"type": "string"}, "metadata": {"type": "object", "additionalProperties": {"type": "string"}}, "generation": {"$ref": "#/components/schemas/ModelGenerationOptions"}, "options": {"$ref": "#/components/schemas/ExecutionOptions"}}},
"AgentTaskLimits": {"type": "object", "additionalProperties": false, "properties": {"deadlineSeconds": {"type": "integer", "minimum": 1, "maximum": 604800, "default": 900}, "maxModelTurns": {"type": "integer", "minimum": 1, "maximum": 256, "default": 64}, "maxToolCalls": {"type": "integer", "minimum": 1, "maximum": 2048, "default": 256}}},
"CreateAgentTaskRequest": {"type": "object", "additionalProperties": false, "required": ["runtimeId", "input"], "properties": {"runtimeId": {"type": "string"}, "conversationId": {"type": "string"}, "input": {"type": "object", "additionalProperties": false, "required": ["text"], "properties": {"text": {"type": "string", "minLength": 1}}}, "workspace": {"type": "object", "additionalProperties": false, "required": ["id"], "properties": {"id": {"type": "string"}}}, "model": {"type": "object", "additionalProperties": false, "required": ["id"], "properties": {"id": {"type": "string"}, "maxOutputTokens": {"type": "integer", "minimum": 1}, "temperature": {"type": "number", "minimum": 0, "maximum": 2}, "stopSequences": {"type": "array", "maxItems": 4, "items": {"type": "string"}}, "responseFormat": {"type": "object"}, "toolChoice": {}}}, "instructions": {"type": "string"}, "limits": {"$ref": "#/components/schemas/AgentTaskLimits"}, "metadata": {"type": "object", "additionalProperties": {"type": "string"}}}},
"AgentTask": {"type": "object", "required": ["id", "object", "runtimeId", "status", "createdAtMs", "updatedAtMs", "links"], "properties": {"id": {"type": "string"}, "object": {"const": "agent.task"}, "runtimeId": {"type": "string"}, "conversationId": {"type": "string"}, "workspace": {"type": "object", "properties": {"id": {"type": "string"}}}, "model": {"type": "string"}, "metadata": {"type": "object", "additionalProperties": {"type": "string"}}, "status": {"enum": ["queued", "running", "waiting_for_input", "finalizing", "completed", "failed", "canceled"]}, "output": {"type": "object"}, "error": {"$ref": "#/components/schemas/ApiError"}, "createdAtMs": {"type": "integer"}, "updatedAtMs": {"type": "integer"}, "links": {"type": "object"}}},
"OpenAIResponseRequest": {"type": "object", "required": ["model", "input"], "properties": {"model": {"type": "string"}, "input": {}, "instructions": {}, "max_output_tokens": {"type": "integer", "minimum": 1}, "temperature": {"type": "number", "minimum": 0, "maximum": 2}, "text": {"type": "object"}, "tool_choice": {}, "background": {"type": "boolean", "default": false}, "stream": {"type": "boolean", "default": false}, "metadata": {"type": "object", "additionalProperties": {"type": "string"}}, "agent": {"type": "object"}}},
"ClaudeMessageRequest": {"type": "object", "required": ["model", "max_tokens", "messages"], "properties": {"model": {"type": "string"}, "max_tokens": {"type": "integer", "minimum": 1}, "messages": {"type": "array", "minItems": 1, "items": {"type": "object", "required": ["role", "content"]}}, "system": {}, "temperature": {"type": "number", "minimum": 0, "maximum": 1}, "stop_sequences": {"type": "array", "maxItems": 4, "items": {"type": "string"}}, "tool_choice": {}, "stream": {"type": "boolean", "default": false}, "metadata": {"type": "object"}, "agent": {"type": "object"}}},
"CreateExecutionResponse": {"type": "object", "additionalProperties": false, "required": ["execution", "replayed"], "properties": {"execution": {"$ref": "#/components/schemas/ExecutionView"}, "replayed": {"type": "boolean"}}},
"ExecutionOutcome": {"type": "object", "additionalProperties": false, "required": ["answer", "modelTurns", "toolCalls", "inputTokens", "outputTokens"], "properties": {"answer": {"type": "string"}, "modelTurns": {"type": "integer", "minimum": 0}, "toolCalls": {"type": "integer", "minimum": 0}, "inputTokens": {"type": ["integer", "null"], "minimum": 0}, "outputTokens": {"type": ["integer", "null"], "minimum": 0}}},
"ExecutionView": {"type": "object", "additionalProperties": false, "required": ["id", "runtimeInstanceId", "state", "outcome", "failure", "createdAtMs", "updatedAtMs"], "properties": {"id": {"type": "string"}, "runtimeInstanceId": {"type": "string"}, "conversationId": {"type": ["string", "null"]}, "workspaceId": {"type": "string"}, "model": {"type": "string"}, "metadata": {"type": "object", "additionalProperties": {"type": "string"}}, "state": {"enum": ["queued", "running", "waiting_for_input", "finalizing", "completed", "failed", "canceled"]}, "outcome": {"oneOf": [{"type": "null"}, {"$ref": "#/components/schemas/ExecutionOutcome"}]}, "failure": {"type": ["object", "null"]}, "createdAtMs": {"type": "integer"}, "updatedAtMs": {"type": "integer"}}},
"SubmitInputRequest": {"type": "object", "additionalProperties": false, "required": ["operationId", "input"], "properties": {"operationId": {"type": "string"}, "input": {"$ref": "#/components/schemas/RuntimeInput"}}},
"ApiError": {"type": "object", "additionalProperties": false, "required": ["code", "message"], "properties": {"code": {"type": "string"}, "message": {"type": "string"}, "requestId": {"type": "string"}, "details": {"type": "object"}}}
}
}
}