---
title: "Create response"
method: POST
path: "/v2/agents/{agent_key}/responses"
tags: ["Agents"]
deprecated: true
---

# Create response

`POST /v2/agents/{agent_key}/responses`

> **Deprecated.**

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.

## Path parameters

- `agent_key` string, required — The unique key of identifier of the agent to invoke

## Request body

- AgentResponseRequest — Request body for creating an agent response. Extends A2AInvokeRequest with response options. Matches POST /v2/agents/{key}/responses
  - `task_id` string — 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` object, required — The A2A message to send to the agent (user input or tool results)
    - `messageId` string — Optional A2A message ID in ULID format
    - `role` union, required — Message role (user or tool for continuing executions)
      - 'user' — Message from the end user
      - 'tool' — Message containing tool execution results
    - `parts` union[], required — A2A message parts (text, file, or tool_result only). Note: Tool role messages must only contain tool_result parts.
      - union — 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.
        - object — Text content part. Use this to send text messages to the agent.
          - `kind` 'text', required
          - `text` string, required
        - object — File attachment part. Use this to send files (images, documents, etc.) to the agent for processing.
          - `kind` 'file', required
          - `file` union, required
            - object — Binary in base64 format. Check in the model's documentation for the supported mime types for the binary format.
              - …
            - object — File in URI format. Check in the model's documentation for the supported mime types for the URI format
              - …
          - `metadata` object
        - object — 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.
          - `kind` 'tool_result', required
          - `tool_call_id` string, required
          - `result` unknown
          - `metadata` object
        - object — Error content part. Generated by the system when an error occurs during agent execution.
          - `kind` 'error', required
          - `error` string, required
          - `code` number
  - `variables` object — Optional variables for template replacement in system prompt, instructions, and messages
  - `identity` object — Information about the identity making the request. If the identity does not exist, it will be created automatically.
    - `id` string, required — Unique identifier for the contact
    - `display_name` string — Display name of the contact
    - `email` string, email — Email address of the contact
    - `metadata` object[] — A hash of key/value pairs containing any other data about the contact
    - `logo_url` string — URL to the contact's avatar or logo
    - `tags` string[] — A list of tags associated with the contact
  - `contact` object — @deprecated Use identity instead. Information about the contact making the request.
    - `id` string, required — Unique identifier for the contact
    - `display_name` string — Display name of the contact
    - `email` string, email — Email address of the contact
    - `metadata` object[] — A hash of key/value pairs containing any other data about the contact
    - `logo_url` string — URL to the contact's avatar or logo
    - `tags` string[] — A list of tags associated with the contact
  - `thread` object — Thread information to group related requests
    - `id` string, required — Unique thread identifier to group related invocations.
    - `tags` string[] — Optional tags to differentiate or categorize threads
  - `memory` object — Memory configuration for the agent execution. Used to associate memory stores with specific entities like users or sessions.
    - `entity_id` string, required — 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.
  - `metadata` object — Optional metadata for the agent invocation as key-value pairs that will be included in traces
  - `engine` 'text' | 'jinja' | 'mustache' — Override template engine for this invocation. If not provided, uses the agent default.
  - `configuration` object — Configuration options for the agent invocation
    - `blocking` boolean — 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.
  - `background` boolean — If true, returns immediately without waiting for completion. If false (default), waits until the agent becomes inactive or errors.
  - `stream` boolean — If true, returns Server-Sent Events (SSE) streaming response with real-time events. If false (default), returns standard JSON response.
  - `conversation` object — Conversation context for chat studio integration
    - `_id` string, required — Unique ULID identifier for the conversation, prefixed with "conv_". Used to link agent executions to a specific conversation thread.

## Response `200`

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.

- CreateAgentResponse — Response type from the create-response endpoint.
  - `_id` string, required — The unique response ID
  - `task_id` string, required — The agent execution task ID
  - `output` AgentResponseMessage[], required — Array of messages from the agent execution
    - `messageId` string, required
    - `role` 'user' | 'agent' | 'tool' | 'system', required
    - `parts` union[], required
      - union
        - TextPart — A text content part containing plain text or markdown. Used for agent messages, user input, and text-based responses.
          - `kind` 'text', required
          - `text` string, required
        - ErrorPart — An error content part containing error information. Used when an error occurs during agent execution.
          - `kind` 'error', required
          - `error` string, required
          - `code` number
        - DataPart — A structured data part containing JSON-serializable key-value pairs. Used for passing structured information between agents and tools.
          - `kind` 'data', required
          - `data` object, required
          - `metadata` object
        - FilePart — 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.
          - `kind` 'file', required
          - `file` union, required
            - object — Binary in base64 format. Check in the model's documentation for the supported mime types for the binary format.
              - …
            - object — File in URI format. Check in the model's documentation for the supported mime types for the URI format
              - …
          - `metadata` object
        - ToolCallPart — A tool invocation request from an agent. Contains the tool name, unique call ID, and arguments for the tool execution.
          - `kind` 'tool_call', required
          - `tool_name` string, required
          - `tool_call_id` string, required
          - `arguments` object, required
          - `thought_signature` string
          - `metadata` object
        - ToolResultPart — The result of a tool execution. Contains the tool call ID for correlation and the result data from the tool invocation.
          - `kind` 'tool_result', required
          - `tool_call_id` string, required
          - `result` unknown
          - `metadata` object
    - `metadata` object
  - `created_at` string, required — ISO timestamp of response creation
  - `model` string, required — Model used in provider/model format
  - `usage` object, nullable — Token usage from the agent execution
    - `completion_tokens` number — Number of tokens in the generated completion.
    - `prompt_tokens` number — Number of tokens in the prompt.
    - `total_tokens` number — Total number of tokens used in the request (prompt + completion).
    - `prompt_tokens_details` object, nullable
      - `cached_tokens` integer, nullable
      - `cache_creation_tokens` integer, nullable
      - `audio_tokens` integer, nullable — The number of audio input tokens consumed by the request.
    - `completion_tokens_details` object, nullable
      - `reasoning_tokens` number, nullable
      - `accepted_prediction_tokens` number, nullable
      - `rejected_prediction_tokens` number, nullable
      - `audio_tokens` integer, nullable — The number of audio output tokens produced by the response.
  - `finish_reason` 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'function_call' | 'max_iterations' | 'max_time' — The reason why the agent stopped generating
  - `pending_tool_calls` object[] — Tool calls awaiting user response (when finish_reason is function_call)
    - `id` string, required
    - `type` 'function', required
    - `function` object, required
      - `name` string
      - `arguments` string
  - `telemetry` Telemetry — Telemetry information for correlating the response with traces
    - `trace_id` string, required — The root trace ID for the agent execution
    - `span_id` string, required — The span ID of the agent execution within the trace

---

[API](https://skmtc.net/orq-ai/apis/orq-ai-api.md) · [All operations](https://skmtc.net/orq-ai/apis/orq-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/orq-ai/orq-ai-api/revisions/deb8d376faee/schema)