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

# Legacy invoke and run SDK Reference

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

## Agents

### Invoke an Agent \[deprecated]

Invoke an agent to perform a task with input messages. Supports tool execution, knowledge retrieval, memory context, and model fallback.

```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": [{"kind": "text", "text": "What is the weather in Paris?"}],
    }, 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: [{ kind: "text", text: "What is the weather in Paris?" }],
    },
    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();
```

**Parameters**

```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": List[Union[TextPart, FilePart, ToolResultPart, ErrorPart]],  # required
    },
    "task_id": Optional[str],
    "variables": Dict[str, Any],  # optional
    "identity": {  # optional
        "id": str,  # required
        "display_name": Optional[str],
        "email": Optional[str],
        "metadata": List[Dict[str, Any]],  # optional
        "logo_url": Optional[str],
        "tags": List[str],  # optional
    },
    "contact": {  # optional
        "id": str,  # required
        "display_name": Optional[str],
        "email": Optional[str],
        "metadata": List[Dict[str, Any]],  # optional
        "logo_url": Optional[str],
        "tags": List[str],  # optional
    },
    "thread": {  # optional
        "id": str,  # required
        "tags": List[str],  # optional
    },
    "memory": {  # optional
        "entity_id": str,  # required
    },
    "metadata": Dict[str, Any],  # optional
    "engine": Optional[Literal["text", "jinja", "mustache"]],
    "configuration": {  # optional
        "blocking": Optional[bool],
    },
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  taskId?: string;
  message: {  // required
    messageId?: string;
    role: RoleUserMessage | RoleToolMessage;  // required
    parts: (TextPart | FilePart | ToolResultPart | ErrorPart)[];  // required
  };
  variables?: Record<string, any>;
  identity?: {
    id: string;  // required
    displayName?: string;
    email?: string;
    metadata?: Record<string, any>[];
    logoUrl?: string;
    tags?: string[];
  };
  contact?: {
    id: string;  // required
    displayName?: string;
    email?: string;
    metadata?: Record<string, any>[];
    logoUrl?: string;
    tags?: string[];
  };
  thread?: {
    id: string;  // required
    tags?: string[];
  };
  memory?: {
    entityId: string;  // required
  };
  metadata?: Record<string, any>;
  engine?: "text" | "jinja" | "mustache";
  configuration?: {
    blocking?: boolean;
  };
  // key is passed as an argument beyond the request object
}
```

**Response**

```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": List[Union[TextPart, ErrorPart, DataPart, FilePart, ToolCallPart, ToolResultPart]],
        },
    },
    "messages": [{  # optional
        "kind": Literal["message"],
        "message_id": str,
        "role": Literal["user", "agent", "tool", "system"],
        "parts": List[Union[TextPart, ErrorPart, DataPart, FilePart, ToolCallPart, ToolResultPart]],
        "task_id": Optional[str],
        "context_id": Optional[str],
        "metadata": Dict[str, Any],  # optional
    }],
    "metadata": Dict[str, Any],  # optional
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  id: string;
  contextId: string;
  kind: "task";
  status: {
    state: "submitted" | "working" | "input-required" | "auth-required" | "completed" | "failed" | "canceled" | "rejected";
    timestamp?: string;
    message?: {
      kind: "message";
      messageId: string;
      role: "user" | "agent" | "tool" | "system";
      parts: (TextPart | ErrorPart | DataPart | FilePart | ToolCallPart | ToolResultPart)[];
    };
  };
  messages?: {
    kind: "message";
    messageId: string;
    role: "user" | "agent" | "tool" | "system";
    parts: (TextPart | ErrorPart | DataPart | FilePart | ToolCallPart | ToolResultPart)[];
    taskId?: string;
    contextId?: string;
    metadata?: Record<string, any>;
  }[];
  metadata?: Record<string, any>;
}
```

### Run an Agent \[deprecated]

Run an agent with inline configuration or existing agent reference. Supports A2A messages, memory context, tool execution, and model fallback.

```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="openai/gpt-6-astra", role="<value>", instructions="<value>", message={
        "role": "user",
        "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: "openai/gpt-6-astra",
    fallbackModels: [
      "<value>",
    ],
    role: "<value>",
    instructions: "<value>",
    message: {
      role: "user",
      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();
```

