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

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

## Agents

### Create an Agent

Creates a new agent with the specified configuration, including model selection, instructions, tools, and knowledge bases. Agents are intelligent assistants that can execute tasks, interact with tools, and maintain context through memory stores. The agent can be configured with a primary model and optional fallback models for automatic failover, custom instructions for behavior control, and various settings to control execution limits and tool 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.create(key="<key>", role="<value>", description="alongside beneath doubtfully behest validity bah after furthermore", instructions="<value>", path="Default", model={
          "id": "<id>",
          "retry": {
              "count": 3,
              "on_codes": [
                  429,
                  500,
                  502,
                  503,
                  504,
              ],
          },
      }, settings={
          "tools": [
              {
                  "type": "mcp",
                  "id": "01KA84ND5J0SWQMA2Q8HY5WZZZ",
                  "tool_id": "01KXYZ123456789",
                  "requires_approval": False,
              },
          ],
      }, fallback_models=[
          {
              "id": "<id>",
              "retry": {
                  "count": 3,
                  "on_codes": [
                      429,
                      500,
                      502,
                      503,
                      504,
                  ],
              },
          },
      ], knowledge_bases=[
          {
              "knowledge_id": "customer-knowledge-base",
          },
      ], engine="text")

      # 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.create({
      key: "<key>",
      role: "<value>",
      description: "alongside beneath doubtfully behest validity bah after furthermore",
      instructions: "<value>",
      path: "Default",
      model: {
        id: "<id>",
        retry: {
          count: 3,
          onCodes: [
            429,
            500,
            502,
            503,
            504,
          ],
        },
      },
      fallbackModels: [
        {
          id: "<id>",
          parameters: {
            fallbacks: [
              {
                model: "openai/gpt-4o-mini",
              },
            ],
            cache: {
              ttl: 3600,
              type: "exact_match",
            },
            loadBalancer: {
              type: "weight_based",
              models: [
                {
                  model: "openai/gpt-4o",
                  weight: 0.7,
                },
              ],
            },
            timeout: {
              callTimeout: 30000,
            },
          },
          retry: {
            count: 3,
            onCodes: [
              429,
              500,
              502,
              503,
              504,
            ],
          },
        },
      ],
      settings: {
        tools: [
          {
            type: "mcp",
            id: "01KA84ND5J0SWQMA2Q8HY5WZZZ",
            toolId: "01KXYZ123456789",
            requiresApproval: false,
          },
        ],
      },
      knowledgeBases: [
        {
          knowledgeId: "customer-knowledge-base",
        },
      ],
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "key": str,  # required
        "role": str,  # required
        "description": str,  # required
        "instructions": str,  # required
        "path": str,  # required
        "model": Union[str, ModelConfiguration2],  # required
        "settings": {  # required
            "max_iterations": Optional[int],
            "max_execution_time": Optional[int],
            "max_cost": Optional[float],
            "tool_approval_required": Optional[Literal["all", "respect_tool", "none"]],
            "tools": Union[GoogleSearchTool, WebScraperTool, CallSubAgentTool, RetrieveAgentsTool, QueryMemoryStoreTool, WriteMemoryStoreTool, RetrieveMemoryStoresTool, DeleteMemoryDocumentTool, RetrieveKnowledgeBasesTool, QueryKnowledgeBaseTool, CurrentDateTool, HTTPTool, CodeExecutionTool, FunctionTool, JSONSchemaTool, MCPTool, ProviderBuiltInTool],
            "evaluators": {  # optional
                "id": str,  # required
                "sample_rate": Optional[float],
                "execute_on": Literal["input", "output"],  # required
            },
            "guardrails": {  # optional
                "id": str,  # required
                "sample_rate": Optional[float],
                "execute_on": Literal["input", "output"],  # required
            },
        },
        "display_name": Optional[str],
        "system_prompt": OptionalNullable[str],
        "fallback_models": Union[str, FallbackModelConfiguration2],
        "memory_stores": List[str],
        "knowledge_bases": {  # optional
            "knowledge_id": str,  # required
        },
        "team_of_agents": {  # optional
            "key": str,  # required
            "role": Optional[str],
        },
        "skills": List[str],
        "variables": Dict[str, Any],
        "source": Optional[Literal["internal", "external", "experiment"]],
        "engine": Optional[Literal["text", "jinja", "mustache"]],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      key: string;  // required
      displayName?: string;
      role: string;  // required
      description: string;  // required
      instructions: string;  // required
      systemPrompt?: string;
      path: string;  // required
      model: string;  // required
      fallbackModels?: string;
      settings: {  // required
        maxIterations?: number;
        maxExecutionTime?: number;
        maxCost?: number;
        toolApprovalRequired?: string;
        tools?: string;
        evaluators?: {
          id: string;  // required
          sampleRate?: number;
          executeOn: string;  // required
        };
        guardrails?: {
          id: string;  // required
          sampleRate?: number;
          executeOn: string;  // required
        };
      };
      memoryStores?: string[];
      knowledgeBases?: {
        knowledgeId: string;  // required
      };
      teamOfAgents?: {
        key: string;  // required
        role?: string;
      };
      skills?: string[];
      variables?: Record<string, any>;
      source?: string;
      engine?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "key": str,
        "display_name": Optional[str],
        "project_id": str,
        "created_by_id": OptionalNullable[str],
        "updated_by_id": OptionalNullable[str],
        "created": Optional[str],
        "updated": Optional[str],
        "status": Literal["live", "draft", "pending", "published"],
        "version": Optional[str],
        "path": str,
        "memory_stores": List[str],
        "team_of_agents": {  # optional
            "key": str,
            "role": Optional[str],
        },
        "skills": List[str],
        "metrics": {  # optional
            "total_cost": Optional[float],
        },
        "variables": Dict[str, Any],
        "knowledge_bases": {  # optional
            "knowledge_id": str,
        },
        "source": Optional[Literal["internal", "external", "experiment"]],
        "engine": Optional[Literal["text", "jinja", "mustache"]],
        "type": Optional[Literal["internal", "a2a"]],
        "role": str,
        "description": str,
        "system_prompt": OptionalNullable[str],
        "instructions": str,
        "settings": {  # optional
            "max_iterations": Optional[int],
            "max_execution_time": Optional[int],
            "max_cost": Optional[float],
            "tool_approval_required": Optional[Literal["all", "respect_tool", "none"]],
            "tools": {  # optional
                "id": str,
                "key": Optional[str],
                "action_type": str,
                "display_name": Optional[str],
                "description": Optional[str],
                "requires_approval": Optional[bool],
                "tool_id": Optional[str],
                "conditions": {  # optional
                    "condition": str,
                    "operator": str,
                    "value": str,
                },
                "timeout": Optional[float],
            },
            "evaluators": {  # optional
                "id": str,
                "sample_rate": Optional[float],
                "execute_on": Literal["input", "output"],
            },
            "guardrails": {  # optional
                "id": str,
                "sample_rate": Optional[float],
                "execute_on": Literal["input", "output"],
            },
        },
        "model": {
            "id": str,
            "integration_id": OptionalNullable[str],
            "parameters": {  # optional
                "name": Optional[str],
                "frequency_penalty": OptionalNullable[float],
                "max_tokens": OptionalNullable[int],
                "max_completion_tokens": OptionalNullable[int],
                "presence_penalty": OptionalNullable[float],
                "response_format": Union[CreateAgentRequestResponseFormatText, CreateAgentRequestResponseFormatJSONObject, CreateAgentRequestResponseFormatAgentsResponse201JSONSchema],
                "reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh"]],
                "verbosity": Optional[str],
                "seed": OptionalNullable[float],
                "stop": Union[str, List[str]],
                "thinking": Union[ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema],
                "temperature": OptionalNullable[float],
                "top_p": OptionalNullable[float],
                "top_k": OptionalNullable[float],
                "tool_choice": Union[CreateAgentRequestToolChoiceAgents1, CreateAgentRequestToolChoiceAgents2],
                "parallel_tool_calls": Optional[bool],
                "modalities": List[Literal["text", "audio"]],
                "guardrails": {  # optional
                    "id": Union[CreateAgentRequestIDAgents1, str],
                    "execute_on": Literal["input", "output"],
                },
                "plugins": Union[PIIRedactionPluginAuto, PIIRedactionPluginEn, PIIRedactionPluginNl],
                "fallbacks": {  # optional
                    "model": str,
                },
                "cache": {  # optional
                    "ttl": Optional[float],
                    "type": Literal["exact_match"],
                },
                "load_balancer": Union[CreateAgentRequestLoadBalancerAgents1],
                "timeout": {  # optional
                    "call_timeout": float,
                },
                "cache_control": {  # optional
                    "type": Literal["ephemeral"],
                    "ttl": Optional[Literal["5m", "1h"]],
                },
                "prompt_cache_key": Optional[str],
            },
            "retry": {  # optional
                "count": Optional[float],
                "on_codes": List[float],
            },
            "fallback_models": Union[str, CreateAgentRequestFallbackModelConfiguration2],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      key: string;
      displayName?: string;
      projectId: string;
      createdById?: string;
      updatedById?: string;
      created?: string;
      updated?: string;
      status: string;
      version?: string;
      path: string;
      memoryStores?: string[];
      teamOfAgents?: {
        key: string;
        role?: string;
      };
      skills: string[];
      metrics?: {
        totalCost?: number;
      };
      variables?: Record<string, any>;
      knowledgeBases?: {
        knowledgeId: string;
      };
      source?: string;
      engine?: string;
      type?: string;
      role: string;
      description: string;
      systemPrompt?: string;
      instructions: string;
      settings?: {
        maxIterations?: number;
        maxExecutionTime?: number;
        maxCost?: number;
        toolApprovalRequired?: string;
        tools?: {
          id: string;
          key?: string;
          actionType: string;
          displayName?: string;
          description?: string;
          requiresApproval?: boolean;
          toolId?: string;
          conditions?: {
            condition: string;
            operator: string;
            value: string;
          };
          timeout?: number;
        };
        evaluators?: {
          id: string;
          sampleRate?: number;
          executeOn: string;
        };
        guardrails?: {
          id: string;
          sampleRate?: number;
          executeOn: string;
        };
      };
      model: {
        id: string;
        integrationId?: string;
        parameters?: {
          name?: string;
          frequencyPenalty?: number;
          maxTokens?: number;
          maxCompletionTokens?: number;
          presencePenalty?: number;
          responseFormat?: string;
          reasoningEffort?: string;
          verbosity?: string;
          seed?: number;
          stop?: string | string[];
          thinking?: string;
          temperature?: number;
          topP?: number;
          topK?: number;
          toolChoice?: string;
          parallelToolCalls?: boolean;
          modalities?: string;
          guardrails?: {
            id: string;
            executeOn: string;
          };
          plugins?: string;
          fallbacks?: {
            model: string;
          };
          cache?: {
            ttl?: number;
            type: string;
          };
          loadBalancer?: string;
          timeout?: {
            callTimeout: number;
          };
          cacheControl?: {
            type: string;
            ttl?: string;
          };
          promptCacheKey?: string;
        };
        retry?: {
          count?: number;
          onCodes?: number[];
        };
        fallbackModels?: string;
      };
    }
    ```
  </CodeGroup>
</Expandable>

### List Agents

Retrieves a comprehensive list of agents configured in your workspace. Supports pagination for large datasets and returns agents sorted by creation date (newest first). Each agent in the response includes its complete configuration: model settings with fallback options, instructions, tools, knowledge bases, memory stores, and execution parameters. Use pagination parameters to efficiently navigate through large collections of agents.

<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.list(limit=10)

      # 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.list(10);

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "limit": Optional[float],
        "starting_after": Optional[str],
        "ending_before": Optional[str],
        "type": Optional[Literal["internal"]],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      limit?: number;
      startingAfter?: string;
      endingBefore?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": Literal["list"],
        "data": {
            "id": str,
            "key": str,
            "display_name": Optional[str],
            "created_by_id": OptionalNullable[str],
            "updated_by_id": OptionalNullable[str],
            "created": Optional[str],
            "updated": Optional[str],
            "status": Literal["live", "draft", "pending", "published"],
            "version": Optional[str],
            "path": str,
            "memory_stores": List[str],
            "team_of_agents": {  # optional
                "key": str,
                "role": Optional[str],
            },
            "skills": List[str],
            "metrics": {  # optional
                "total_cost": Optional[float],
            },
            "variables": Dict[str, Any],
            "knowledge_bases": {  # optional
                "knowledge_id": str,
            },
            "source": Optional[Literal["internal", "external", "experiment"]],
            "engine": Optional[Literal["text", "jinja", "mustache"]],
            "type": Optional[Literal["internal", "a2a"]],
            "role": str,
            "description": str,
            "system_prompt": OptionalNullable[str],
            "instructions": str,
            "settings": {  # optional
                "max_iterations": Optional[int],
                "max_execution_time": Optional[int],
                "max_cost": Optional[float],
                "tool_approval_required": Optional[Literal["all", "respect_tool", "none"]],
                "tools": {  # optional
                    "id": str,
                    "key": Optional[str],
                    "action_type": str,
                    "display_name": Optional[str],
                    "description": Optional[str],
                    "requires_approval": Optional[bool],
                    "tool_id": Optional[str],
                    "conditions": {  # optional
                        "condition": str,
                        "operator": str,
                        "value": str,
                    },
                    "timeout": Optional[float],
                },
                "evaluators": {  # optional
                    "id": str,
                    "sample_rate": Optional[float],
                    "execute_on": Literal["input", "output"],
                },
                "guardrails": {  # optional
                    "id": str,
                    "sample_rate": Optional[float],
                    "execute_on": Literal["input", "output"],
                },
            },
            "model": {
                "id": str,
                "integration_id": OptionalNullable[str],
                "parameters": {  # optional
                    "name": Optional[str],
                    "frequency_penalty": OptionalNullable[float],
                    "max_tokens": OptionalNullable[int],
                    "max_completion_tokens": OptionalNullable[int],
                    "presence_penalty": OptionalNullable[float],
                    "response_format": Union[ListAgentsResponseFormatText, ListAgentsResponseFormatJSONObject, ListAgentsResponseFormatAgentsJSONSchema],
                    "reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh"]],
                    "verbosity": Optional[str],
                    "seed": OptionalNullable[float],
                    "stop": Union[str, List[str]],
                    "thinking": Union[ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema],
                    "temperature": OptionalNullable[float],
                    "top_p": OptionalNullable[float],
                    "top_k": OptionalNullable[float],
                    "tool_choice": Union[ListAgentsToolChoice1, ListAgentsToolChoice2],
                    "parallel_tool_calls": Optional[bool],
                    "modalities": List[Literal["text", "audio"]],
                    "guardrails": {  # optional
                        "id": Union[ListAgentsID1, str],
                        "execute_on": Literal["input", "output"],
                    },
                    "plugins": Union[PIIRedactionPluginAuto, PIIRedactionPluginEn, PIIRedactionPluginNl],
                    "fallbacks": {  # optional
                        "model": str,
                    },
                    "cache": {  # optional
                        "ttl": Optional[float],
                        "type": Literal["exact_match"],
                    },
                    "load_balancer": Union[ListAgentsLoadBalancer1],
                    "timeout": {  # optional
                        "call_timeout": float,
                    },
                    "cache_control": {  # optional
                        "type": Literal["ephemeral"],
                        "ttl": Optional[Literal["5m", "1h"]],
                    },
                    "prompt_cache_key": Optional[str],
                },
                "retry": {  # optional
                    "count": Optional[float],
                    "on_codes": List[float],
                },
                "fallback_models": Union[str, ListAgentsFallbackModelConfiguration2],
            },
        },
        "has_more": bool,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object: string;
      data: {
        id: string;
        key: string;
        displayName?: string;
        createdById?: string;
        updatedById?: string;
        created?: string;
        updated?: string;
        status: string;
        version?: string;
        path: string;
        memoryStores?: string[];
        teamOfAgents?: {
          key: string;
          role?: string;
        };
        skills: string[];
        metrics?: {
          totalCost?: number;
        };
        variables?: Record<string, any>;
        knowledgeBases?: {
          knowledgeId: string;
        };
        source?: string;
        engine?: string;
        type?: string;
        role: string;
        description: string;
        systemPrompt?: string;
        instructions: string;
        settings?: {
          maxIterations?: number;
          maxExecutionTime?: number;
          maxCost?: number;
          toolApprovalRequired?: string;
          tools?: {
            id: string;
            key?: string;
            actionType: string;
            displayName?: string;
            description?: string;
            requiresApproval?: boolean;
            toolId?: string;
            conditions?: {
              condition: string;
              operator: string;
              value: string;
            };
            timeout?: number;
          };
          evaluators?: {
            id: string;
            sampleRate?: number;
            executeOn: string;
          };
          guardrails?: {
            id: string;
            sampleRate?: number;
            executeOn: string;
          };
        };
        model: {
          id: string;
          integrationId?: string;
          parameters?: {
            name?: string;
            frequencyPenalty?: number;
            maxTokens?: number;
            maxCompletionTokens?: number;
            presencePenalty?: number;
            responseFormat?: string;
            reasoningEffort?: string;
            verbosity?: string;
            seed?: number;
            stop?: string | string[];
            thinking?: string;
            temperature?: number;
            topP?: number;
            topK?: number;
            toolChoice?: string;
            parallelToolCalls?: boolean;
            modalities?: string;
            guardrails?: {
              id: string;
              executeOn: string;
            };
            plugins?: string;
            fallbacks?: {
              model: string;
            };
            cache?: {
              ttl?: number;
              type: string;
            };
            loadBalancer?: string;
            timeout?: {
              callTimeout: number;
            };
            cacheControl?: {
              type: string;
              ttl?: string;
            };
            promptCacheKey?: string;
          };
          retry?: {
            count?: number;
            onCodes?: number[];
          };
          fallbackModels?: string;
        };
      };
      hasMore: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

### Delete an Agent

Permanently removes an agent from the workspace. This operation is irreversible and will delete all associated configuration including model assignments, tools, knowledge bases, memory stores, and cached data. Active agent sessions will be terminated, and the agent key will become available for reuse.

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

      orq.agents.delete(agent_key="<value>")

      # Use the SDK ...

  ```

  ```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() {
    await orq.agents.delete("<value>");

  }

  run();
  ```
