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

# Run Agents

> Execute AI agents in Orq.ai. Send messages, pass variables, attach files, continue tasks, and trace executions through the AI Studio, API, or Orq MCP.

Execute agents already configured. For building and configuring agents, see [Build Agents](/docs/agents/build).

## Run Agents

<Note>For Python and Node.js client libraries, see [Orq SDKs](/reference/client-libraries).</Note>

Send a message to an agent using the Responses API:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.orq.ai/v2/agents/my-agent/responses \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "background": false,
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "Help me plan a microservices architecture for our e-commerce platform."
        }
      ]
    }
  }'
  ```

  ```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:
      response = orq.agents.responses.create(
          agent_key="my-agent",
          background=False,
          message={
              "role": "user",
              "parts": [
                  {
                      "kind": "text",
                      "text": "Help me plan a microservices architecture for our e-commerce platform."
                  }
              ]
          }
      )
      print(response)
  ```

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

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

  const response = await orq.agents.responses.create({
    background: false,
    message: {
      role: 'user',
      parts: [
        {
          kind: 'text',
          text: 'Help me plan a microservices architecture for our e-commerce platform.'
        }
      ]
    }
  }, 'my-agent');

  console.log(response);
  ```
</CodeGroup>

With `background: false` (default), the call waits for the agent to finish and returns a completed `task` object including an `output` array:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "01K6D8QESESZ6SAXQPJPFQXPFT",
  "contextId": "0ae12412-cdea-408e-a165-9ff8086db400",
  "kind": "task",
  "status": {
    "state": "completed",
    "timestamp": "2025-09-30T12:14:35.123Z",
    "message": {
      "role": "agent",
      "parts": [{ "kind": "text", "text": "Here's a microservices architecture..." }]
    }
  },
  "output": [
    {
      "parts": [{ "kind": "text", "text": "Here's a microservices architecture..." }]
    }
  ],
  "metadata": {
    "orq_agent_key": "my-agent"
  }
}
```

Set `background: true` to return immediately without waiting: the response will have `status.state: "submitted"` and no `output`. Use the returned `id` to continue the conversation.

<Tip>See the full [Create Response API reference](/reference/agents/create-response).</Tip>

### Pass Variables

Pass variables in the `variables` field of the execution request:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.orq.ai/v2/agents/my-agent/responses \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "message": {
        "role": "user",
        "parts": [{"kind": "text", "text": "I need help with my account."}]
      },
      "variables": {
        "user_name": "John Smith",
        "user_role": "admin",
        "company_name": "Acme Corp"
      }
    }'
  ```

  ```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:
      response = orq.agents.responses.create(
          agent_key="my-agent",
          message={
              "role": "user",
              "parts": [{"kind": "text", "text": "I need help with my account."}],
          },
          variables={
              "user_name": "John Smith",
              "user_role": "admin",
              "company_name": "Acme Corp",
          },
      )
      print(response.output[0].parts[0].text)
  ```

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

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

  const response = await orq.agents.responses.create({
    message: {
      role: 'user',
      parts: [{ kind: 'text', text: 'I need help with my account.' }],
    },
    variables: {
      user_name: 'John Smith',
      user_role: 'admin',
      company_name: 'Acme Corp',
    },
  }, 'my-agent');

  console.log(response.output[0].parts[0].text);
  ```
</CodeGroup>

To define which variables the agent uses and configure templating, see [Build Agents: Variables and Templates](/docs/agents/build#variables-and-templates).

### Attach Files

Attach files in the `parts` array of the message:

* **Images**: Via URL (`uri`) or base64 encoding (`bytes`)
* **PDFs**: Base64 encoding only (`bytes`). URI links are not supported for PDFs.
* **MIME Types**: Required. Specify the correct `mimeType` (e.g. `image/jpeg`, `application/pdf`).

<Warning>
  Verify the chosen model supports the file types in use. Vision models are required for image and PDF processing.
</Warning>

**Attach an image via URL:**

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.orq.ai/v2/agents/image-classifier/responses \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "What can you see in this image?"
        },
        {
          "kind": "file",
          "file": {
            "uri": "https://example.com/image.jpg",
            "mimeType": "image/jpeg",
            "name": "image.jpg"
          }
        }
      ]
    }
  }'
  ```

  ```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:
      response = orq.agents.responses.create(
          agent_key="image-classifier",
          message={
              "role": "user",
              "parts": [
                  {"kind": "text", "text": "What can you see in this image?"},
                  {
                      "kind": "file",
                      "file": {
                          "uri": "https://example.com/image.jpg",
                          "mimeType": "image/jpeg",
                          "name": "image.jpg"
                      }
                  }
              ]
          }
      )
      print(response)
  ```

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

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

  const response = await orq.agents.responses.create({
    message: {
      role: 'user',
      parts: [
        { kind: 'text', text: 'What can you see in this image?' },
        {
          kind: 'file',
          file: {
            uri: 'https://example.com/image.jpg',
            mimeType: 'image/jpeg',
            name: 'image.jpg'
          }
        }
      ]
    }
  }, 'image-classifier');

  console.log(response);
  ```
</CodeGroup>

**Attach a PDF via base64:**

Convert the file to base64 first:

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
import base64

def file_to_base64(file_path: str) -> str:
    with open(file_path, "rb") as file:
        return base64.b64encode(file.read()).decode("utf-8")

pdf_base64 = file_to_base64("path/to/document.pdf")
```