**Parameters**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "key": str,  # required
    "model": {  # required
        # one of: RunAgentModelConfiguration2, str
        "id": str,  # required
        "parameters": {  # optional
            "name": Optional[str],
            "frequency_penalty": Optional[float],
            "max_tokens": Optional[int],
            "max_completion_tokens": Optional[int],
            "presence_penalty": Optional[float],
            "response_format": {  # optional
                # one of: RunAgentResponseFormatText, RunAgentResponseFormatJSONObject, RunAgentResponseFormatJSONSchema
                "type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]],  # required
                "json_schema": {  # required (variant-specific)
                    "description": Optional[str],
                    "name": str,  # required
                    "schema_": Optional[Any],
                    "strict": Optional[bool],
                },
            },
            "reasoning_effort": Optional[Literal["none", "instant", "minimal", "low", "medium", "high", "xhigh", "max"]],
            "verbosity": Optional[str],
            "seed": Optional[float],
            "stop": Union[str, List[str]],  # optional
            "thinking": {  # optional
                # one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema, ThinkingConfigBetweenToolsSchema
                "type": Union[Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]], Literal["between_tools"]],  # required
                "budget_tokens": Union[float, Optional[float]],  # required (variant-specific)
                "thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
                "display": Optional[Literal["summarized", "omitted", "updates"]],
            },
            "temperature": Optional[float],
            "top_p": Optional[float],
            "top_k": Optional[float],
            "tool_choice": {  # optional
                # one of: RunAgentToolChoice1, RunAgentToolChoice2
                "type": Optional[Literal["function"]],
                "function": {  # required (variant-specific)
                    "name": str,  # required
                },
            },
            "parallel_tool_calls": Optional[bool],
            "modalities": List[Literal["text", "audio"]],  # optional
            "guardrails": [{  # optional
                "id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str],  # required
                "execute_on": Literal["input", "output"],  # required
            }],
            "plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]],  # optional
            "fallback_on_codes": List[int],  # optional
            "fallbacks": [{  # optional
                "model": str,  # required
            }],
            "cache": {  # optional
                "ttl": Optional[float],
                "type": Literal["exact_match"],  # required
            },
            "load_balancer": {  # optional
                # one of: RunAgentLoadBalancer1
                "type": Literal["weight_based"],  # required
                "models": [{  # required
                    "model": str,  # required
                    "weight": Optional[float],
                }],
            },
            "timeout": {  # optional
                "call_timeout": float,  # required
            },
            "cache_control": {  # optional
                "type": Literal["ephemeral"],  # required
                "ttl": Optional[Literal["5m", "1h"]],
            },
            "prompt_cache_key": Optional[str],
        },
        "retry": {  # optional
            "count": Optional[float],
            "on_codes": List[float],  # optional
        },
    },
    "role": str,  # required
    "instructions": str,  # required
    "message": {  # required
        "message_id": Optional[str],
        "role": Union[RunAgentRoleUserMessage, RunAgentRoleToolMessage],  # required
        "parts": List[Union[TextPart, FilePart, ToolResultPart, ErrorPart]],  # required
    },
    "path": str,  # required
    "settings": {  # required
        "tools": List[Union[GoogleSearchToolInput, WebScraperToolInput, CallSubAgentToolInput, RetrieveAgentsToolInput, QueryMemoryStoreToolInput, WriteMemoryStoreToolInput, RetrieveMemoryStoresToolInput, DeleteMemoryDocumentToolInput, RetrieveKnowledgeBasesToolInput, QueryKnowledgeBaseToolInput, CurrentDateToolInput, AdvisorToolInput, SidekickToolInput, CodeInterpreterToolInput, FileSystemToolInput, HTTPToolRun, CodeToolRun, FunctionToolRun, JSONSchemaToolRun, MCPToolRun]],  # optional
        "tool_approval_required": Optional[Literal["all", "respect_tool", "none"]],
        "max_iterations": Optional[int],
        "max_execution_time": Optional[int],
        "max_cost": Optional[float],
        "chat_exposed": Optional[bool],
        "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": List[Union[str, RunAgentFallbackModelConfiguration2]],  # optional
    "variables": Dict[str, Any],  # optional
    "identity": {  # optional
        "id": str,  # required
        "display_name": Optional[str],
        "email": Optional[str],
        "metadata": List[Dict[str, Any]],  # optional
        "logo_url": Optional[str],
        "tags": List[str],  # optional
    },
    "contact": {  # optional
        "id": str,  # required
        "display_name": Optional[str],
        "email": Optional[str],
        "metadata": List[Dict[str, Any]],  # optional
        "logo_url": Optional[str],
        "tags": List[str],  # optional
    },
    "thread": {  # optional
        "id": str,  # required
        "tags": List[str],  # optional
    },
    "memory": {  # optional
        "entity_id": str,  # required
    },
    "description": Optional[str],
    "system_prompt": Optional[str],
    "memory_stores": List[str],  # optional
    "knowledge_bases": [{  # optional
        "knowledge_id": str,  # required
    }],
    "team_of_agents": [{  # optional
        "key": str,  # required
        "role": Optional[str],
    }],
    "metadata": Dict[str, Any],  # optional
    "engine": Optional[Literal["text", "jinja", "mustache"]],
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  key: string;  // required
  taskId?: string;
  model: {  // required
    // one of: RunAgentModelConfiguration2, string
    id: string;  // required
    parameters?: {
      name?: string;
      frequencyPenalty?: number;
      maxTokens?: number;
      maxCompletionTokens?: number;
      presencePenalty?: number;
      responseFormat?: {
        // one of: RunAgentResponseFormatText, RunAgentResponseFormatJSONObject, RunAgentResponseFormatJSONSchema
        type: "text" | "json_object" | "json_schema";  // required
        jsonSchema: {  // required (variant-specific)
          description?: string;
          name: string;  // required
          schema?: any;
          strict?: boolean;
        };
      };
      reasoningEffort?: "none" | "instant" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
      verbosity?: string;
      seed?: number;
      stop?: string | string[];
      thinking?: {
        // one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema, ThinkingConfigBetweenToolsSchema
        type: "disabled" | "enabled" | "adaptive" | "between_tools";  // required
        budgetTokens: number;  // required (variant-specific)
        thinkingLevel?: "minimal" | "low" | "medium" | "high";
        display?: "summarized" | "omitted" | "updates";
      };
      temperature?: number;
      topP?: number;
      topK?: number;
      toolChoice?: {
        // one of: RunAgentToolChoice1, RunAgentToolChoice2
        type?: "function";
        function: {  // required (variant-specific)
          name: string;  // required
        };
      };
      parallelToolCalls?: boolean;
      modalities?: ("text" | "audio")[];
      guardrails?: {
        id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string;  // required
        executeOn: "input" | "output";  // required
      }[];
      plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
      fallbackOnCodes?: number[];
      fallbacks?: {
        model: string;  // required
      }[];
      cache?: {
        ttl?: number;
        type: "exact_match";  // required
      };
      loadBalancer?: {
        // one of: RunAgentLoadBalancer1
        type: "weight_based";  // required
        models: {  // required
          model: string;  // required
          weight?: number;
        }[];
      };
      timeout?: {
        callTimeout: number;  // required
      };
      cacheControl?: {
        type: "ephemeral";  // required
        ttl?: "5m" | "1h";
      };
      promptCacheKey?: string;
    };
    retry?: {
      count?: number;
      onCodes?: number[];
    };
  };
  fallbackModels?: (string | RunAgentFallbackModelConfiguration2)[];
  role: string;  // required
  instructions: string;  // required
  message: {  // required
    messageId?: string;
    role: RunAgentRoleUserMessage | RunAgentRoleToolMessage;  // required
    parts: (TextPart | FilePart | ToolResultPart | ErrorPart)[];  // required
  };
  variables?: Record<string, any>;
  identity?: {
    id: string;  // required
    displayName?: string;
    email?: string;
    metadata?: Record<string, any>[];
    logoUrl?: string;
    tags?: string[];
  };
  contact?: {
    id: string;  // required
    displayName?: string;
    email?: string;
    metadata?: Record<string, any>[];
    logoUrl?: string;
    tags?: string[];
  };
  thread?: {
    id: string;  // required
    tags?: string[];
  };
  memory?: {
    entityId: string;  // required
  };
  path: string;  // required
  description?: string;
  systemPrompt?: string;
  memoryStores?: string[];
  knowledgeBases?: {
    knowledgeId: string;  // required
  }[];
  teamOfAgents?: {
    key: string;  // required
    role?: string;
  }[];
  settings: {  // required
    tools?: (GoogleSearchToolInput | WebScraperToolInput | CallSubAgentToolInput | RetrieveAgentsToolInput | QueryMemoryStoreToolInput | WriteMemoryStoreToolInput | RetrieveMemoryStoresToolInput | DeleteMemoryDocumentToolInput | RetrieveKnowledgeBasesToolInput | QueryKnowledgeBaseToolInput | CurrentDateToolInput | AdvisorToolInput | SidekickToolInput | CodeInterpreterToolInput | FileSystemToolInput | HTTPToolRun | CodeToolRun | FunctionToolRun | JSONSchemaToolRun | MCPToolRun)[];
    toolApprovalRequired?: "all" | "respect_tool" | "none";
    maxIterations?: number;
    maxExecutionTime?: number;
    maxCost?: number;
    chatExposed?: boolean;
    evaluators?: {
      id: string;  // required
      sampleRate?: number;
      executeOn: "input" | "output";  // required
    }[];
    guardrails?: {
      id: string;  // required
      sampleRate?: number;
      executeOn: "input" | "output";  // required
    }[];
  };
  metadata?: Record<string, any>;
  engine?: "text" | "jinja" | "mustache";
}
```

**Response**

```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": List[Union[TextPart, ErrorPart, DataPart, FilePart, ToolCallPart, ToolResultPart]],
        },
    },
    "messages": [{  # optional
        "kind": Literal["message"],
        "message_id": str,
        "role": Literal["user", "agent", "tool", "system"],
        "parts": List[Union[TextPart, ErrorPart, DataPart, FilePart, ToolCallPart, ToolResultPart]],
        "task_id": Optional[str],
        "context_id": Optional[str],
        "metadata": Dict[str, Any],  # optional
    }],
    "metadata": Dict[str, Any],  # optional
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  id: string;
  contextId: string;
  kind: "task";
  status: {
    state: "submitted" | "working" | "input-required" | "auth-required" | "completed" | "failed" | "canceled" | "rejected";
    timestamp?: string;
    message?: {
      kind: "message";
      messageId: string;
      role: "user" | "agent" | "tool" | "system";
      parts: (TextPart | ErrorPart | DataPart | FilePart | ToolCallPart | ToolResultPart)[];
    };
  };
  messages?: {
    kind: "message";
    messageId: string;
    role: "user" | "agent" | "tool" | "system";
    parts: (TextPart | ErrorPart | DataPart | FilePart | ToolCallPart | ToolResultPart)[];
    taskId?: string;
    contextId?: string;
    metadata?: Record<string, any>;
  }[];
  metadata?: Record<string, any>;
}
```

**Variant types**

#### RunAgentFallbackModelConfiguration2

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "id": str,
    "parameters": {  # optional
        "name": Optional[str],
        "frequency_penalty": Optional[float],
        "max_tokens": Optional[int],
        "max_completion_tokens": Optional[int],
        "presence_penalty": Optional[float],
        "response_format": {  # optional
            # one of: RunAgentResponseFormatAgentsText, RunAgentResponseFormatAgentsJSONObject, RunAgentResponseFormatAgentsRequestJSONSchema
            "type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]],
            "json_schema": {
                "description": Optional[str],
                "name": str,
                "schema_": Optional[Any],
                "strict": Optional[bool],
            },
        },
        "reasoning_effort": Optional[Literal["none", "instant", "minimal", "low", "medium", "high", "xhigh", "max"]],
        "verbosity": Optional[str],
        "seed": Optional[float],
        "stop": Union[str, List[str]],  # optional
        "thinking": {  # optional
            # one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema, ThinkingConfigBetweenToolsSchema
            "type": Union[Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]], Literal["between_tools"]],
            "budget_tokens": Union[float, Optional[float]],
            "thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
            "display": Optional[Literal["summarized", "omitted", "updates"]],
        },
        "temperature": Optional[float],
        "top_p": Optional[float],
        "top_k": Optional[float],
        "tool_choice": {  # optional
            # one of: RunAgentToolChoiceAgents1, RunAgentToolChoiceAgents2
            "type": Optional[Literal["function"]],
            "function": {
                "name": str,
            },
        },
        "parallel_tool_calls": Optional[bool],
        "modalities": List[Literal["text", "audio"]],  # optional
        "guardrails": [{  # optional
            "id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str],
            "execute_on": Literal["input", "output"],
        }],
        "plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]],  # optional
        "fallback_on_codes": List[int],  # optional
        "fallbacks": [{  # optional
            "model": str,
        }],
        "cache": {  # optional
            "ttl": Optional[float],
            "type": Literal["exact_match"],
        },
        "load_balancer": {  # optional
            # one of: RunAgentLoadBalancerAgents1
            "type": Literal["weight_based"],
            "models": [{
                "model": str,
                "weight": Optional[float],
            }],
        },
        "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],  # optional
    },
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  id: string;
  parameters?: {
    name?: string;
    frequencyPenalty?: number;
    maxTokens?: number;
    maxCompletionTokens?: number;
    presencePenalty?: number;
    responseFormat?: {
      // one of: RunAgentResponseFormatAgentsText, RunAgentResponseFormatAgentsJSONObject, RunAgentResponseFormatAgentsRequestJSONSchema
      type: "text" | "json_object" | "json_schema";
      jsonSchema: {
        description?: string;
        name: string;
        schema?: any;
        strict?: boolean;
      };
    };
    reasoningEffort?: "none" | "instant" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
    verbosity?: string;
    seed?: number;
    stop?: string | string[];
    thinking?: {
      // one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema, ThinkingConfigBetweenToolsSchema
      type: "disabled" | "enabled" | "adaptive" | "between_tools";
      budgetTokens: number;
      thinkingLevel?: "minimal" | "low" | "medium" | "high";
      display?: "summarized" | "omitted" | "updates";
    };
    temperature?: number;
    topP?: number;
    topK?: number;
    toolChoice?: {
      // one of: RunAgentToolChoiceAgents1, RunAgentToolChoiceAgents2
      type?: "function";
      function: {
        name: string;
      };
    };
    parallelToolCalls?: boolean;
    modalities?: ("text" | "audio")[];
    guardrails?: {
      id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string;
      executeOn: "input" | "output";
    }[];
    plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
    fallbackOnCodes?: number[];
    fallbacks?: {
      model: string;
    }[];
    cache?: {
      ttl?: number;
      type: "exact_match";
    };
    loadBalancer?: {
      // one of: RunAgentLoadBalancerAgents1
      type: "weight_based";
      models: {
        model: string;
        weight?: number;
      }[];
    };
    timeout?: {
      callTimeout: number;
    };
    cacheControl?: {
      type: "ephemeral";
      ttl?: "5m" | "1h";
    };
    promptCacheKey?: string;
  };
  retry?: {
    count?: number;
    onCodes?: number[];
  };
}
```