</CodeGroup>

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

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

### Retrieve an Agent

Retrieves detailed information about a specific agent identified by its unique key or identifier. Returns the complete agent manifest including configuration settings, model assignments (primary and fallback), tools, knowledge bases, memory stores, instructions, and execution parameters. Use this endpoint to fetch the current state and configuration of an individual agent.

<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.retrieve(agent_key="<value>")

      # 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.retrieve("<value>");

    console.log(result);
  }

  run();
  ```
</CodeGroup>

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

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

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "key": str,
        "display_name": Optional[str],
        "project_id": str,
        "created_by_id": OptionalNullable[str],
        "updated_by_id": OptionalNullable[str],
        "created": Optional[str],
        "updated": Optional[str],
        "status": Literal["live", "draft", "pending", "published"],
        "version": Optional[str],
        "path": str,
        "memory_stores": List[str],
        "team_of_agents": {  # optional
            "key": str,
            "role": Optional[str],
        },
        "skills": List[str],
        "metrics": {  # optional
            "total_cost": Optional[float],
        },
        "variables": Dict[str, Any],
        "knowledge_bases": {  # optional
            "knowledge_id": str,
        },
        "source": Optional[Literal["internal", "external", "experiment"]],
        "engine": Optional[Literal["text", "jinja", "mustache"]],
        "type": Optional[Literal["internal", "a2a"]],
        "role": str,
        "description": str,
        "system_prompt": OptionalNullable[str],
        "instructions": str,
        "settings": {  # optional
            "max_iterations": Optional[int],
            "max_execution_time": Optional[int],
            "max_cost": Optional[float],
            "tool_approval_required": Optional[Literal["all", "respect_tool", "none"]],
            "tools": {  # optional
                "id": str,
                "key": Optional[str],
                "action_type": str,
                "display_name": Optional[str],
                "description": Optional[str],
                "requires_approval": Optional[bool],
                "tool_id": Optional[str],
                "conditions": {  # optional
                    "condition": str,
                    "operator": str,
                    "value": str,
                },
                "timeout": Optional[float],
            },
            "evaluators": {  # optional
                "id": str,
                "sample_rate": Optional[float],
                "execute_on": Literal["input", "output"],
            },
            "guardrails": {  # optional
                "id": str,
                "sample_rate": Optional[float],
                "execute_on": Literal["input", "output"],
            },
        },
        "model": {
            "id": str,
            "integration_id": OptionalNullable[str],
            "parameters": {  # optional
                "name": Optional[str],
                "frequency_penalty": OptionalNullable[float],
                "max_tokens": OptionalNullable[int],
                "max_completion_tokens": OptionalNullable[int],
                "presence_penalty": OptionalNullable[float],
                "response_format": Union[RetrieveAgentRequestResponseFormatText, RetrieveAgentRequestResponseFormatJSONObject, RetrieveAgentRequestResponseFormatAgentsJSONSchema],
                "reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh"]],
                "verbosity": Optional[str],
                "seed": OptionalNullable[float],
                "stop": Union[str, List[str]],
                "thinking": Union[ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema],
                "temperature": OptionalNullable[float],
                "top_p": OptionalNullable[float],
                "top_k": OptionalNullable[float],
                "tool_choice": Union[RetrieveAgentRequestToolChoice1, RetrieveAgentRequestToolChoice2],
                "parallel_tool_calls": Optional[bool],
                "modalities": List[Literal["text", "audio"]],
                "guardrails": {  # optional
                    "id": Union[RetrieveAgentRequestID1, str],
                    "execute_on": Literal["input", "output"],
                },
                "plugins": Union[PIIRedactionPluginAuto, PIIRedactionPluginEn, PIIRedactionPluginNl],
                "fallbacks": {  # optional
                    "model": str,
                },
                "cache": {  # optional
                    "ttl": Optional[float],
                    "type": Literal["exact_match"],
                },
                "load_balancer": Union[RetrieveAgentRequestLoadBalancer1],
                "timeout": {  # optional
                    "call_timeout": float,
                },
                "cache_control": {  # optional
                    "type": Literal["ephemeral"],
                    "ttl": Optional[Literal["5m", "1h"]],
                },
                "prompt_cache_key": Optional[str],
            },
            "retry": {  # optional
                "count": Optional[float],
                "on_codes": List[float],
            },
            "fallback_models": Union[str, RetrieveAgentRequestFallbackModelConfiguration2],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      key: string;
      displayName?: string;
      projectId: string;
      createdById?: string;
      updatedById?: string;
      created?: string;
      updated?: string;
      status: string;
      version?: string;
      path: string;
      memoryStores?: string[];
      teamOfAgents?: {
        key: string;
        role?: string;
      };
      skills: string[];
      metrics?: {
        totalCost?: number;
      };
      variables?: Record<string, any>;
      knowledgeBases?: {
        knowledgeId: string;
      };
      source?: string;
      engine?: string;
      type?: string;
      role: string;
      description: string;
      systemPrompt?: string;
      instructions: string;
      settings?: {
        maxIterations?: number;
        maxExecutionTime?: number;
        maxCost?: number;
        toolApprovalRequired?: string;
        tools?: {
          id: string;
          key?: string;
          actionType: string;
          displayName?: string;
          description?: string;
          requiresApproval?: boolean;
          toolId?: string;
          conditions?: {
            condition: string;
            operator: string;
            value: string;
          };
          timeout?: number;
        };
        evaluators?: {
          id: string;
          sampleRate?: number;
          executeOn: string;
        };
        guardrails?: {
          id: string;
          sampleRate?: number;
          executeOn: string;
        };
      };
      model: {
        id: string;
        integrationId?: string;
        parameters?: {
          name?: string;
          frequencyPenalty?: number;
          maxTokens?: number;
          maxCompletionTokens?: number;
          presencePenalty?: number;
          responseFormat?: string;
          reasoningEffort?: string;
          verbosity?: string;
          seed?: number;
          stop?: string | string[];
          thinking?: string;
          temperature?: number;
          topP?: number;
          topK?: number;
          toolChoice?: string;
          parallelToolCalls?: boolean;
          modalities?: string;
          guardrails?: {
            id: string;
            executeOn: string;
          };
          plugins?: string;
          fallbacks?: {
            model: string;
          };
          cache?: {
            ttl?: number;
            type: string;
          };
          loadBalancer?: string;
          timeout?: {
            callTimeout: number;
          };
          cacheControl?: {
            type: string;
            ttl?: string;
          };
          promptCacheKey?: string;
        };
        retry?: {
          count?: number;
          onCodes?: number[];
        };
        fallbackModels?: string;
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Update an Agent

Modifies an existing agent's configuration with partial updates. Supports updating any aspect of the agent including model assignments (primary and fallback), instructions, tools, knowledge bases, memory stores, and execution parameters. Only the fields provided in the request body will be updated; all other fields remain unchanged. Changes take effect immediately for new agent invocations.

<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.update(agent_key="<value>", model="El Camino", fallback_models=[
          "<value>",
      ], settings={
          "tools": [
              {
                  "type": "mcp",
                  "id": "01KA84ND5J0SWQMA2Q8HY5WZZZ",
                  "tool_id": "01KXYZ123456789",
                  "requires_approval": False,
              },
          ],
      }, path="Default", knowledge_bases=[
          {
              "knowledge_id": "customer-knowledge-base",
          },
      ])

      # 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.update({
      model: "El Camino",
      fallbackModels: [
        "<value>",
      ],
      settings: {
        tools: [
          {
            type: "mcp",
            id: "01KA84ND5J0SWQMA2Q8HY5WZZZ",
            toolId: "01KXYZ123456789",
            requiresApproval: false,
          },
        ],
      },
      path: "Default",
      knowledgeBases: [
        {
          knowledgeId: "customer-knowledge-base",
        },
      ],
    }, "<value>");

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "agent_key": str,  # required
        "key": Optional[str],
        "display_name": Optional[str],
        "project_id": Optional[str],
        "role": Optional[str],
        "description": Optional[str],
        "instructions": Optional[str],
        "system_prompt": OptionalNullable[str],
        "model": Union[str, UpdateAgentModelConfiguration2],
        "fallback_models": Union[str, UpdateAgentFallbackModelConfiguration2],
        "settings": {  # optional
            "max_iterations": Optional[int],
            "max_execution_time": Optional[int],
            "max_cost": Optional[float],
            "tool_approval_required": Optional[Literal["all", "respect_tool", "none"]],
            "tools": Union[AgentToolInputCRUDGoogleSearchTool, AgentToolInputCRUDWebScraperTool, AgentToolInputCRUDCallSubAgentTool, AgentToolInputCRUDRetrieveAgentsTool, AgentToolInputCRUDQueryMemoryStoreTool, AgentToolInputCRUDWriteMemoryStoreTool, AgentToolInputCRUDRetrieveMemoryStoresTool, AgentToolInputCRUDDeleteMemoryDocumentTool, AgentToolInputCRUDRetrieveKnowledgeBasesTool, AgentToolInputCRUDQueryKnowledgeBaseTool, AgentToolInputCRUDCurrentDateTool, AgentToolInputCRUDHTTPTool, AgentToolInputCRUDCodeExecutionTool, AgentToolInputCRUDFunctionTool, AgentToolInputCRUDJSONSchemaTool, AgentToolInputCRUDMCPTool, AgentToolInputCRUDProviderBuiltInTool],
            "evaluators": {  # optional
                "id": str,  # required
                "sample_rate": Optional[float],
                "execute_on": Literal["input", "output"],  # required
            },
            "guardrails": {  # optional
                "id": str,  # required
                "sample_rate": Optional[float],
                "execute_on": Literal["input", "output"],  # required
            },
        },
        "path": Optional[str],
        "memory_stores": List[str],
        "knowledge_bases": {  # optional
            "knowledge_id": str,  # required
        },
        "team_of_agents": {  # optional
            "key": str,  # required
            "role": Optional[str],
        },
        "skills": List[str],
        "variables": Dict[str, Any],
        "engine": Optional[Literal["text", "jinja", "mustache"]],
        "version_increment": Optional[Literal["major", "minor", "patch"]],
        "version_description": Optional[str],
    }
    ```

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

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "key": str,
        "display_name": Optional[str],
        "project_id": str,
        "created_by_id": OptionalNullable[str],
        "updated_by_id": OptionalNullable[str],
        "created": Optional[str],
        "updated": Optional[str],
        "status": Literal["live", "draft", "pending", "published"],
        "version": Optional[str],
        "path": str,
        "memory_stores": List[str],
        "team_of_agents": {  # optional
            "key": str,
            "role": Optional[str],
        },
        "skills": List[str],
        "metrics": {  # optional
            "total_cost": Optional[float],
        },
        "variables": Dict[str, Any],
        "knowledge_bases": {  # optional
            "knowledge_id": str,
        },
        "source": Optional[Literal["internal", "external", "experiment"]],
        "engine": Optional[Literal["text", "jinja", "mustache"]],
        "type": Optional[Literal["internal", "a2a"]],
        "role": str,
        "description": str,
        "system_prompt": OptionalNullable[str],
        "instructions": str,
        "settings": {  # optional
            "max_iterations": Optional[int],
            "max_execution_time": Optional[int],
            "max_cost": Optional[float],
            "tool_approval_required": Optional[Literal["all", "respect_tool", "none"]],
            "tools": {  # optional
                "id": str,
                "key": Optional[str],
                "action_type": str,
                "display_name": Optional[str],
                "description": Optional[str],
                "requires_approval": Optional[bool],
                "tool_id": Optional[str],
                "conditions": {  # optional
                    "condition": str,
                    "operator": str,
                    "value": str,
                },
                "timeout": Optional[float],
            },
            "evaluators": {  # optional
                "id": str,
                "sample_rate": Optional[float],
                "execute_on": Literal["input", "output"],
            },
            "guardrails": {  # optional
                "id": str,
                "sample_rate": Optional[float],
                "execute_on": Literal["input", "output"],
            },
        },
        "model": {
            "id": str,
            "integration_id": OptionalNullable[str],
            "parameters": {  # optional
                "name": Optional[str],
                "frequency_penalty": OptionalNullable[float],
                "max_tokens": OptionalNullable[int],
                "max_completion_tokens": OptionalNullable[int],
                "presence_penalty": OptionalNullable[float],
                "response_format": Union[UpdateAgentResponseFormatAgentsResponseText, UpdateAgentResponseFormatAgentsResponseJSONObject, UpdateAgentResponseFormatAgentsResponse200JSONSchema],
                "reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh"]],
                "verbosity": Optional[str],
                "seed": OptionalNullable[float],
                "stop": Union[str, List[str]],
                "thinking": Union[ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema],
                "temperature": OptionalNullable[float],
                "top_p": OptionalNullable[float],
                "top_k": OptionalNullable[float],
                "tool_choice": Union[UpdateAgentToolChoiceAgentsResponse1, UpdateAgentToolChoiceAgentsResponse2],
                "parallel_tool_calls": Optional[bool],
                "modalities": List[Literal["text", "audio"]],
                "guardrails": {  # optional
                    "id": Union[UpdateAgentIDAgentsResponse1, str],
                    "execute_on": Literal["input", "output"],
                },
                "plugins": Union[PIIRedactionPluginAuto, PIIRedactionPluginEn, PIIRedactionPluginNl],
                "fallbacks": {  # optional
                    "model": str,
                },
                "cache": {  # optional
                    "ttl": Optional[float],
                    "type": Literal["exact_match"],
                },
                "load_balancer": Union[UpdateAgentLoadBalancerAgentsResponse1],
                "timeout": {  # optional
                    "call_timeout": float,
                },
                "cache_control": {  # optional
                    "type": Literal["ephemeral"],
                    "ttl": Optional[Literal["5m", "1h"]],
                },
                "prompt_cache_key": Optional[str],
            },
            "retry": {  # optional
                "count": Optional[float],
                "on_codes": List[float],
            },
            "fallback_models": Union[str, UpdateAgentFallbackModelConfigurationAgents2],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      key: string;
      displayName?: string;
      projectId: string;
      createdById?: string;
      updatedById?: string;
      created?: string;
      updated?: string;
      status: string;
      version?: string;
      path: string;
      memoryStores?: string[];
      teamOfAgents?: {
        key: string;
        role?: string;
      };
      skills: string[];
      metrics?: {
        totalCost?: number;
      };
      variables?: Record<string, any>;
      knowledgeBases?: {
        knowledgeId: string;
      };
      source?: string;
      engine?: string;
      type?: string;
      role: string;
      description: string;
      systemPrompt?: string;
      instructions: string;
      settings?: {
        maxIterations?: number;
        maxExecutionTime?: number;
        maxCost?: number;
        toolApprovalRequired?: string;
        tools?: {
          id: string;
          key?: string;
          actionType: string;
          displayName?: string;
          description?: string;
          requiresApproval?: boolean;
          toolId?: string;
          conditions?: {
            condition: string;
            operator: string;
            value: string;
          };
          timeout?: number;
        };
        evaluators?: {
          id: string;
          sampleRate?: number;
          executeOn: string;
        };
        guardrails?: {
          id: string;
          sampleRate?: number;
          executeOn: string;
        };
      };
      model: {
        id: string;
        integrationId?: string;
        parameters?: {
          name?: string;
          frequencyPenalty?: number;
          maxTokens?: number;
          maxCompletionTokens?: number;
          presencePenalty?: number;
          responseFormat?: string;
          reasoningEffort?: string;
          verbosity?: string;
          seed?: number;
          stop?: string | string[];
          thinking?: string;
          temperature?: number;
          topP?: number;
          topK?: number;
          toolChoice?: string;
          parallelToolCalls?: boolean;
          modalities?: string;
          guardrails?: {
            id: string;
            executeOn: string;
          };
          plugins?: string;
          fallbacks?: {
            model: string;
          };
          cache?: {
            ttl?: number;
            type: string;
          };
          loadBalancer?: string;
          timeout?: {
            callTimeout: number;
          };
          cacheControl?: {
            type: string;
            ttl?: string;
          };
          promptCacheKey?: string;
        };
        retry?: {
          count?: number;
          onCodes?: number[];
        };
        fallbackModels?: string;
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Invoke an Agent <Badge color="yellow" size="lg" stroke>\[deprecated]</Badge>

Invokes an agent to perform a task with the provided input message. The agent will process the request using its configured model and tools, maintaining context through memory stores if configured. Supports automatic model fallback on primary model failure, tool execution, knowledge base retrieval, and continuation of previous conversations. Returns a task response that can be used to track execution status and retrieve results.

<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.invoke(key="<key>", message={
          "role": "user",
          "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",
          ],
      })

      # 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.invoke("<key>", {
      message: {
        role: "user",
        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"}}
    {
        "key": str,  # required
        "message": {  # required
            "message_id": Optional[str],
            "role": Union[InvokeAgentRoleUserMessage, InvokeAgentRoleToolMessage],  # 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],
        },
    }
    ```

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

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "context_id": str,
        "kind": Literal["task"],
        "status": {
            "state": Literal["submitted", "working", "input-required", "auth-required", "completed", "failed", "canceled", "rejected"],
            "timestamp": Optional[str],
            "message": {  # optional
                "kind": Literal["message"],
                "message_id": str,
                "role": Literal["user", "agent", "tool", "system"],
                "parts": Union[TextPart, ErrorPart, DataPart, FilePart, ToolCallPart, ToolResultPart],
            },
        },
        "messages": {  # optional
            "kind": Literal["message"],
            "message_id": str,
            "role": Literal["user", "agent", "tool", "system"],
            "parts": Union[TextPart, ErrorPart, DataPart, FilePart, ToolCallPart, ToolResultPart],
            "task_id": Optional[str],
            "context_id": Optional[str],
            "metadata": Dict[str, Any],
        },
        "metadata": Dict[str, Any],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      contextId: string;
      kind: string;
      status: {
        state: string;
        timestamp?: string;
        message?: {
          kind: string;
          messageId: string;
          role: string;
          parts: string;
        };
      };
      messages?: {
        kind: string;
        messageId: string;
        role: string;
        parts: string;
        taskId?: string;
        contextId?: string;
        metadata?: Record<string, any>;
      };
      metadata?: Record<string, any>;
    }
    ```
  </CodeGroup>
</Expandable>

### Run an Agent <Badge color="yellow" size="lg" stroke>\[deprecated]</Badge>

Executes an agent using inline configuration or references an existing agent. Supports dynamic agent creation where the system automatically manages agent versioning - reusing existing agents with matching configurations or creating new versions when configurations differ. Ideal for programmatic agent execution with flexible configuration management. The agent processes messages in A2A format with support for memory context, tool execution, and automatic model fallback on failure.

<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.run(key="<key>", model="F-150", role="<value>", instructions="<value>", message={
          "role": "tool",
          "parts": [
              {
                  "kind": "text",
                  "text": "<value>",
              },
          ],
      }, path="Default", settings={}, fallback_models=[
          "<value>",
      ], 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",
          ],
      }, knowledge_bases=[
          {
              "knowledge_id": "customer-knowledge-base",
          },
      ], engine="text")

      # 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.run({
      key: "<key>",
      model: "F-150",
      fallbackModels: [
        "<value>",
      ],
      role: "<value>",
      instructions: "<value>",
      message: {
        role: "tool",
        parts: [
          {
            kind: "text",
            text: "<value>",
          },
        ],
      },
      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",
        ],
      },
      path: "Default",
      knowledgeBases: [
        {
          knowledgeId: "customer-knowledge-base",
        },
      ],
      settings: {},
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "key": str,  # required
        "model": Union[str, RunAgentModelConfiguration2],  # required
        "role": str,  # required
        "instructions": str,  # required
        "message": {  # required
            "message_id": Optional[str],
            "role": Union[RunAgentRoleUserMessage, RunAgentRoleToolMessage],  # required
            "parts": Union[TextPart, FilePart, ToolResultPart, ErrorPart],  # required
        },
        "path": str,  # required
        "settings": {  # required
            "tools": Union[AgentToolInputRunGoogleSearchTool, AgentToolInputRunWebScraperTool, AgentToolInputRunCallSubAgentTool, AgentToolInputRunRetrieveAgentsTool, AgentToolInputRunQueryMemoryStoreTool, AgentToolInputRunWriteMemoryStoreTool, AgentToolInputRunRetrieveMemoryStoresTool, AgentToolInputRunDeleteMemoryDocumentTool, AgentToolInputRunRetrieveKnowledgeBasesTool, AgentToolInputRunQueryKnowledgeBaseTool, AgentToolInputRunCurrentDateTool, HTTPToolRun, CodeToolRun, FunctionToolRun, JSONSchemaToolRun, MCPToolRun],
            "tool_approval_required": Optional[Literal["all", "respect_tool", "none"]],
            "max_iterations": Optional[int],
            "max_execution_time": Optional[int],
            "max_cost": Optional[float],
            "evaluators": {  # optional
                "id": str,  # required
                "sample_rate": Optional[float],
                "execute_on": Literal["input", "output"],  # required
            },
            "guardrails": {  # optional
                "id": str,  # required
                "sample_rate": Optional[float],
                "execute_on": Literal["input", "output"],  # required
            },
        },
        "task_id": Optional[str],
        "fallback_models": Union[str, RunAgentFallbackModelConfiguration2],
        "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
        },
        "description": Optional[str],
        "system_prompt": OptionalNullable[str],
        "memory_stores": List[str],
        "knowledge_bases": {  # optional
            "knowledge_id": str,  # required
        },
        "team_of_agents": {  # optional
            "key": str,  # required
            "role": Optional[str],
        },
        "metadata": Dict[str, Any],
        "engine": Optional[Literal["text", "jinja", "mustache"]],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      key: string;  // required
      taskId?: string;
      model: string;  // required
      fallbackModels?: string;
      role: string;  // required
      instructions: string;  // required
      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
      };
      path: string;  // required
      description?: string;
      systemPrompt?: string;
      memoryStores?: string[];
      knowledgeBases?: {
        knowledgeId: string;  // required
      };
      teamOfAgents?: {
        key: string;  // required
        role?: string;
      };
      settings: {  // required
        tools?: string;
        toolApprovalRequired?: string;
        maxIterations?: number;
        maxExecutionTime?: number;
        maxCost?: number;
        evaluators?: {
          id: string;  // required
          sampleRate?: number;
          executeOn: string;  // required
        };
        guardrails?: {
          id: string;  // required
          sampleRate?: number;
          executeOn: string;  // required
        };
      };
      metadata?: Record<string, any>;
      engine?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "context_id": str,
        "kind": Literal["task"],
        "status": {
            "state": Literal["submitted", "working", "input-required", "auth-required", "completed", "failed", "canceled", "rejected"],
            "timestamp": Optional[str],
            "message": {  # optional
                "kind": Literal["message"],
                "message_id": str,
                "role": Literal["user", "agent", "tool", "system"],
                "parts": Union[TextPart, ErrorPart, DataPart, FilePart, ToolCallPart, ToolResultPart],
            },
        },
        "messages": {  # optional
            "kind": Literal["message"],
            "message_id": str,
            "role": Literal["user", "agent", "tool", "system"],
            "parts": Union[TextPart, ErrorPart, DataPart, FilePart, ToolCallPart, ToolResultPart],
            "task_id": Optional[str],
            "context_id": Optional[str],
            "metadata": Dict[str, Any],
        },
        "metadata": Dict[str, Any],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      contextId: string;
      kind: string;
      status: {
        state: string;
        timestamp?: string;
        message?: {
          kind: string;
          messageId: string;
          role: string;
          parts: string;
        };
      };
      messages?: {
        kind: string;
        messageId: string;
        role: string;
        parts: string;
        taskId?: string;
        contextId?: string;
        metadata?: Record<string, any>;
      };
      metadata?: Record<string, any>;
    }
    ```
  </CodeGroup>
</Expandable>

### Stream Run <Badge color="yellow" size="lg" stroke>\[deprecated]</Badge>

Dynamically configures and executes an agent while streaming the interaction in real-time via Server-Sent Events (SSE). Intelligently manages agent versioning by reusing existing agents with matching configurations or creating new versions when configurations differ. Combines the flexibility of inline configuration with real-time streaming, making it ideal for dynamic agent interactions with live feedback. The stream provides continuous updates including message chunks, tool executions, and status changes until completion or timeout.

<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.stream_run(key="<key>", model="Alpine", role="<value>", instructions="<value>", message={
          "role": "user",
          "parts": [
              {
                  "kind": "file",
                  "file": {
                      "uri": "https://jumbo-zebra.info/",
                  },
              },
          ],
      }, path="Default", settings={}, fallback_models=[
          "<value>",
      ], 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",
          ],
      }, knowledge_bases=[
          {
              "knowledge_id": "customer-knowledge-base",
          },
      ], engine="text")

      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.streamRun({
      key: "<key>",
      model: "Alpine",
      fallbackModels: [
        "<value>",
      ],
      role: "<value>",
      instructions: "<value>",
      message: {
        role: "user",
        parts: [
          {
            kind: "file",
            file: {
              uri: "https://jumbo-zebra.info/",
            },
          },
        ],
      },
      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",
        ],
      },
      path: "Default",
      knowledgeBases: [
        {
          knowledgeId: "customer-knowledge-base",
        },
      ],
      settings: {},
    });

    for await (const event of result) {
      console.log(event);
    }
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "key": str,  # required
        "model": Union[str, StreamRunAgentModelConfiguration2],  # required
        "role": str,  # required
        "instructions": str,  # required
        "message": {  # required
            "message_id": Optional[str],
            "role": Union[StreamRunAgentRoleUserMessage, StreamRunAgentRoleToolMessage],  # required
            "parts": Union[TextPart, FilePart, ToolResultPart, ErrorPart],  # required
        },
        "path": str,  # required
        "settings": {  # required
            "tools": Union[StreamRunAgentAgentToolInputRunGoogleSearchTool, StreamRunAgentAgentToolInputRunWebScraperTool, StreamRunAgentAgentToolInputRunCallSubAgentTool, StreamRunAgentAgentToolInputRunRetrieveAgentsTool, StreamRunAgentAgentToolInputRunQueryMemoryStoreTool, StreamRunAgentAgentToolInputRunWriteMemoryStoreTool, StreamRunAgentAgentToolInputRunRetrieveMemoryStoresTool, StreamRunAgentAgentToolInputRunDeleteMemoryDocumentTool, StreamRunAgentAgentToolInputRunRetrieveKnowledgeBasesTool, StreamRunAgentAgentToolInputRunQueryKnowledgeBaseTool, StreamRunAgentAgentToolInputRunCurrentDateTool, AgentToolInputRunHTTPToolRun, AgentToolInputRunCodeToolRun, AgentToolInputRunFunctionToolRun, AgentToolInputRunJSONSchemaToolRun, AgentToolInputRunMCPToolRun],
            "tool_approval_required": Optional[Literal["all", "respect_tool", "none"]],
            "max_iterations": Optional[int],
            "max_execution_time": Optional[int],
            "max_cost": Optional[float],
            "evaluators": {  # optional
                "id": str,  # required
                "sample_rate": Optional[float],
                "execute_on": Literal["input", "output"],  # required
            },
            "guardrails": {  # optional
                "id": str,  # required
                "sample_rate": Optional[float],
                "execute_on": Literal["input", "output"],  # required
            },
        },
        "task_id": Optional[str],
        "fallback_models": Union[str, StreamRunAgentFallbackModelConfiguration2],
        "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
        },
        "description": Optional[str],
        "system_prompt": OptionalNullable[str],
        "memory_stores": List[str],
        "knowledge_bases": {  # optional
            "knowledge_id": str,  # required
        },
        "team_of_agents": {  # optional
            "key": str,  # required
            "role": Optional[str],
        },
        "metadata": Dict[str, Any],
        "engine": Optional[Literal["text", "jinja", "mustache"]],
        "stream_timeout_seconds": Optional[float],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      key: string;  // required
      taskId?: string;
      model: string;  // required
      fallbackModels?: string;
      role: string;  // required
      instructions: string;  // required
      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
      };
      path: string;  // required
      description?: string;
      systemPrompt?: string;
      memoryStores?: string[];
      knowledgeBases?: {
        knowledgeId: string;  // required
      };
      teamOfAgents?: {
        key: string;  // required
        role?: string;
      };
      settings: {  // required
        tools?: string;
        toolApprovalRequired?: string;
        maxIterations?: number;
        maxExecutionTime?: number;
        maxCost?: number;
        evaluators?: {
          id: string;  // required
          sampleRate?: number;
          executeOn: string;  // required
        };
        guardrails?: {
          id: string;  // required
          sampleRate?: number;
          executeOn: string;  // required
        };
      };
      metadata?: Record<string, any>;
      engine?: string;
      streamTimeoutSeconds?: number;
    }
    ```
  </CodeGroup>
