> ## 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.

# Agents.Responses SDK Reference

> SDK reference for the Agents.Responses API, available in Node.js and Python.

## Agents.Responses

### Create a 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.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.agents.responses.create(agent_key="<value>", message={
          "role": "tool",
          "parts": [],
      }, identity={
          "id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
          "display_name": "Jane Doe",
          "email": "jane.doe@example.com",
          "metadata": [
              {
                  "department": "Engineering",
                  "role": "Senior Developer",
              },
          ],
          "logo_url": "https://example.com/avatars/jane-doe.jpg",
          "tags": [
              "hr",
              "engineering",
          ],
      }, thread={
          "id": "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
          "tags": [
              "customer-support",
              "priority-high",
          ],
      }, background=False, stream=False)

      with res as event_stream:
          for event in event_stream:
              # handle event
              print(event, flush=True)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.agents.responses.create({
      message: {
        role: "tool",
        parts: [],
      },
      identity: {
        id: "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
        displayName: "Jane Doe",
        email: "jane.doe@example.com",
        metadata: [
          {
            "department": "Engineering",
            "role": "Senior Developer",
          },
        ],
        logoUrl: "https://example.com/avatars/jane-doe.jpg",
        tags: [
          "hr",
          "engineering",
        ],
      },
      thread: {
        id: "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
        tags: [
          "customer-support",
          "priority-high",
        ],
      },
    }, "<value>");

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "agent_key": str,  # required
        "message": {  # required
            "message_id": Optional[str],
            "role": Union[RoleUserMessage, RoleToolMessage],  # required
            "parts": Union[TextPart, FilePart, ToolResultPart, ErrorPart],  # required
        },
        "task_id": Optional[str],
        "variables": Dict[str, Any],
        "identity": {  # optional
            "id": str,  # required
            "display_name": Optional[str],
            "email": Optional[str],
            "metadata": List[Dict[str, Any]],
            "logo_url": Optional[str],
            "tags": List[str],
        },
        "contact": {  # optional
            "id": str,  # required
            "display_name": Optional[str],
            "email": Optional[str],
            "metadata": List[Dict[str, Any]],
            "logo_url": Optional[str],
            "tags": List[str],
        },
        "thread": {  # optional
            "id": str,  # required
            "tags": List[str],
        },
        "memory": {  # optional
            "entity_id": str,  # required
        },
        "metadata": Dict[str, Any],
        "engine": Optional[Literal["text", "jinja", "mustache"]],
        "configuration": {  # optional
            "blocking": Optional[bool],
        },
        "background": Optional[bool],
        "stream": Optional[bool],
        "conversation": {  # optional
            "id": str,  # required
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      agentKey: string;  // required
      taskId?: string;
      message: {  // required
        messageId?: string;
        role: string;  // required
        parts: string;  // required
      };
      variables?: Record<string, any>;
      identity?: {
        id: string;  // required
        displayName?: string;
        email?: string;
        metadata?: Record<string, any>[];
        logoUrl?: string;
        tags?: string[];
      };
      ~~`contact`~~?: {
        id: string;  // required
        displayName?: string;
        email?: string;
        metadata?: Record<string, any>[];
        logoUrl?: string;
        tags?: string[];
      };
      thread?: {
        id: string;  // required
        tags?: string[];
      };
      memory?: {
        entityId: string;  // required
      };
      metadata?: Record<string, any>;
      engine?: string;
      configuration?: {
        blocking?: boolean;
      };
      background?: boolean;
      stream?: boolean;
      conversation?: {
        id: string;  // required
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "task_id": str,
        "output": {
            "message_id": str,
            "role": Literal["user", "agent", "tool", "system"],
            "parts": Union[TextPart, ErrorPart, DataPart, FilePart, ToolCallPart, ToolResultPart],
            "metadata": Dict[str, Any],
        },
        "created_at": str,
        "model": str,
        "usage": {  # optional
            "completion_tokens": Optional[float],
            "prompt_tokens": Optional[float],
            "total_tokens": Optional[float],
            "prompt_tokens_details": {  # optional
                "cached_tokens": OptionalNullable[int],
                "cache_creation_tokens": OptionalNullable[int],
                "audio_tokens": OptionalNullable[int],
            },
            "completion_tokens_details": {  # optional
                "reasoning_tokens": OptionalNullable[float],
                "accepted_prediction_tokens": OptionalNullable[float],
                "rejected_prediction_tokens": OptionalNullable[float],
                "audio_tokens": OptionalNullable[int],
            },
        },
        "finish_reason": Optional[Literal["stop", "length", "tool_calls", "content_filter", "function_call", "max_iterations", "max_time"]],
        "pending_tool_calls": {  # optional
            "id": str,
            "type": Literal["function"],
            "function": {
                "name": Optional[str],
                "arguments": Optional[str],
            },
        },
        "telemetry": {  # optional
            "trace_id": str,
            "span_id": str,
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      task_id: string;
      output: {
        message_id: string;
        role: "user" | "agent" | "tool" | "system";
        parts: TextPart | ErrorPart | DataPart | FilePart | ToolCallPart | ToolResultPart;
        metadata?: Record<string, unknown>;
      };
      created_at: string;
      model: string;
      usage?: {
        completion_tokens?: number | undefined;
        prompt_tokens?: number | undefined;
        total_tokens?: number | undefined;
        prompt_tokens_details?: {
          cached_tokens?: number | null | undefined;
          cache_creation_tokens?: number | null | undefined;
          audio_tokens?: number | null | undefined;
        };
        completion_tokens_details?: {
          reasoning_tokens?: number | null | undefined;
          accepted_prediction_tokens?: number | null | undefined;
          rejected_prediction_tokens?: number | null | undefined;
          audio_tokens?: number | null | undefined;
        };
      };
      finish_reason?: "stop" | "length" | "tool_calls" | "content_filter" | "function_call" | "max_iterations" | "max_time" | undefined;
      pending_tool_calls?: {
        id: string;
        type: "function";
        function: {
          name?: string | undefined;
          arguments?: string | undefined;
        };
      };
      telemetry?: {
        trace_id: string;
        span_id: string;
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Retrieve a Response

Retrieves the current state of an agent response by task ID. Returns the response output, model information, token usage, and execution status. When the agent is still processing, the output array will be empty and status will be `in_progress`. Once completed, the response includes the full output, usage statistics, and finish reason.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.agents.responses.get(agent_key="<value>", task_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.agents.responses.get({
      agentKey: "<value>",
      taskId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "agent_key": str,  # required
        "task_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      agentKey: string;  // required
      taskId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "task_id": str,
        "output": {
            "message_id": str,
            "role": Literal["user", "agent", "tool", "system"],
            "parts": Union[TextPart, ErrorPart, DataPart, FilePart, ToolCallPart, ToolResultPart],
            "metadata": Dict[str, Any],
        },
        "created_at": str,
        "model": str,
        "usage": {  # optional
            "completion_tokens": Optional[float],
            "prompt_tokens": Optional[float],
            "total_tokens": Optional[float],
            "prompt_tokens_details": {  # optional
                "cached_tokens": OptionalNullable[int],
                "cache_creation_tokens": OptionalNullable[int],
                "audio_tokens": OptionalNullable[int],
            },
            "completion_tokens_details": {  # optional
                "reasoning_tokens": OptionalNullable[float],
                "accepted_prediction_tokens": OptionalNullable[float],
                "rejected_prediction_tokens": OptionalNullable[float],
                "audio_tokens": OptionalNullable[int],
            },
        },
        "finish_reason": Optional[Literal["stop", "length", "tool_calls", "content_filter", "function_call", "max_iterations", "max_time"]],
        "pending_tool_calls": {  # optional
            "id": str,
            "type": Literal["function"],
            "function": {
                "name": Optional[str],
                "arguments": Optional[str],
            },
        },
        "telemetry": {  # optional
            "trace_id": str,
            "span_id": str,
        },
        "status": Literal["in_progress", "completed", "failed"],
        "error": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      taskId: string;
      output: {
        messageId: string;
        role: string;
        parts: string;
        metadata?: Record<string, any>;
      };
      createdAt: string;
      model: string;
      usage?: {
        completionTokens?: number;
        promptTokens?: number;
        totalTokens?: number;
        promptTokensDetails?: {
          cachedTokens?: number;
          cacheCreationTokens?: number;
          audioTokens?: number;
        };
        completionTokensDetails?: {
          reasoningTokens?: number;
          acceptedPredictionTokens?: number;
          rejectedPredictionTokens?: number;
          audioTokens?: number;
        };
      };
      finishReason?: string;
      pendingToolCalls?: {
        id: string;
        type: string;
        function: {
          name?: string;
          arguments?: string;
        };
      };
      telemetry?: {
        traceId: string;
        spanId: string;
      };
      status: string;
      error?: string;
    }
    ```
  </CodeGroup>
</Expandable>