### Stream Run \[deprecated]

Run an agent with streaming via SSE, combining inline configuration with real-time updates including messages, tool executions, and status.

```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="openai/gpt-6-astra", role="<value>", instructions="<value>", message={
        "role": "user",
        "parts": [
            {
                "kind": "file",
                "file": {
                    "uri": "https://example.com/report.pdf",
                },
            },
        ],
    }, 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: "openai/gpt-6-astra",
    fallbackModels: [
      "<value>",
    ],
    role: "<value>",
    instructions: "<value>",
    message: {
      role: "user",
      parts: [
        {
          kind: "file",
          file: {
            uri: "https://example.com/report.pdf",
          },
        },
      ],
    },
    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();
```

**Parameters**

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "key": str,  # required
    "model": {  # required
        # one of: StreamRunAgentModelConfiguration2, str
        "id": str,  # required
        "parameters": {  # optional
            "name": Optional[str],
            "frequency_penalty": Optional[float],
            "max_tokens": Optional[int],
            "max_completion_tokens": Optional[int],
            "presence_penalty": Optional[float],
            "response_format": {  # optional
                # one of: StreamRunAgentResponseFormatText, StreamRunAgentResponseFormatJSONObject, StreamRunAgentResponseFormatJSONSchema
                "type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]],  # required
                "json_schema": {  # required (variant-specific)
                    "description": Optional[str],
                    "name": str,  # required
                    "schema_": Optional[Any],
                    "strict": Optional[bool],
                },
            },
            "reasoning_effort": Optional[Literal["none", "instant", "minimal", "low", "medium", "high", "xhigh", "max"]],
            "verbosity": Optional[str],
            "seed": Optional[float],
            "stop": Union[str, List[str]],  # optional
            "thinking": {  # optional
                # one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema, ThinkingConfigBetweenToolsSchema
                "type": Union[Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]], Literal["between_tools"]],  # required
                "budget_tokens": Union[float, Optional[float]],  # required (variant-specific)
                "thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
                "display": Optional[Literal["summarized", "omitted", "updates"]],
            },
            "temperature": Optional[float],
            "top_p": Optional[float],
            "top_k": Optional[float],
            "tool_choice": {  # optional
                # one of: StreamRunAgentToolChoice1, StreamRunAgentToolChoice2
                "type": Optional[Literal["function"]],
                "function": {  # required (variant-specific)
                    "name": str,  # required
                },
            },
            "parallel_tool_calls": Optional[bool],
            "modalities": List[Literal["text", "audio"]],  # optional
            "guardrails": [{  # optional
                "id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str],  # required
                "execute_on": Literal["input", "output"],  # required
            }],
            "plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]],  # optional
            "fallback_on_codes": List[int],  # optional
            "fallbacks": [{  # optional
                "model": str,  # required
            }],
            "cache": {  # optional
                "ttl": Optional[float],
                "type": Literal["exact_match"],  # required
            },
            "load_balancer": {  # optional
                # one of: StreamRunAgentLoadBalancer1
                "type": Literal["weight_based"],  # required
                "models": [{  # required
                    "model": str,  # required
                    "weight": Optional[float],
                }],
            },
            "timeout": {  # optional
                "call_timeout": float,  # required
            },
            "cache_control": {  # optional
                "type": Literal["ephemeral"],  # required
                "ttl": Optional[Literal["5m", "1h"]],
            },
            "prompt_cache_key": Optional[str],
        },
        "retry": {  # optional
            "count": Optional[float],
            "on_codes": List[float],  # optional
        },
    },
    "role": str,  # required
    "instructions": str,  # required
    "message": {  # required
        "message_id": Optional[str],
        "role": Union[StreamRunAgentRoleUserMessage, StreamRunAgentRoleToolMessage],  # required
        "parts": List[Union[TextPart, FilePart, ToolResultPart, ErrorPart]],  # required
    },
    "path": str,  # required
    "settings": {  # required
        "tools": List[Union[GoogleSearchToolInput, WebScraperToolInput, CallSubAgentToolInput, RetrieveAgentsToolInput, QueryMemoryStoreToolInput, WriteMemoryStoreToolInput, RetrieveMemoryStoresToolInput, DeleteMemoryDocumentToolInput, RetrieveKnowledgeBasesToolInput, QueryKnowledgeBaseToolInput, CurrentDateToolInput, AdvisorToolInput, SidekickToolInput, CodeInterpreterToolInput, FileSystemToolInput, AgentToolInputRunHTTPToolRun, AgentToolInputRunCodeToolRun, AgentToolInputRunFunctionToolRun, AgentToolInputRunJSONSchemaToolRun, AgentToolInputRunMCPToolRun]],  # optional
        "tool_approval_required": Optional[Literal["all", "respect_tool", "none"]],
        "max_iterations": Optional[int],
        "max_execution_time": Optional[int],
        "max_cost": Optional[float],
        "chat_exposed": Optional[bool],
        "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": List[Union[str, StreamRunAgentFallbackModelConfiguration2]],  # optional
    "variables": Dict[str, Any],  # optional
    "identity": {  # optional
        "id": str,  # required
        "display_name": Optional[str],
        "email": Optional[str],
        "metadata": List[Dict[str, Any]],  # optional
        "logo_url": Optional[str],
        "tags": List[str],  # optional
    },
    "contact": {  # optional
        "id": str,  # required
        "display_name": Optional[str],
        "email": Optional[str],
        "metadata": List[Dict[str, Any]],  # optional
        "logo_url": Optional[str],
        "tags": List[str],  # optional
    },
    "thread": {  # optional
        "id": str,  # required
        "tags": List[str],  # optional
    },
    "memory": {  # optional
        "entity_id": str,  # required
    },
    "description": Optional[str],
    "system_prompt": Optional[str],
    "memory_stores": List[str],  # optional
    "knowledge_bases": [{  # optional
        "knowledge_id": str,  # required
    }],
    "team_of_agents": [{  # optional
        "key": str,  # required
        "role": Optional[str],
    }],
    "metadata": Dict[str, Any],  # optional
    "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: {  // required
    // one of: StreamRunAgentModelConfiguration2, string
    id: string;  // required
    parameters?: {
      name?: string;
      frequencyPenalty?: number;
      maxTokens?: number;
      maxCompletionTokens?: number;
      presencePenalty?: number;
      responseFormat?: {
        // one of: StreamRunAgentResponseFormatText, StreamRunAgentResponseFormatJSONObject, StreamRunAgentResponseFormatJSONSchema
        type: "text" | "json_object" | "json_schema";  // required
        jsonSchema: {  // required (variant-specific)
          description?: string;
          name: string;  // required
          schema?: any;
          strict?: boolean;
        };
      };
      reasoningEffort?: "none" | "instant" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
      verbosity?: string;
      seed?: number;
      stop?: string | string[];
      thinking?: {
        // one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema, ThinkingConfigBetweenToolsSchema
        type: "disabled" | "enabled" | "adaptive" | "between_tools";  // required
        budgetTokens: number;  // required (variant-specific)
        thinkingLevel?: "minimal" | "low" | "medium" | "high";
        display?: "summarized" | "omitted" | "updates";
      };
      temperature?: number;
      topP?: number;
      topK?: number;
      toolChoice?: {
        // one of: StreamRunAgentToolChoice1, StreamRunAgentToolChoice2
        type?: "function";
        function: {  // required (variant-specific)
          name: string;  // required
        };
      };
      parallelToolCalls?: boolean;
      modalities?: ("text" | "audio")[];
      guardrails?: {
        id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string;  // required
        executeOn: "input" | "output";  // required
      }[];
      plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
      fallbackOnCodes?: number[];
      fallbacks?: {
        model: string;  // required
      }[];
      cache?: {
        ttl?: number;
        type: "exact_match";  // required
      };
      loadBalancer?: {
        // one of: StreamRunAgentLoadBalancer1
        type: "weight_based";  // required
        models: {  // required
          model: string;  // required
          weight?: number;
        }[];
      };
      timeout?: {
        callTimeout: number;  // required
      };
      cacheControl?: {
        type: "ephemeral";  // required
        ttl?: "5m" | "1h";
      };
      promptCacheKey?: string;
    };
    retry?: {
      count?: number;
      onCodes?: number[];
    };
  };
  fallbackModels?: (string | StreamRunAgentFallbackModelConfiguration2)[];
  role: string;  // required
  instructions: string;  // required
  message: {  // required
    messageId?: string;
    role: StreamRunAgentRoleUserMessage | StreamRunAgentRoleToolMessage;  // required
    parts: (TextPart | FilePart | ToolResultPart | ErrorPart)[];  // required
  };
  variables?: Record<string, any>;
  identity?: {
    id: string;  // required
    displayName?: string;
    email?: string;
    metadata?: Record<string, any>[];
    logoUrl?: string;
    tags?: string[];
  };
  contact?: {
    id: string;  // required
    displayName?: string;
    email?: string;
    metadata?: Record<string, any>[];
    logoUrl?: string;
    tags?: string[];
  };
  thread?: {
    id: string;  // required
    tags?: string[];
  };
  memory?: {
    entityId: string;  // required
  };
  path: string;  // required
  description?: string;
  systemPrompt?: string;
  memoryStores?: string[];
  knowledgeBases?: {
    knowledgeId: string;  // required
  }[];
  teamOfAgents?: {
    key: string;  // required
    role?: string;
  }[];
  settings: {  // required
    tools?: (GoogleSearchToolInput | WebScraperToolInput | CallSubAgentToolInput | RetrieveAgentsToolInput | QueryMemoryStoreToolInput | WriteMemoryStoreToolInput | RetrieveMemoryStoresToolInput | DeleteMemoryDocumentToolInput | RetrieveKnowledgeBasesToolInput | QueryKnowledgeBaseToolInput | CurrentDateToolInput | AdvisorToolInput | SidekickToolInput | CodeInterpreterToolInput | FileSystemToolInput | AgentToolInputRunHTTPToolRun | AgentToolInputRunCodeToolRun | AgentToolInputRunFunctionToolRun | AgentToolInputRunJSONSchemaToolRun | AgentToolInputRunMCPToolRun)[];
    toolApprovalRequired?: "all" | "respect_tool" | "none";
    maxIterations?: number;
    maxExecutionTime?: number;
    maxCost?: number;
    chatExposed?: boolean;
    evaluators?: {
      id: string;  // required
      sampleRate?: number;
      executeOn: "input" | "output";  // required
    }[];
    guardrails?: {
      id: string;  // required
      sampleRate?: number;
      executeOn: "input" | "output";  // required
    }[];
  };
  metadata?: Record<string, any>;
  engine?: "text" | "jinja" | "mustache";
  streamTimeoutSeconds?: number;
}
```

**Variant types**

#### StreamRunAgentFallbackModelConfiguration2

```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
    "id": str,
    "parameters": {  # optional
        "name": Optional[str],
        "frequency_penalty": Optional[float],
        "max_tokens": Optional[int],
        "max_completion_tokens": Optional[int],
        "presence_penalty": Optional[float],
        "response_format": {  # optional
            # one of: StreamRunAgentResponseFormatAgentsText, StreamRunAgentResponseFormatAgentsJSONObject, StreamRunAgentResponseFormatAgentsRequestJSONSchema
            "type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]],
            "json_schema": {
                "description": Optional[str],
                "name": str,
                "schema_": Optional[Any],
                "strict": Optional[bool],
            },
        },
        "reasoning_effort": Optional[Literal["none", "instant", "minimal", "low", "medium", "high", "xhigh", "max"]],
        "verbosity": Optional[str],
        "seed": Optional[float],
        "stop": Union[str, List[str]],  # optional
        "thinking": {  # optional
            # one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema, ThinkingConfigBetweenToolsSchema
            "type": Union[Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]], Literal["between_tools"]],
            "budget_tokens": Union[float, Optional[float]],
            "thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
            "display": Optional[Literal["summarized", "omitted", "updates"]],
        },
        "temperature": Optional[float],
        "top_p": Optional[float],
        "top_k": Optional[float],
        "tool_choice": {  # optional
            # one of: StreamRunAgentToolChoiceAgents1, StreamRunAgentToolChoiceAgents2
            "type": Optional[Literal["function"]],
            "function": {
                "name": str,
            },
        },
        "parallel_tool_calls": Optional[bool],
        "modalities": List[Literal["text", "audio"]],  # optional
        "guardrails": [{  # optional
            "id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str],
            "execute_on": Literal["input", "output"],
        }],
        "plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]],  # optional
        "fallback_on_codes": List[int],  # optional
        "fallbacks": [{  # optional
            "model": str,
        }],
        "cache": {  # optional
            "ttl": Optional[float],
            "type": Literal["exact_match"],
        },
        "load_balancer": {  # optional
            # one of: StreamRunAgentLoadBalancerAgents1
            "type": Literal["weight_based"],
            "models": [{
                "model": str,
                "weight": Optional[float],
            }],
        },
        "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],  # optional
    },
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  id: string;
  parameters?: {
    name?: string;
    frequencyPenalty?: number;
    maxTokens?: number;
    maxCompletionTokens?: number;
    presencePenalty?: number;
    responseFormat?: {
      // one of: StreamRunAgentResponseFormatAgentsText, StreamRunAgentResponseFormatAgentsJSONObject, StreamRunAgentResponseFormatAgentsRequestJSONSchema
      type: "text" | "json_object" | "json_schema";
      jsonSchema: {
        description?: string;
        name: string;
        schema?: any;
        strict?: boolean;
      };
    };
    reasoningEffort?: "none" | "instant" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
    verbosity?: string;
    seed?: number;
    stop?: string | string[];
    thinking?: {
      // one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema, ThinkingConfigBetweenToolsSchema
      type: "disabled" | "enabled" | "adaptive" | "between_tools";
      budgetTokens: number;
      thinkingLevel?: "minimal" | "low" | "medium" | "high";
      display?: "summarized" | "omitted" | "updates";
    };
    temperature?: number;
    topP?: number;
    topK?: number;
    toolChoice?: {
      // one of: StreamRunAgentToolChoiceAgents1, StreamRunAgentToolChoiceAgents2
      type?: "function";
      function: {
        name: string;
      };
    };
    parallelToolCalls?: boolean;
    modalities?: ("text" | "audio")[];
    guardrails?: {
      id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string;
      executeOn: "input" | "output";
    }[];
    plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
    fallbackOnCodes?: number[];
    fallbacks?: {
      model: string;
    }[];
    cache?: {
      ttl?: number;
      type: "exact_match";
    };
    loadBalancer?: {
      // one of: StreamRunAgentLoadBalancerAgents1
      type: "weight_based";
      models: {
        model: string;
        weight?: number;
      }[];
    };
    timeout?: {
      callTimeout: number;
    };
    cacheControl?: {
      type: "ephemeral";
      ttl?: "5m" | "1h";
    };
    promptCacheKey?: string;
  };
  retry?: {
    count?: number;
    onCodes?: number[];
  };
}
```

### Stream an Agent \[deprecated]

Stream an existing agent execution in real-time via SSE, providing live message chunks, tool calls, and status updates until completion.

```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": [{"kind": "text", "text": "What is the weather in Paris?"}],
    }, 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: [{ kind: "text", text: "What is the weather in Paris?" }],
    },
    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();