</Expandable>

### Stream an Agent <Badge color="yellow" size="lg" stroke>\[deprecated]</Badge>

Executes an agent and streams the interaction in real-time using Server-Sent Events (SSE). Provides live updates as the agent processes the request, including message chunks, tool calls, and execution status. Perfect for building responsive chat interfaces and monitoring agent progress. The stream continues until the agent completes its task, encounters an error, or reaches the configured timeout (default 30 minutes, configurable 1-3600 seconds).

<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.stream(key="<key>", message={
          "role": "user",
          "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",
          ],
      })

      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.stream({
      message: {
        role: "user",
        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",
        ],
      },
    }, "<key>");

    for await (const event of result) {
      console.log(event);
    }
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "key": str,  # required
        "message": {  # required
            "message_id": Optional[str],
            "role": Union[StreamAgentRoleUserMessage, StreamAgentRoleToolMessage],  # 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],
        },
        "stream_timeout_seconds": Optional[float],
    }
    ```

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

### Refresh Agent Card

Fetches the latest agent card from the external A2A agent and updates the cached card in the database. Similar to MCP server refresh functionality.

<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.refresh_key_card(key="<key>")

      # 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.refreshKeyCard({
      key: "<key>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

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

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

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "message": str,
        "card": Optional[Any],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      message: string;
      card?: any;
    }
    ```
  </CodeGroup>
</Expandable>