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

> Create and retrieve agent responses with the Node.js and Python SDKs, including conversation output, tool calls, token usage, and task status.

## Agents.Responses

### Create a Response <Badge color="yellow" size="lg" stroke>\[deprecated]</Badge>

Create an agent response for a given message. Return the complete conversation including messages, tool interactions, and token usage.

<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({
      agentKey: "<value>",
      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",
        ],
      },
    });

    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": List[Union[TextPart, FilePart, ToolResultPart, ErrorPart]],  # required
        },
        "task_id": Optional[str],
        "variables": Dict[str, Any],  # optional
        "identity": {  # optional
            "id": str,  # required
            "display_name": Optional[str],
            "email": Optional[str],
            "metadata": List[Dict[str, Any]],  # optional
            "logo_url": Optional[str],
            "tags": List[str],  # optional
        },
        "contact": {  # optional
            "id": str,  # required
            "display_name": Optional[str],
            "email": Optional[str],
            "metadata": List[Dict[str, Any]],  # optional
            "logo_url": Optional[str],
            "tags": List[str],  # optional
        },
        "thread": {  # optional
            "id": str,  # required
            "tags": List[str],  # optional
        },
        "memory": {  # optional
            "entity_id": str,  # required
        },
        "metadata": Dict[str, Any],  # optional
        "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: RoleUserMessage | RoleToolMessage;  // required
        parts: (TextPart | FilePart | ToolResultPart | ErrorPart)[];  // 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?: "text" | "jinja" | "mustache";
      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": List[Union[TextPart, ErrorPart, DataPart, FilePart, ToolCallPart, ToolResultPart]],
            "metadata": Dict[str, Any],  # optional
        }],
        "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": Optional[int],
                "cache_creation_tokens": Optional[int],
                "audio_tokens": Optional[int],
            },
            "completion_tokens_details": {  # optional
                "reasoning_tokens": Optional[float],
                "accepted_prediction_tokens": Optional[float],
                "rejected_prediction_tokens": Optional[float],
                "audio_tokens": Optional[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;
      taskId: string;
      output: {
        messageId: string;
        role: "user" | "agent" | "tool" | "system";
        parts: (TextPart | ErrorPart | DataPart | FilePart | ToolCallPart | ToolResultPart)[];
        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?: "stop" | "length" | "tool_calls" | "content_filter" | "function_call" | "max_iterations" | "max_time";
      pendingToolCalls?: {
        id: string;
        type: "function";
        function: {
          name?: string;
          arguments?: string;
        };
      }[];
      telemetry?: {
        traceId: string;
        spanId: string;
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Retrieve a Response <Badge color="yellow" size="lg" stroke>\[deprecated]</Badge>

Retrieve an agent response by task ID, including output, model info, token usage, and execution status.

<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": List[Union[TextPart, ErrorPart, DataPart, FilePart, ToolCallPart, ToolResultPart]],
            "metadata": Dict[str, Any],  # optional
        }],
        "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": Optional[int],
                "cache_creation_tokens": Optional[int],
                "audio_tokens": Optional[int],
            },
            "completion_tokens_details": {  # optional
                "reasoning_tokens": Optional[float],
                "accepted_prediction_tokens": Optional[float],
                "rejected_prediction_tokens": Optional[float],
                "audio_tokens": Optional[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: "user" | "agent" | "tool" | "system";
        parts: (TextPart | ErrorPart | DataPart | FilePart | ToolCallPart | ToolResultPart)[];
        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?: "stop" | "length" | "tool_calls" | "content_filter" | "function_call" | "max_iterations" | "max_time";
      pendingToolCalls?: {
        id: string;
        type: "function";
        function: {
          name?: string;
          arguments?: string;
        };
      }[];
      telemetry?: {
        traceId: string;
        spanId: string;
      };
      status: "in_progress" | "completed" | "failed";
      error?: string;
    }
    ```
  </CodeGroup>
</Expandable>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.