> ## Documentation Index > Fetch the complete documentation index at: https://docs.orq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create response > Initiates an agent conversation and returns a complete response. This endpoint manages the full lifecycle of an agent interaction, from receiving the initial message through all processing steps until completion. Supports synchronous execution (waits for completion) and asynchronous execution (returns immediately with task ID). The response includes all messages exchanged, tool calls made, and token usage statistics. Ideal for request-response patterns where you need the complete interaction result. ## OpenAPI ````yaml post /v2/agents/{agent_key}/responses openapi: 3.1.0 info: title: orq.ai API version: '2.0' description: orq.ai API documentation servers: - url: https://api.orq.ai security: - ApiKey: [] tags: - name: Guardrail Rules - name: Policies - name: Routing Rules - name: Files description: File upload and retrieval operations. - name: FilesService - name: Projects description: Projects organize resources within a workspace - name: ProjectsService - name: Skills description: >- Skills are modular instructions you can use to codify processes and conventions - name: SkillsService - name: Responses - description: >- Run agents on a cadence — cron, interval, or one-off. Minimum firing interval is 1 hour. name: Agent Schedules - name: Reporting description: >- GenAI reporting API over canonical analytics rollups. Accepts a metric name, time range, grain, group-by, and filters; returns a typed time series and optional totals. - name: ReportingService description: |- ReportingService exposes a single QueryReport RPC that maps allowlisted analytics payloads onto safe rollup queries. Callers never send SQL; the backend picks the rollup family and grain from the metric catalogue, the requested range, and the requested grouping. externalDocs: url: https://docs.orq.ai description: orq.ai Documentation paths: /v2/agents/{agent_key}/responses: post: tags: - Agents summary: Create response description: >- Initiates an agent conversation and returns a complete response. This endpoint manages the full lifecycle of an agent interaction, from receiving the initial message through all processing steps until completion. Supports synchronous execution (waits for completion) and asynchronous execution (returns immediately with task ID). The response includes all messages exchanged, tool calls made, and token usage statistics. Ideal for request-response patterns where you need the complete interaction result. operationId: CreateAgentResponseRequest parameters: - schema: type: string description: The unique key of identifier of the agent to invoke required: true description: The unique key of identifier of the agent to invoke name: agent_key in: path requestBody: required: true content: application/json: schema: type: object properties: task_id: type: string description: >- Optional task ID to continue an existing agent execution. When provided, the agent will continue the conversation from the existing task state. The task must be in an inactive state to continue. message: type: object properties: messageId: type: string description: Optional A2A message ID in ULID format role: anyOf: - type: string enum: - user title: User message description: Message from the end user - type: string enum: - tool title: Tool message description: Message containing tool execution results description: Message role (user or tool for continuing executions) parts: type: array items: oneOf: - allOf: - $ref: '#/components/schemas/TextPart' - description: >- Text content part. Use this to send text messages to the agent. - allOf: - $ref: '#/components/schemas/FilePart' - description: >- File attachment part. Use this to send files (images, documents, etc.) to the agent for processing. - allOf: - $ref: '#/components/schemas/ToolResultPart' - description: >- Tool execution result part. Use this ONLY when providing results for a pending tool call from the agent. The tool_call_id must match the ID from the agent's tool call request. - allOf: - $ref: '#/components/schemas/ErrorPart' - description: >- Error content part. Generated by the system when an error occurs during agent execution. discriminator: propertyName: kind mapping: text: $ref: '#/components/schemas/TextPart' file: $ref: '#/components/schemas/FilePart' tool_result: $ref: '#/components/schemas/ToolResultPart' error: $ref: '#/components/schemas/ErrorPart' title: Public Message Part description: >- Message part that can be provided by users. Use "text" for regular messages, "file" for attachments, or "tool_result" when responding to tool call requests. description: >- A2A message parts (text, file, or tool_result only). Note: Tool role messages must only contain tool_result parts. required: - role - parts title: A2A Message description: >- The A2A message to send to the agent (user input or tool results) variables: type: object additionalProperties: {} description: >- Optional variables for template replacement in system prompt, instructions, and messages identity: type: object properties: id: type: string description: Unique identifier for the contact example: contact_01ARZ3NDEKTSV4RRFFQ69G5FAV display_name: type: string description: Display name of the contact example: Jane Doe email: type: string format: email description: Email address of the contact example: jane.doe@example.com metadata: type: array items: type: object additionalProperties: {} description: >- A hash of key/value pairs containing any other data about the contact example: - department: Engineering role: Senior Developer logo_url: type: string description: URL to the contact's avatar or logo example: https://example.com/avatars/jane-doe.jpg tags: type: array items: type: string description: A list of tags associated with the contact example: - hr - engineering required: - id description: >- Information about the identity making the request. If the identity does not exist, it will be created automatically. contact: type: object properties: id: type: string description: Unique identifier for the contact example: contact_01ARZ3NDEKTSV4RRFFQ69G5FAV display_name: type: string description: Display name of the contact example: Jane Doe email: type: string format: email description: Email address of the contact example: jane.doe@example.com metadata: type: array items: type: object additionalProperties: {} description: >- A hash of key/value pairs containing any other data about the contact example: - department: Engineering role: Senior Developer logo_url: type: string description: URL to the contact's avatar or logo example: https://example.com/avatars/jane-doe.jpg tags: type: array items: type: string description: A list of tags associated with the contact example: - hr - engineering required: - id description: >- @deprecated Use identity instead. Information about the contact making the request. deprecated: true thread: type: object properties: id: type: string description: Unique thread identifier to group related invocations. example: thread_01ARZ3NDEKTSV4RRFFQ69G5FAV tags: type: array items: type: string description: Optional tags to differentiate or categorize threads example: - customer-support - priority-high required: - id description: Thread information to group related requests memory: type: object properties: entity_id: type: string description: >- An entity ID used to link memory stores to a specific user, session, or conversation. This ID is used to isolate and retrieve memories specific to the entity across agent executions. required: - entity_id description: >- Memory configuration for the agent execution. Used to associate memory stores with specific entities like users or sessions. metadata: type: object additionalProperties: {} description: >- Optional metadata for the agent invocation as key-value pairs that will be included in traces engine: type: string enum: - text - jinja - mustache description: >- Override template engine for this invocation. If not provided, uses the agent default. configuration: type: object properties: blocking: type: boolean default: false description: >- Whether to block until the agent task completes. When true, the response will include the full task with messages. When false (default), returns immediately with task ID and status. description: Configuration options for the agent invocation background: type: boolean default: false description: >- If true, returns immediately without waiting for completion. If false (default), waits until the agent becomes inactive or errors. stream: type: boolean default: false description: >- If true, returns Server-Sent Events (SSE) streaming response with real-time events. If false (default), returns standard JSON response. conversation: type: object properties: _id: type: string minLength: 1 description: >- Unique ULID identifier for the conversation, prefixed with "conv_". Used to link agent executions to a specific conversation thread. required: - _id description: Conversation context for chat studio integration required: - message responses: '200': description: >- Agent response successfully created and completed. Returns the full conversation including all messages, tool interactions, model used, and token usage statistics. In background mode, returns immediately with initial task details. In streaming mode, returns Server-Sent Events (SSE) with real-time events. content: application/json: schema: $ref: '#/components/schemas/CreateAgentResponse' text/event-stream: schema: $ref: '#/components/schemas/ResponseStreamingEvent' x-speakeasy-sse-sentinel: '[DONE]' x-code-samples: - lang: curl label: cURL source: |- curl --request POST \ --url 'https://api.orq.ai/v2/agents/customer_support/responses' \ --header 'Authorization: Bearer $ORQ_API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "message": { "role": "user", "parts": [ { "kind": "text", "text": "Hi! I am testing your capabilities. Can you describe what you can do?" } ] } }' - lang: python label: Python source: |- import os from orq_ai_sdk import Orq client = Orq( api_key=os.environ.get("ORQ_API_KEY") ) response = client.agents.responses.create( agent_key="customer_support", message={ "role": "user", "parts": [ { "kind": "text", "text": "Hi! I am testing your capabilities. Can you describe what you can do?" } ] } ) print(response.output[0].parts[0].text) print(response.usage) - lang: typescript label: Node.js source: |- import { Orq } from '@orq-ai/node'; const client = new Orq({ apiKey: process.env.ORQ_API_KEY, }); const response = await client.agents.responses.create({ agentKey: 'customer_support', message: { role: 'user', parts: [ { kind: 'text', text: 'Hi! I am testing your capabilities. Can you describe what you can do?', }, ], } }); console.log(response.output[0].parts[0].text); console.log(response.usage); components: schemas: TextPart: type: object properties: kind: type: string enum: - text text: type: string required: - kind - text title: Text Part description: >- A text content part containing plain text or markdown. Used for agent messages, user input, and text-based responses. FilePart: type: object properties: kind: type: string enum: - file file: anyOf: - type: object properties: bytes: type: string minLength: 1 description: base64 encoded content of the file mimeType: type: string description: Optional mimeType for the file name: type: string description: Optional name for the file required: - bytes title: Binary format description: >- Binary in base64 format. Check in the model's documentation for the supported mime types for the binary format. - type: object properties: uri: type: string description: URL for the File content mimeType: type: string description: Optional mimeType for the file name: type: string description: Optional name for the file required: - uri title: File in URI format description: >- File in URI format. Check in the model's documentation for the supported mime types for the URI format metadata: type: object additionalProperties: {} required: - kind - file title: File Part description: >- A file content part that can contain either base64-encoded bytes or a URI reference. Used for images, documents, and other binary content in agent communications. ToolResultPart: type: object properties: kind: type: string enum: - tool_result tool_call_id: type: string minLength: 1 result: {} metadata: type: object additionalProperties: {} required: - kind - tool_call_id title: Tool Result Part description: >- The result of a tool execution. Contains the tool call ID for correlation and the result data from the tool invocation. ErrorPart: type: object properties: kind: type: string enum: - error error: type: string code: type: number required: - kind - error title: Error Part description: >- An error content part containing error information. Used when an error occurs during agent execution. CreateAgentResponse: type: object properties: _id: type: string description: The unique response ID task_id: type: string description: The agent execution task ID output: type: array items: $ref: '#/components/schemas/AgentResponseMessage' description: Array of messages from the agent execution created_at: type: string description: ISO timestamp of response creation model: type: string description: Model used in provider/model format usage: type: - object - 'null' properties: completion_tokens: type: number description: Number of tokens in the generated completion. prompt_tokens: type: number description: Number of tokens in the prompt. total_tokens: type: number description: >- Total number of tokens used in the request (prompt + completion). prompt_tokens_details: type: - object - 'null' properties: cached_tokens: type: - integer - 'null' cache_creation_tokens: type: - integer - 'null' audio_tokens: type: - integer - 'null' description: The number of audio input tokens consumed by the request. completion_tokens_details: type: - object - 'null' properties: reasoning_tokens: type: - number - 'null' accepted_prediction_tokens: type: - number - 'null' rejected_prediction_tokens: type: - number - 'null' audio_tokens: type: - integer - 'null' description: The number of audio output tokens produced by the response. description: Token usage from the agent execution finish_reason: type: string enum: - stop - length - tool_calls - content_filter - function_call - max_iterations - max_time description: The reason why the agent stopped generating pending_tool_calls: type: array items: type: object properties: id: type: string type: type: string enum: - function function: type: object properties: name: type: string arguments: type: string required: - id - type - function description: >- Tool calls awaiting user response (when finish_reason is function_call) telemetry: $ref: '#/components/schemas/Telemetry' required: - _id - task_id - output - created_at - model title: Create Agent Response description: Response type from the create-response endpoint. ResponseStreamingEvent: oneOf: - $ref: '#/components/schemas/ResponseStartedEvent' - $ref: '#/components/schemas/ResponseDoneEvent' - $ref: '#/components/schemas/ResponseFailedEvent' - $ref: '#/components/schemas/ToolStartedEvent' - $ref: '#/components/schemas/ToolDoneEvent' - $ref: '#/components/schemas/ToolFailedEvent' - $ref: '#/components/schemas/ToolReviewRequestedEvent' - $ref: '#/components/schemas/ToolReviewDoneEvent' - $ref: '#/components/schemas/PartDeltaEvent' - $ref: '#/components/schemas/PartDoneEvent' discriminator: propertyName: type mapping: response.started: $ref: '#/components/schemas/ResponseStartedEvent' response.done: $ref: '#/components/schemas/ResponseDoneEvent' response.failed: $ref: '#/components/schemas/ResponseFailedEvent' tool.started: $ref: '#/components/schemas/ToolStartedEvent' tool.done: $ref: '#/components/schemas/ToolDoneEvent' tool.failed: $ref: '#/components/schemas/ToolFailedEvent' tool.review.requested: $ref: '#/components/schemas/ToolReviewRequestedEvent' tool.review.done: $ref: '#/components/schemas/ToolReviewDoneEvent' part.delta: $ref: '#/components/schemas/PartDeltaEvent' part.done: $ref: '#/components/schemas/PartDoneEvent' title: Response Streaming Event description: >- Union of all possible streaming events. Each event has a type field for discrimination. AgentResponseMessage: type: object properties: messageId: type: string role: type: string enum: - user - agent - tool - system parts: type: array items: oneOf: - $ref: '#/components/schemas/TextPart' - $ref: '#/components/schemas/ErrorPart' - $ref: '#/components/schemas/DataPart' - $ref: '#/components/schemas/FilePart' - $ref: '#/components/schemas/ToolCallPart' - $ref: '#/components/schemas/ToolResultPart' discriminator: propertyName: kind mapping: text: $ref: '#/components/schemas/TextPart' error: $ref: '#/components/schemas/ErrorPart' data: $ref: '#/components/schemas/DataPart' file: $ref: '#/components/schemas/FilePart' tool_call: $ref: '#/components/schemas/ToolCallPart' tool_result: $ref: '#/components/schemas/ToolResultPart' metadata: type: object additionalProperties: {} required: - messageId - role - parts title: Agent Response Message description: Response message from an agent execution. Telemetry: type: object properties: trace_id: type: string description: The root trace ID for the agent execution span_id: type: string description: The span ID of the agent execution within the trace required: - trace_id - span_id title: Telemetry description: Telemetry information for correlating the response with traces ResponseStartedEvent: type: object properties: type: type: string enum: - response.started timestamp: type: string description: ISO timestamp of when the event occurred data: type: object properties: responseId: type: string description: Unique identifier for this response taskId: type: string description: >- The agent execution task ID. Use responseId for tracking instead. deprecated: true x-deprecation-notice: >- This field will be replaced by previous_response_id in a future version. Track the responseId from each response to use for continuations. model: type: string description: >- The model ID being used for this response in provider/model format workflowRunId: type: string description: >- Trace ID for this turn of the conversation (new for each continuation) userMessageId: type: string description: >- Server-generated ID for the user message. Use this ID for frontend state consistency. assistantMessageId: type: string description: >- Server-generated ID for the assistant message. Use this ID for frontend state consistency. telemetry: $ref: '#/components/schemas/Telemetry' required: - responseId - taskId - model - workflowRunId required: - type - timestamp - data title: Response Started Event description: >- Emitted when the agent begins processing. Contains identifiers for tracking the response. ResponseDoneEvent: type: object properties: type: type: string enum: - response.done timestamp: type: string description: ISO timestamp of when the event occurred data: type: object properties: finishReason: type: string enum: - stop - length - tool_calls - content_filter - function_call - max_iterations - max_time description: The reason why the agent stopped generating usage: type: object properties: completion_tokens: type: number description: Number of tokens in the generated completion. prompt_tokens: type: number description: Number of tokens in the prompt. total_tokens: type: number description: >- Total number of tokens used in the request (prompt + completion). prompt_tokens_details: type: - object - 'null' properties: cached_tokens: type: - integer - 'null' cache_creation_tokens: type: - integer - 'null' audio_tokens: type: - integer - 'null' description: >- The number of audio input tokens consumed by the request. completion_tokens_details: type: - object - 'null' properties: reasoning_tokens: type: - number - 'null' accepted_prediction_tokens: type: - number - 'null' rejected_prediction_tokens: type: - number - 'null' audio_tokens: type: - integer - 'null' description: >- The number of audio output tokens produced by the response. description: Token usage statistics for the complete response pendingToolCalls: type: array items: type: object properties: id: type: string description: Unique identifier for the tool call type: type: string enum: - function function: type: object properties: name: type: string description: The name of the function to call arguments: type: string description: The arguments to pass to the function as JSON string required: - id - type - function description: >- Tool calls awaiting user response (when finishReason is function_call) telemetry: $ref: '#/components/schemas/Telemetry' required: - finishReason required: - type - timestamp - data title: Response Done Event description: >- Emitted when the agent completes processing. Contains the finish reason and usage statistics. ResponseFailedEvent: type: object properties: type: type: string enum: - response.failed timestamp: type: string description: ISO timestamp of when the event occurred data: type: object properties: error: type: string description: Error message describing what went wrong code: type: number description: HTTP status code indicating the error type required: - error - code required: - type - timestamp - data title: Response Failed Event description: >- Emitted when an error occurs during agent execution. Contains error details. ToolStartedEvent: type: object properties: type: type: string enum: - tool.started timestamp: type: string description: ISO timestamp of when the event occurred data: type: object properties: toolId: type: string description: Unique identifier for the tool toolName: type: string description: Display name of the tool toolCallId: type: string description: Unique identifier for this specific tool call arguments: type: object additionalProperties: {} description: Arguments passed to the tool required: - toolId - toolCallId - arguments required: - type - timestamp - data title: Tool Started Event description: >- Emitted when a tool begins execution. Contains tool details and input arguments. ToolDoneEvent: type: object properties: type: type: string enum: - tool.done timestamp: type: string description: ISO timestamp of when the event occurred data: type: object properties: toolId: type: string description: Unique identifier for the tool in the tool registry toolCallId: type: string description: Unique identifier matching the tool call that was executed result: description: The result returned by the tool required: - toolId - toolCallId required: - type - timestamp - data title: Tool Done Event description: >- Emitted when a tool completes execution successfully. Contains the tool result. ToolFailedEvent: type: object properties: type: type: string enum: - tool.failed timestamp: type: string description: ISO timestamp of when the event occurred data: type: object properties: toolId: type: string description: Unique identifier for the tool in the tool registry toolCallId: type: string description: Unique identifier matching the tool call that failed error: type: string description: Error message describing why the tool failed required: - toolId - toolCallId - error required: - type - timestamp - data title: Tool Failed Event description: Emitted when a tool execution fails. Contains error details. ToolReviewRequestedEvent: type: object properties: type: type: string enum: - tool.review.requested timestamp: type: string description: ISO timestamp of when the event occurred data: type: object properties: toolId: type: string description: Unique identifier for the tool in the tool registry toolCallId: type: string description: The tool call ID requiring review toolName: type: string description: Name of the tool requiring approval arguments: type: object additionalProperties: {} description: Arguments that will be passed to the tool requiresApproval: type: boolean description: Whether approval is mandatory before execution required: - toolId - toolCallId - arguments - requiresApproval required: - type - timestamp - data title: Tool Review Requested Event description: >- Emitted when a tool action requires approval before execution. The execution will pause until reviewed. ToolReviewDoneEvent: type: object properties: type: type: string enum: - tool.review.done timestamp: type: string description: ISO timestamp of when the event occurred data: type: object properties: toolId: type: string description: Unique identifier for the tool in the tool registry toolCallId: type: string description: The tool call ID that was reviewed review: $ref: '#/components/schemas/ReviewOutcome' required: - toolId - toolCallId - review required: - type - timestamp - data title: Tool Review Done Event description: >- Emitted after a tool action has been reviewed. Contains the review decision. PartDeltaEvent: type: object properties: type: type: string enum: - part.delta timestamp: type: string description: ISO timestamp of when the event occurred data: type: object properties: partId: type: string description: >- Unique identifier for this part. Format: {kind}_{ulid}. Use to correlate with part.done event. example: text_01hxyz123abc delta: $ref: '#/components/schemas/PartDelta' required: - partId - delta required: - type - timestamp - data title: Part Delta Event description: >- Emitted for each content chunk streamed from the LLM. The delta field contains a discriminated union based on the kind field. PartDoneEvent: type: object properties: type: type: string enum: - part.done timestamp: type: string description: ISO timestamp of when the event occurred data: type: object properties: partId: type: string description: >- Unique identifier for this part. Matches the partId from part.delta events. example: text_01hxyz123abc part: allOf: - $ref: '#/components/schemas/PartDelta' - description: >- The complete part. Discriminated by kind field (text, reasoning, file, data). required: - partId - part required: - type - timestamp - data title: Part Done Event description: >- Emitted when a part has been fully streamed. Contains the complete part with all content. DataPart: type: object properties: kind: type: string enum: - data data: type: object additionalProperties: {} metadata: type: object additionalProperties: {} required: - kind - data title: Data Part description: >- A structured data part containing JSON-serializable key-value pairs. Used for passing structured information between agents and tools. ToolCallPart: type: object properties: kind: type: string enum: - tool_call tool_name: type: string tool_call_id: type: string minLength: 1 arguments: type: object additionalProperties: {} thought_signature: type: string metadata: type: object additionalProperties: {} required: - kind - tool_name - tool_call_id - arguments title: Tool Call Part description: >- A tool invocation request from an agent. Contains the tool name, unique call ID, and arguments for the tool execution. ReviewOutcome: type: string enum: - approved - rejected title: Review Outcome description: The review decision PartDelta: oneOf: - allOf: - $ref: '#/components/schemas/TextPart' - description: A message part containing text content - $ref: '#/components/schemas/ReasoningPart' - allOf: - $ref: '#/components/schemas/FilePart' - description: >- A message part containing file content, either embedded or referenced - allOf: - $ref: '#/components/schemas/DataPart' - description: >- A message part containing arbitrary structured data as key-value pairs discriminator: propertyName: kind mapping: text: $ref: '#/components/schemas/TextPart' reasoning: $ref: '#/components/schemas/ReasoningPart' file: $ref: '#/components/schemas/FilePart' data: $ref: '#/components/schemas/DataPart' description: >- The content chunk being streamed. Discriminated by kind field (text or reasoning). ReasoningPart: allOf: - $ref: '#/components/schemas/BasePart' - type: object properties: _id: type: string default: reasoning_01krm5rebgvd4xgjpst6hrcvj8 description: >- Unique identifier for the part. Format: reasoning_{ulid} (e.g., reasoning_01hxyz...) example: reasoning_01hxyz123abc kind: type: string enum: - reasoning description: Type discriminator indicating this is a reasoning part example: reasoning reasoning: type: string description: >- The reasoning or thought process behind the response. Used for chain-of-thought or extended thinking. example: Let me analyze this step by step... signature: type: string description: >- Optional cryptographic signature to verify the authenticity and integrity of the reasoning content example: sha256:a1b2c3d4e5f6... required: - kind - reasoning title: Reasoning Part description: A message part containing reasoning or chain-of-thought content BasePart: type: object properties: _id: type: string description: >- Unique identifier for the part. Format: {kind}_{ulid} (e.g., text_01hxyz...) example: text_01hxyz123abc metadata: type: object additionalProperties: {} description: >- Optional metadata associated with the message part. Can store arbitrary key-value pairs for custom data. Maximum size of 50KB and maximum of 20 keys. example: source: user_input timestamp: '2024-01-15T10:30:00Z' required: - _id title: Base Part description: Base schema for all message parts securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: JWT ````