```

**Parameters**

```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": List[Union[TextPart, FilePart, ToolResultPart, ErrorPart]],  # required
    },
    "task_id": Optional[str],
    "variables": Dict[str, Any],  # optional
    "identity": {  # optional
        "id": str,  # required
        "display_name": Optional[str],
        "email": Optional[str],
        "metadata": List[Dict[str, Any]],  # optional
        "logo_url": Optional[str],
        "tags": List[str],  # optional
    },
    "contact": {  # optional
        "id": str,  # required
        "display_name": Optional[str],
        "email": Optional[str],
        "metadata": List[Dict[str, Any]],  # optional
        "logo_url": Optional[str],
        "tags": List[str],  # optional
    },
    "thread": {  # optional
        "id": str,  # required
        "tags": List[str],  # optional
    },
    "memory": {  # optional
        "entity_id": str,  # required
    },
    "metadata": Dict[str, Any],  # optional
    "engine": Optional[Literal["text", "jinja", "mustache"]],
    "configuration": {  # optional
        "blocking": Optional[bool],
    },
    "stream_timeout_seconds": Optional[float],
}
```

```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  taskId?: string;
  message: {  // required
    messageId?: string;
    role: StreamAgentRoleUserMessage | StreamAgentRoleToolMessage;  // required
    parts: (TextPart | FilePart | ToolResultPart | ErrorPart)[];  // required
  };
  variables?: Record<string, any>;
  identity?: {
    id: string;  // required
    displayName?: string;
    email?: string;
    metadata?: Record<string, any>[];
    logoUrl?: string;
    tags?: string[];
  };
  contact?: {
    id: string;  // required
    displayName?: string;
    email?: string;
    metadata?: Record<string, any>[];
    logoUrl?: string;
    tags?: string[];
  };
  thread?: {
    id: string;  // required
    tags?: string[];
  };
  memory?: {
    entityId: string;  // required
  };
  metadata?: Record<string, any>;
  engine?: "text" | "jinja" | "mustache";
  configuration?: {
    blocking?: boolean;
  };
  streamTimeoutSeconds?: number;
  // key is passed as an argument beyond the request object
}
```


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