Then include it in the message:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "kind": "file",
  "file": {
    "bytes": "<base64-encoded-content>",
    "mimeType": "application/pdf",
    "name": "document.pdf"
  }
}
```

<Tip>See the full [Create Response API reference](/reference/agents/create-response).</Tip>

### Continue a Task

<Tabs>
  <Tab title="API & SDK" icon="code">
    After receiving a task response, continue the conversation by passing the previously received `task_id` in the next request. The agent maintains full context from previous exchanges.

    When polling task state, a task in `input-required` state means the agent is waiting and ready for continuation (the agent is in `inactive` state). Pass the same `task_id` to resume.

    <CodeGroup>
      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl -X POST https://api.orq.ai/v2/agents/my-agent/responses \
        -H "Authorization: Bearer $ORQ_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
        "task_id": "01K6D8QESESZ6SAXQPJPFQXPFT",
        "background": false,
        "message": {
          "role": "user",
          "parts": [
            {
              "kind": "text",
              "text": "Can you expand on the challenges section?"
            }
          ]
        }
      }'
      ```

      ```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:
          response = orq.agents.responses.create(
              agent_key="my-agent",
              task_id="01K6D8QESESZ6SAXQPJPFQXPFT",
              background=False,
              message={
                  "role": "user",
                  "parts": [
                      {
                          "kind": "text",
                          "text": "Can you expand on the challenges section?"
                      }
                  ]
              }
          )
          print(response)
      ```

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

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

      const response = await orq.agents.responses.create({
        taskId: '01K6D8QESESZ6SAXQPJPFQXPFT',
        background: false,
        message: {
          role: 'user',
          parts: [
            {
              kind: 'text',
              text: 'Can you expand on the challenges section?'
            }
          ]
        }
      }, 'my-agent');

      console.log(response);
      ```
    </CodeGroup>

    The continuation returns a new task ID for the extended conversation. The agent retains full context from all prior turns.

    <Tip>See the full [Create Response API reference](/reference/agents/create-response).</Tip>
  </Tab>

  <Tab title="MCP" icon="https://mintcdn.com/orqai/i7ZhKI7LFRfXU7ox/images/logos/mcp.svg?fit=max&auto=format&n=i7ZhKI7LFRfXU7ox&q=85&s=cef7916eb5fe1f6bb97541398d3f7639" width="16" height="16" data-path="images/logos/mcp.svg">
    Task continuation requires direct API or SDK calls. Use `list_traces` to inspect previous runs and verify task states:

    ```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
    Show me the latest traces for the "support-bot" agent to see which tasks are still active
    ```

    The assistant uses `list_traces` filtered to the agent to surface active and inactive task states.
  </Tab>
</Tabs>

### Use Memory Stores

To call the Agent with a memory store, we'll use the [Responses API](/reference/agents/create-response) with an Embedded message and Linked memory.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST https://api.orq.ai/v2/agents/agent-memories/responses \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
    "memory": {
      "entity_id": "customer_456"
    },
    "message": {
      "role": "user",
      "parts": [
        {
          "kind": "text",
          "text": "Do you remember what is my name?"
        }
      ]
    }
  }'
  ```

  ```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:
      response = orq.agents.responses.create(
          agent_key="agent-memories",
          memory={
              "entity_id": "customer_456"
          },
          message={
              "role": "user",
              "parts": [
                  {
                      "kind": "text",
                      "text": "Do you remember what is my name?"
                  }
              ]
          }
      )
      print(response)
  ```

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

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

  const response = await orq.agents.responses.create({
    memory: {
      entityId: 'customer_456',
    },
    message: {
      role: 'user',
      parts: [
        {
          kind: 'text',
          text: 'Do you remember what is my name?',
        },
      ],
    },
  }, 'agent-memories');

  console.log(response);
  ```
</CodeGroup>

<Tip>
  You can use multiple memory stores per call, ensure that the `entity_id` sent during the calls maps the same way to all previously declared memory stores during agent creation.
</Tip>

## Agent and Task States

<Tabs>
  <Tab title="AI Studio" icon="https://mintcdn.com/orqai/My16MDKJXrKALEHC/images/logos/ai-studio-round.svg?fit=max&auto=format&n=My16MDKJXrKALEHC&q=85&s=ac04dd509320d58ab9701cb6d6137733" width="100" height="100" data-path="images/logos/ai-studio-round.svg">
    <Warning>
      Agent execution can take a long time. If the agent appears to be hanging, it is most likely still running. Wait and check the panel again later.
    </Warning>

    **Agent states:**

    | State             | Description                                                    |
    | ----------------- | -------------------------------------------------------------- |
    | Active            | Execution in progress; continuation requests blocked           |
    | Inactive          | Waiting for user input or tool results; ready for continuation |
    | Error             | Execution failed; continuation blocked                         |
    | Approval Required | Tool execution requires manual approval (coming soon)          |

    **Task states:**

    | State          | Description                            |
    | -------------- | -------------------------------------- |
    | Submitted      | Task created and queued for execution  |
    | Working        | Agent actively processing              |
    | Input Required | Waiting for user input or tool results |
    | Completed      | Task finished successfully             |
    | Failed         | Task encountered an error              |
    | Canceled       | Task was manually canceled             |
  </Tab>

  <Tab title="API & SDK" icon="code">
    **Agent states:**

    | State               | Description                                                    |
    | ------------------- | -------------------------------------------------------------- |
    | `active`            | Execution in progress; continuation requests blocked           |
    | `inactive`          | Waiting for user input or tool results; ready for continuation |
    | `error`             | Execution failed; continuation blocked                         |
    | `approval_required` | Tool execution requires manual approval (coming soon)          |

    **Task states:**

    | State            | Description                            |
    | ---------------- | -------------------------------------- |
    | `submitted`      | Task created and queued for execution  |
    | `working`        | Agent actively processing              |
    | `input-required` | Waiting for user input or tool results |
    | `completed`      | Task finished successfully             |
    | `failed`         | Task encountered an error              |
    | `canceled`       | Task was manually canceled             |

    An agent in `inactive` state accepts continuation requests. An agent in `active`, `error`, or `approval_required` state does not.
  </Tab>

  <Tab title="MCP" icon="https://mintcdn.com/orqai/i7ZhKI7LFRfXU7ox/images/logos/mcp.svg?fit=max&auto=format&n=i7ZhKI7LFRfXU7ox&q=85&s=cef7916eb5fe1f6bb97541398d3f7639" width="16" height="16" data-path="images/logos/mcp.svg">
    **Inspect task states through traces:**

    ```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
    Show me the last 10 traces for "support-bot" and summarize their completion states
    ```

    The assistant uses `list_traces` filtered to the agent and surfaces the state distribution.
  </Tab>
</Tabs>

## Multi-Agent Workflows

<Tabs>
  <Tab title="AI Studio" icon="https://mintcdn.com/orqai/My16MDKJXrKALEHC/images/logos/ai-studio-round.svg?fit=max&auto=format&n=My16MDKJXrKALEHC&q=85&s=ac04dd509320d58ab9701cb6d6137733" width="100" height="100" data-path="images/logos/ai-studio-round.svg">
    Multi-agent workflows are configured at the agent level. Each agent in a team is created individually, then the orchestrator references sub-agents through its `team_of_agents` configuration.

    The **Description** field on each sub-agent is critical: orchestrators use it to decide when to delegate.

    <Info>
      To configure multi-agent setups, see [Build Agents: Instructions](/docs/agents/build#configure-instructions) for how to write descriptions that enable effective delegation.
    </Info>
  </Tab>

  <Tab title="API & SDK" icon="code">
    Multi-agent workflows use a hierarchical system:

    * **Orchestrator**: Main agent that delegates tasks using `call_sub_agent`.
    * **Sub-agents**: Specialized agents for specific functions.
    * **Delegation**: Automatic routing based on sub-agent descriptions and capabilities.

    **Step 1: Create sub-agents.**

    Create each specialized agent individually. The `description` field drives orchestrator delegation decisions.

    **Step 2: Create the orchestrator.**

    Reference sub-agents in the `team_of_agents` array. Include `retrieve_agents` and `call_sub_agent` tools.

    <CodeGroup>
      ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
      curl -X POST https://api.orq.ai/v2/agents \
        -H "Authorization: Bearer $ORQ_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
        "key": "orchestrator",
        "role": "Task Coordinator",
        "description": "Coordinates specialized agents to handle diverse user requests",
        "instructions": "Answer the user using your sub-agents. Use retrieve_agents to discover available agents, then call_sub_agent to delegate tasks based on their capabilities.",
        "settings": {
          "max_iterations": 15,
          "max_execution_time": 600,
          "tools": [
            { "type": "retrieve_agents" },
            { "type": "call_sub_agent" }
          ]
        },
        "model": "openai/gpt-4o",
        "path": "Default/agents",
        "team_of_agents": [
          { "key": "specialist-a", "role": "Handles domain A" },
          { "key": "specialist-b", "role": "Handles domain B" }
        ]
      }'
      ```

      ```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:
          orchestrator = orq.agents.create(
              key="orchestrator",
              role="Task Coordinator",
              description="Coordinates specialized agents to handle diverse user requests",
              instructions="Answer the user using your sub-agents. Use retrieve_agents to discover available agents, then call_sub_agent to delegate tasks based on their capabilities.",
              path="Default/agents",
              model="openai/gpt-4o",
              settings={
                  "max_iterations": 15,
                  "max_execution_time": 600,
                  "tools": [
                      {"type": "retrieve_agents"},
                      {"type": "call_sub_agent"}
                  ]
              },
              team_of_agents=[
                  {"key": "specialist-a", "role": "Handles domain A"},
                  {"key": "specialist-b", "role": "Handles domain B"}
              ]
          )
      ```

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

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

      const orchestrator = await orq.agents.create({
        key: 'orchestrator',
        role: 'Task Coordinator',
        description: 'Coordinates specialized agents to handle diverse user requests',
        instructions: 'Answer the user using your sub-agents. Use retrieve_agents to discover available agents, then call_sub_agent to delegate tasks based on their capabilities.',
        path: 'Default/agents',
        model: 'openai/gpt-4o',
        settings: {
          maxIterations: 15,
          maxExecutionTime: 600,
          tools: [
            { type: 'retrieve_agents' },
            { type: 'call_sub_agent' }
          ]
        },
        teamOfAgents: [
          { key: 'specialist-a', role: 'Handles domain A' },
          { key: 'specialist-b', role: 'Handles domain B' }
        ]
      });
      ```
    </CodeGroup>

    **Step 3: Invoke the orchestrator.**

    Invoke the orchestrator the same way as any other agent. It handles delegation internally.

    <Warning>
      Orchestrator agents must include `retrieve_agents` to discover sub-agents before delegating. Add explicit instructions: "Use `retrieve_agents` to see what specialized agents are available, then `call_sub_agent` to delegate."
    </Warning>

    <Tip>Update the orchestrator at any time with [`PATCH /v2/agents/{key}`](/reference/agents/update-agent) to add or remove sub-agents from `team_of_agents`.</Tip>
  </Tab>

  <Tab title="MCP" icon="https://mintcdn.com/orqai/i7ZhKI7LFRfXU7ox/images/logos/mcp.svg?fit=max&auto=format&n=i7ZhKI7LFRfXU7ox&q=85&s=cef7916eb5fe1f6bb97541398d3f7639" width="16" height="16" data-path="images/logos/mcp.svg">
    **Find all agents available as sub-agents:**

    ```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
    Search for all agents in the Default/agents project
    ```

    The assistant uses `search_entities` with `type: "agent"` to list available agents.

    ***

    **Set up an orchestrator:**

    ```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
    Create an orchestrator agent that coordinates "youth-agent" and "formal-agent" for tone-matched responses
    ```

    The assistant uses `create_agent` with the `team_of_agents` array and `retrieve_agents` / `call_sub_agent` tools.
  </Tab>
</Tabs>

## Traces

<Tabs>
  <Tab title="AI Studio" icon="https://mintcdn.com/orqai/My16MDKJXrKALEHC/images/logos/ai-studio-round.svg?fit=max&auto=format&n=My16MDKJXrKALEHC&q=85&s=ac04dd509320d58ab9701cb6d6137733" width="100" height="100" data-path="images/logos/ai-studio-round.svg">
    The **Traces** tab in the agent page shows execution logs filtered to the agent automatically.

    <Frame caption="Agent-specific traces with automatic filtering.">
      <img src="https://mintcdn.com/orqai/hGdKybmgjhwDfaBt/images/agent-traces-tab.png?fit=max&auto=format&n=hGdKybmgjhwDfaBt&q=85&s=273887082ceb068e11ea26c07e7240af" alt="Traces tab for the bank_creditcard_agent showing a list of invoke-agent runs with timestamps, duration, and cost, filtered to this agent." width="3362" height="1970" data-path="images/agent-traces-tab.png" />
    </Frame>

    **Trace data includes:**

    * Execution history with timestamps
    * Input and output for each call
    * Token usage and cost per execution
    * Execution duration and performance metrics
    * Errors and debugging information
    * Tool calls executed (function, HTTP, code, or MCP calls)
    * Knowledge retrieval results and RAG context
    * Memory store interactions
  </Tab>

  <Tab title="API & SDK" icon="code">
    All agent executions are automatically traced. Access traces in the **AI Studio** or via the [Traces API](/docs/observability/traces).

    For programmatic trace access, see the [Observability documentation](/docs/observability/traces).
  </Tab>

  <Tab title="MCP" icon="https://mintcdn.com/orqai/i7ZhKI7LFRfXU7ox/images/logos/mcp.svg?fit=max&auto=format&n=i7ZhKI7LFRfXU7ox&q=85&s=cef7916eb5fe1f6bb97541398d3f7639" width="16" height="16" data-path="images/logos/mcp.svg">
    **List recent traces for an agent:**

    ```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
    Show me the last 20 traces for "support-bot" sorted by most recent
    ```

    The assistant uses `list_traces` with a filter on the agent key.

    ***

    **Inspect a specific trace:**

    ```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
    Show me the full span details for trace ID 01K6D8QESESZ6SAXQPJPFQXPFT
    ```

    The assistant uses `list_spans` to retrieve the full execution tree for that trace.

    ***

    **Debug errors:**

    ```prompt wrap theme={"theme":{"light":"github-light","dark":"github-dark"}}
    Find all failed traces for "support-bot" from the last 24 hours and summarize the errors
    ```

    The assistant uses `list_traces` filtered by `status:=ERROR` and time range, then `get_span` on relevant spans to surface root causes.
  </Tab>
</Tabs>

### Trace Views

Each trace can be inspected in three views:

<Tabs>
  <Tab title="Trace" icon="diagram-project">
    The **Trace** view shows the full execution tree for a single agent run. Each step is displayed hierarchically, including LLM calls, tool invocations, knowledge retrievals, and memory interactions.

    <Frame>
      <img src="https://mintcdn.com/orqai/o4CxH4xK7MCteqsT/images/agent-traces.png?fit=max&auto=format&n=o4CxH4xK7MCteqsT&q=85&s=c9ff9068c81f135879cd15a1654cb027" alt="Trace view showing the single-product-agent span tree with nested invoke-agent, gpt-4o chat-completion, and current_date spans, with properties panel on the right." width="1506" height="925" data-path="images/agent-traces.png" />
    </Frame>
  </Tab>

  <Tab title="Thread" icon="messages">
    The **Thread** view presents the execution as a conversation thread, showing the sequence of messages exchanged between the user, the agent, and any tools.

    <Frame>
      <img src="https://mintcdn.com/orqai/hYJ46ZNib1CGRiid/images/agent-traces-thread.png?fit=max&auto=format&n=hYJ46ZNib1CGRiid&q=85&s=6b2904b134eee8a2a6a4f37751e5be41" alt="Thread view showing the conversation turn with user message, tool executions (current_date called multiple times), and assistant responses." width="1161" height="1176" data-path="images/agent-traces-thread.png" />
    </Frame>
  </Tab>

  <Tab title="Timeline" icon="chart-gantt">
    The **Timeline** view shows execution steps plotted against time, making it easy to identify bottlenecks and understand parallel vs sequential operations.

    <Frame>
      <img src="https://mintcdn.com/orqai/hYJ46ZNib1CGRiid/images/agent-traces-timeline.png?fit=max&auto=format&n=hYJ46ZNib1CGRiid&q=85&s=727f7c4a29aa23a55b81126c612c384d" alt="Timeline view showing agent spans as horizontal bars across a 10-second axis, with invoke-agent, chat-completion, and current_date calls visualized sequentially." width="1165" height="1176" data-path="images/agent-traces-timeline.png" />
    </Frame>
  </Tab>
</Tabs>

### Creating Custom Views

Save frequently used filter combinations as reusable views:

1. Set the desired filters.
2. Click **All Rows** (top right).
3. Select **Create New View**.
4. Give the view a title.
5. Optionally check **Set view private** (default is shared with project members).

<Tip>
  For advanced filtering and cross-agent analysis, see [Traces](/docs/observability/traces).
</Tip>