> ## 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 > Create, list, update, delete, and invoke Orq.ai agents with the Node.js and Python SDKs, including streaming runs, tools, and fallback models. ## Agents ### Create an Agent Create a new agent with the specified model, instructions, tools, and knowledge bases. Supports fallback models and configurable execution settings. ```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="", role="", description="Customer support triage agent", instructions="", path="Default", model={ "id": "", "retry": { "count": 3, "on_codes": [ 429, 500, 502, 503, 504, ], }, }, settings={ "tools": [ { "type": "mcp", "id": "01KA84ND5J0SWQMA2Q8HY5WZZZ", "tool_id": "01KXYZ123456789", "requires_approval": False, }, ], }, display_name="HR Assistant", fallback_models=[ { "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: "", displayName: "HR Assistant", role: "", description: "Customer support triage agent", instructions: "", path: "Default", model: { id: "", retry: { count: 3, onCodes: [ 429, 500, 502, 503, 504, ], }, }, fallbackModels: [ { id: "", parameters: { fallbacks: [ { model: "openai/gpt-5.6-luna", }, ], cache: { ttl: 3600, type: "exact_match", }, loadBalancer: { type: "weight_based", models: [ { model: "openai/gpt-6-astra", 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(); ``` ```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"]], "chat_exposed": Optional[bool], "tools": List[Union[GoogleSearchToolInput, WebScraperToolInput, CallSubAgentToolInput, RetrieveAgentsToolInput, QueryMemoryStoreToolInput, WriteMemoryStoreToolInput, RetrieveMemoryStoresToolInput, DeleteMemoryDocumentToolInput, RetrieveKnowledgeBasesToolInput, QueryKnowledgeBaseToolInput, CurrentDateToolInput, AdvisorToolInput, SidekickToolInput, CodeInterpreterToolInput, FileSystemToolInput, HTTPToolInput, CodeToolInput, FunctionToolInput, JSONSchemaToolInput, McpToolInput]], # optional "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": Optional[str], "fallback_models": List[Union[str, FallbackModelConfiguration2]], # optional "memory_stores": List[str], # optional "knowledge_bases": [{ # optional "knowledge_id": str, # required }], "team_of_agents": [{ # optional "key": str, # required "role": Optional[str], }], "skills": List[str], # optional "variables": Dict[str, Any], # optional "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 | ModelConfiguration2; // required fallbackModels?: (string | FallbackModelConfiguration2)[]; settings: { // required maxIterations?: number; maxExecutionTime?: number; maxCost?: number; toolApprovalRequired?: "all" | "respect_tool" | "none"; chatExposed?: boolean; tools?: (GoogleSearchToolInput | WebScraperToolInput | CallSubAgentToolInput | RetrieveAgentsToolInput | QueryMemoryStoreToolInput | WriteMemoryStoreToolInput | RetrieveMemoryStoresToolInput | DeleteMemoryDocumentToolInput | RetrieveKnowledgeBasesToolInput | QueryKnowledgeBaseToolInput | CurrentDateToolInput | AdvisorToolInput | SidekickToolInput | CodeInterpreterToolInput | FileSystemToolInput | HttpToolInput | CodeToolInput | FunctionToolInput | JsonSchemaToolInput | McpToolInput)[]; evaluators?: { id: string; // required sampleRate?: number; executeOn: "input" | "output"; // required }[]; guardrails?: { id: string; // required sampleRate?: number; executeOn: "input" | "output"; // required }[]; }; memoryStores?: string[]; knowledgeBases?: { knowledgeId: string; // required }[]; teamOfAgents?: { key: string; // required role?: string; }[]; skills?: string[]; variables?: Record; source?: "internal" | "external" | "experiment"; engine?: "text" | "jinja" | "mustache"; } ``` ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} { "id": str, "key": str, "display_name": Optional[str], "project_id": str, "created_by_id": Optional[str], "updated_by_id": Optional[str], "created": Optional[str], "updated": Optional[str], "status": Literal["live", "draft", "pending", "published"], "version": Optional[str], "path": str, "memory_stores": List[str], # optional "team_of_agents": [{ # optional "key": str, "role": Optional[str], }], "skills": List[str], # optional "metrics": { # optional "total_cost": Optional[float], }, "variables": Dict[str, Any], # optional "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": Optional[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"]], "chat_exposed": Optional[bool], "tools": [{ # optional "id": str, "key": Optional[str], "action_type": str, "display_name": Optional[str], "description": Optional[str], "configuration": Dict[str, Any], # optional "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": Optional[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": Union[CreateAgentRequestResponseFormatText, CreateAgentRequestResponseFormatJSONObject, CreateAgentRequestResponseFormatAgentsResponse201JSONSchema], # optional "reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]], "verbosity": Optional[str], "seed": Optional[float], "stop": Union[str, List[str]], # optional "thinking": Union[ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema], # optional "temperature": Optional[float], "top_p": Optional[float], "top_k": Optional[float], "tool_choice": Union[CreateAgentRequestToolChoiceAgents1, CreateAgentRequestToolChoiceAgents2], # optional "parallel_tool_calls": Optional[bool], "modalities": List[Literal["text", "audio"]], # optional "guardrails": [{ # optional "id": Union[CreateAgentRequestIDAgents1, str], "execute_on": Literal["input", "output"], }], "plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]], # optional "fallbacks": [{ # optional "model": str, }], "cache": { # optional "ttl": Optional[float], "type": Literal["exact_match"], }, "load_balancer": Union[CreateAgentRequestLoadBalancerAgents1], # optional "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 }, "fallback_models": List[Union[str, CreateAgentRequestFallbackModelConfiguration2]], # optional }, } ``` ```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: "live" | "draft" | "pending" | "published"; version?: string; path: string; memoryStores?: string[]; teamOfAgents?: { key: string; role?: string; }[]; skills?: string[]; metrics?: { totalCost?: number; }; variables?: Record; knowledgeBases?: { knowledgeId: string; }[]; source?: "internal" | "external" | "experiment"; engine?: "text" | "jinja" | "mustache"; type?: "internal" | "a2a"; role: string; description: string; systemPrompt?: string; instructions: string; settings?: { maxIterations?: number; maxExecutionTime?: number; maxCost?: number; toolApprovalRequired?: "all" | "respect_tool" | "none"; chatExposed?: boolean; tools?: { id: string; key?: string; actionType: string; displayName?: string; description?: string; configuration?: Record; requiresApproval?: boolean; toolId?: string; conditions?: { condition: string; operator: string; value: string; }[]; timeout?: number; }[]; evaluators?: { id: string; sampleRate?: number; executeOn: "input" | "output"; }[]; guardrails?: { id: string; sampleRate?: number; executeOn: "input" | "output"; }[]; }; model: { id: string; integrationId?: string; parameters?: { name?: string; frequencyPenalty?: number; maxTokens?: number; maxCompletionTokens?: number; presencePenalty?: number; responseFormat?: CreateAgentRequestResponseFormatText | CreateAgentRequestResponseFormatJSONObject | CreateAgentRequestResponseFormatAgentsResponse201JSONSchema; reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"; verbosity?: string; seed?: number; stop?: string | string[]; thinking?: ThinkingConfigDisabledSchema | ThinkingConfigEnabledSchema | ThinkingConfigAdaptiveSchema; temperature?: number; topP?: number; topK?: number; toolChoice?: CreateAgentRequestToolChoiceAgents1 | CreateAgentRequestToolChoiceAgents2; parallelToolCalls?: boolean; modalities?: ("text" | "audio")[]; guardrails?: { id: CreateAgentRequestIdAgents1 | string; executeOn: "input" | "output"; }[]; plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[]; fallbacks?: { model: string; }[]; cache?: { ttl?: number; type: "exact_match"; }; loadBalancer?: CreateAgentRequestLoadBalancerAgents1; timeout?: { callTimeout: number; }; cacheControl?: { type: "ephemeral"; ttl?: "5m" | "1h"; }; promptCacheKey?: string; }; retry?: { count?: number; onCodes?: number[]; }; fallbackModels?: (string | CreateAgentRequestFallbackModelConfiguration2)[]; }; } ``` ### List Agents List all agents in the workspace with full configuration details. Supports pagination and sorts agents newest first. ```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(); ``` ```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; } ``` ```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": Optional[str], "updated_by_id": Optional[str], "created": Optional[str], "updated": Optional[str], "status": Literal["live", "draft", "pending", "published"], "version": Optional[str], "path": str, "memory_stores": List[str], # optional "team_of_agents": [{ # optional "key": str, "role": Optional[str], }], "skills": List[str], # optional "metrics": { # optional "total_cost": Optional[float], }, "variables": Dict[str, Any], # optional "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": Optional[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"]], "chat_exposed": Optional[bool], "tools": [{ # optional "id": str, "key": Optional[str], "action_type": str, "display_name": Optional[str], "description": Optional[str], "configuration": Dict[str, Any], # optional "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": Optional[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": Union[ListAgentsResponseFormatText, ListAgentsResponseFormatJSONObject, ListAgentsResponseFormatAgentsJSONSchema], # optional "reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]], "verbosity": Optional[str], "seed": Optional[float], "stop": Union[str, List[str]], # optional "thinking": Union[ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema], # optional "temperature": Optional[float], "top_p": Optional[float], "top_k": Optional[float], "tool_choice": Union[ListAgentsToolChoice1, ListAgentsToolChoice2], # optional "parallel_tool_calls": Optional[bool], "modalities": List[Literal["text", "audio"]], # optional "guardrails": [{ # optional "id": Union[ListAgentsID1, str], "execute_on": Literal["input", "output"], }], "plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]], # optional "fallbacks": [{ # optional "model": str, }], "cache": { # optional "ttl": Optional[float], "type": Literal["exact_match"], }, "load_balancer": Union[ListAgentsLoadBalancer1], # optional "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 }, "fallback_models": List[Union[str, ListAgentsFallbackModelConfiguration2]], # optional }, }], "has_more": bool, } ``` ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}} { object: "list"; data: { id: string; key: string; displayName?: string; createdById?: string; updatedById?: string; created?: string; updated?: string; status: "live" | "draft" | "pending" | "published"; version?: string; path: string; memoryStores?: string[]; teamOfAgents?: { key: string; role?: string; }[]; skills?: string[]; metrics?: { totalCost?: number; }; variables?: Record; knowledgeBases?: { knowledgeId: string; }[]; source?: "internal" | "external" | "experiment"; engine?: "text" | "jinja" | "mustache"; type?: "internal" | "a2a"; role: string; description: string; systemPrompt?: string; instructions: string; settings?: { maxIterations?: number; maxExecutionTime?: number; maxCost?: number; toolApprovalRequired?: "all" | "respect_tool" | "none"; chatExposed?: boolean; tools?: { id: string; key?: string; actionType: string; displayName?: string; description?: string; configuration?: Record; requiresApproval?: boolean; toolId?: string; conditions?: { condition: string; operator: string; value: string; }[]; timeout?: number; }[]; evaluators?: { id: string; sampleRate?: number; executeOn: "input" | "output"; }[]; guardrails?: { id: string; sampleRate?: number; executeOn: "input" | "output"; }[]; }; model: { id: string; integrationId?: string; parameters?: { name?: string; frequencyPenalty?: number; maxTokens?: number; maxCompletionTokens?: number; presencePenalty?: number; responseFormat?: ListAgentsResponseFormatText | ListAgentsResponseFormatJSONObject | ListAgentsResponseFormatAgentsJSONSchema; reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"; verbosity?: string; seed?: number; stop?: string | string[]; thinking?: ThinkingConfigDisabledSchema | ThinkingConfigEnabledSchema | ThinkingConfigAdaptiveSchema; temperature?: number; topP?: number; topK?: number; toolChoice?: ListAgentsToolChoice1 | ListAgentsToolChoice2; parallelToolCalls?: boolean; modalities?: ("text" | "audio")[]; guardrails?: { id: ListAgentsId1 | string; executeOn: "input" | "output"; }[]; plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[]; fallbacks?: { model: string; }[]; cache?: { ttl?: number; type: "exact_match"; }; loadBalancer?: ListAgentsLoadBalancer1; timeout?: { callTimeout: number; }; cacheControl?: { type: "ephemeral"; ttl?: "5m" | "1h"; }; promptCacheKey?: string; }; retry?: { count?: number; onCodes?: number[]; }; fallbackModels?: (string | ListAgentsFallbackModelConfiguration2)[]; }; }[]; hasMore: boolean; } ``` ### Delete an Agent Permanently remove an agent and all associated configuration from the workspace. Terminate active sessions and the key becomes reusable. ```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="") # 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(""); } run(); ``` ```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 } ``` ### Retrieve an Agent Retrieve the complete agent manifest by key, including model assignments, tools, knowledge bases, memory stores, and execution parameters. ```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="") # 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(""); console.log(result); } run(); ``` ```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 } ``` ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} { "id": str, "key": str, "display_name": Optional[str], "project_id": str, "created_by_id": Optional[str], "updated_by_id": Optional[str], "created": Optional[str], "updated": Optional[str], "status": Literal["live", "draft", "pending", "published"], "version": Optional[str], "path": str, "memory_stores": List[str], # optional "team_of_agents": [{ # optional "key": str, "role": Optional[str], }], "skills": List[str], # optional "metrics": { # optional "total_cost": Optional[float], }, "variables": Dict[str, Any], # optional "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": Optional[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"]], "chat_exposed": Optional[bool], "tools": [{ # optional "id": str, "key": Optional[str], "action_type": str, "display_name": Optional[str], "description": Optional[str], "configuration": Dict[str, Any], # optional "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": Optional[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": Union[RetrieveAgentRequestResponseFormatText, RetrieveAgentRequestResponseFormatJSONObject, RetrieveAgentRequestResponseFormatAgentsJSONSchema], # optional "reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]], "verbosity": Optional[str], "seed": Optional[float], "stop": Union[str, List[str]], # optional "thinking": Union[ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema], # optional "temperature": Optional[float], "top_p": Optional[float], "top_k": Optional[float], "tool_choice": Union[RetrieveAgentRequestToolChoice1, RetrieveAgentRequestToolChoice2], # optional "parallel_tool_calls": Optional[bool], "modalities": List[Literal["text", "audio"]], # optional "guardrails": [{ # optional "id": Union[RetrieveAgentRequestID1, str], "execute_on": Literal["input", "output"], }], "plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]], # optional "fallbacks": [{ # optional "model": str, }], "cache": { # optional "ttl": Optional[float], "type": Literal["exact_match"], }, "load_balancer": Union[RetrieveAgentRequestLoadBalancer1], # optional "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 }, "fallback_models": List[Union[str, RetrieveAgentRequestFallbackModelConfiguration2]], # optional }, } ``` ```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: "live" | "draft" | "pending" | "published"; version?: string; path: string; memoryStores?: string[]; teamOfAgents?: { key: string; role?: string; }[]; skills?: string[]; metrics?: { totalCost?: number; }; variables?: Record; knowledgeBases?: { knowledgeId: string; }[]; source?: "internal" | "external" | "experiment"; engine?: "text" | "jinja" | "mustache"; type?: "internal" | "a2a"; role: string; description: string; systemPrompt?: string; instructions: string; settings?: { maxIterations?: number; maxExecutionTime?: number; maxCost?: number; toolApprovalRequired?: "all" | "respect_tool" | "none"; chatExposed?: boolean; tools?: { id: string; key?: string; actionType: string; displayName?: string; description?: string; configuration?: Record; requiresApproval?: boolean; toolId?: string; conditions?: { condition: string; operator: string; value: string; }[]; timeout?: number; }[]; evaluators?: { id: string; sampleRate?: number; executeOn: "input" | "output"; }[]; guardrails?: { id: string; sampleRate?: number; executeOn: "input" | "output"; }[]; }; model: { id: string; integrationId?: string; parameters?: { name?: string; frequencyPenalty?: number; maxTokens?: number; maxCompletionTokens?: number; presencePenalty?: number; responseFormat?: RetrieveAgentRequestResponseFormatText | RetrieveAgentRequestResponseFormatJSONObject | RetrieveAgentRequestResponseFormatAgentsJSONSchema; reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"; verbosity?: string; seed?: number; stop?: string | string[]; thinking?: ThinkingConfigDisabledSchema | ThinkingConfigEnabledSchema | ThinkingConfigAdaptiveSchema; temperature?: number; topP?: number; topK?: number; toolChoice?: RetrieveAgentRequestToolChoice1 | RetrieveAgentRequestToolChoice2; parallelToolCalls?: boolean; modalities?: ("text" | "audio")[]; guardrails?: { id: RetrieveAgentRequestId1 | string; executeOn: "input" | "output"; }[]; plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[]; fallbacks?: { model: string; }[]; cache?: { ttl?: number; type: "exact_match"; }; loadBalancer?: RetrieveAgentRequestLoadBalancer1; timeout?: { callTimeout: number; }; cacheControl?: { type: "ephemeral"; ttl?: "5m" | "1h"; }; promptCacheKey?: string; }; retry?: { count?: number; onCodes?: number[]; }; fallbackModels?: (string | RetrieveAgentRequestFallbackModelConfiguration2)[]; }; } ``` ### Update an Agent Partially update an existing agent configuration including models, instructions, tools, knowledge bases, and execution parameters. ```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="", model="openai/gpt-6-astra", fallback_models=[ "", ], 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({ agentKey: "", model: "openai/gpt-6-astra", fallbackModels: [ "", ], settings: { tools: [ { type: "mcp", id: "01KA84ND5J0SWQMA2Q8HY5WZZZ", toolId: "01KXYZ123456789", requiresApproval: false, }, ], }, path: "Default", knowledgeBases: [ { knowledgeId: "customer-knowledge-base", }, ], }); console.log(result); } run(); ``` ```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": Optional[str], "model": Union[str, UpdateAgentModelConfiguration2], # optional "fallback_models": List[Union[str, UpdateAgentFallbackModelConfiguration2]], # optional "settings": { # optional "max_iterations": Optional[int], "max_execution_time": Optional[int], "max_cost": Optional[float], "tool_approval_required": Optional[Literal["all", "respect_tool", "none"]], "chat_exposed": Optional[bool], "tools": List[Union[GoogleSearchToolInput, WebScraperToolInput, CallSubAgentToolInput, RetrieveAgentsToolInput, QueryMemoryStoreToolInput, WriteMemoryStoreToolInput, RetrieveMemoryStoresToolInput, DeleteMemoryDocumentToolInput, RetrieveKnowledgeBasesToolInput, QueryKnowledgeBaseToolInput, CurrentDateToolInput, AdvisorToolInput, SidekickToolInput, CodeInterpreterToolInput, FileSystemToolInput, HTTPToolInput, CodeToolInput, FunctionToolInput, JSONSchemaToolInput, McpToolInput]], # optional "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], # optional "knowledge_bases": [{ # optional "knowledge_id": str, # required }], "team_of_agents": [{ # optional "key": str, # required "role": Optional[str], }], "skills": List[str], # optional "variables": Dict[str, Any], # optional "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 key?: string; displayName?: string; projectId?: string; role?: string; description?: string; instructions?: string; systemPrompt?: string; model?: string | UpdateAgentModelConfiguration2; fallbackModels?: (string | UpdateAgentFallbackModelConfiguration2)[]; settings?: { maxIterations?: number; maxExecutionTime?: number; maxCost?: number; toolApprovalRequired?: "all" | "respect_tool" | "none"; chatExposed?: boolean; tools?: (GoogleSearchToolInput | WebScraperToolInput | CallSubAgentToolInput | RetrieveAgentsToolInput | QueryMemoryStoreToolInput | WriteMemoryStoreToolInput | RetrieveMemoryStoresToolInput | DeleteMemoryDocumentToolInput | RetrieveKnowledgeBasesToolInput | QueryKnowledgeBaseToolInput | CurrentDateToolInput | AdvisorToolInput | SidekickToolInput | CodeInterpreterToolInput | FileSystemToolInput | HttpToolInput | CodeToolInput | FunctionToolInput | JsonSchemaToolInput | McpToolInput)[]; evaluators?: { id: string; // required sampleRate?: number; executeOn: "input" | "output"; // required }[]; guardrails?: { id: string; // required sampleRate?: number; executeOn: "input" | "output"; // required }[]; }; path?: string; memoryStores?: string[]; knowledgeBases?: { knowledgeId: string; // required }[]; teamOfAgents?: { key: string; // required role?: string; }[]; skills?: string[]; variables?: Record; engine?: "text" | "jinja" | "mustache"; versionIncrement?: "major" | "minor" | "patch"; versionDescription?: string; } ``` ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}} { "id": str, "key": str, "display_name": Optional[str], "project_id": str, "created_by_id": Optional[str], "updated_by_id": Optional[str], "created": Optional[str], "updated": Optional[str], "status": Literal["live", "draft", "pending", "published"], "version": Optional[str], "path": str, "memory_stores": List[str], # optional "team_of_agents": [{ # optional "key": str, "role": Optional[str], }], "skills": List[str], # optional "metrics": { # optional "total_cost": Optional[float], }, "variables": Dict[str, Any], # optional "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": Optional[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"]], "chat_exposed": Optional[bool], "tools": [{ # optional "id": str, "key": Optional[str], "action_type": str, "display_name": Optional[str], "description": Optional[str], "configuration": Dict[str, Any], # optional "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": Optional[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": Union[UpdateAgentResponseFormatAgentsResponseText, UpdateAgentResponseFormatAgentsResponseJSONObject, UpdateAgentResponseFormatAgentsResponse200JSONSchema], # optional "reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]], "verbosity": Optional[str], "seed": Optional[float], "stop": Union[str, List[str]], # optional "thinking": Union[ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema], # optional "temperature": Optional[float], "top_p": Optional[float], "top_k": Optional[float], "tool_choice": Union[UpdateAgentToolChoiceAgentsResponse1, UpdateAgentToolChoiceAgentsResponse2], # optional "parallel_tool_calls": Optional[bool], "modalities": List[Literal["text", "audio"]], # optional "guardrails": [{ # optional "id": Union[UpdateAgentIDAgentsResponse1, str], "execute_on": Literal["input", "output"], }], "plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]], # optional "fallbacks": [{ # optional "model": str, }], "cache": { # optional "ttl": Optional[float], "type": Literal["exact_match"], }, "load_balancer": Union[UpdateAgentLoadBalancerAgentsResponse1], # optional "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 }, "fallback_models": List[Union[str, UpdateAgentFallbackModelConfigurationAgents2]], # optional }, } ``` ```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: "live" | "draft" | "pending" | "published"; version?: string; path: string; memoryStores?: string[]; teamOfAgents?: { key: string; role?: string; }[]; skills?: string[]; metrics?: { totalCost?: number; }; variables?: Record; knowledgeBases?: { knowledgeId: string; }[]; source?: "internal" | "external" | "experiment"; engine?: "text" | "jinja" | "mustache"; type?: "internal" | "a2a"; role: string; description: string; systemPrompt?: string; instructions: string; settings?: { maxIterations?: number; maxExecutionTime?: number; maxCost?: number; toolApprovalRequired?: "all" | "respect_tool" | "none"; chatExposed?: boolean; tools?: { id: string; key?: string; actionType: string; displayName?: string; description?: string; configuration?: Record; requiresApproval?: boolean; toolId?: string; conditions?: { condition: string; operator: string; value: string; }[]; timeout?: number; }[]; evaluators?: { id: string; sampleRate?: number; executeOn: "input" | "output"; }[]; guardrails?: { id: string; sampleRate?: number; executeOn: "input" | "output"; }[]; }; model: { id: string; integrationId?: string; parameters?: { name?: string; frequencyPenalty?: number; maxTokens?: number; maxCompletionTokens?: number; presencePenalty?: number; responseFormat?: UpdateAgentResponseFormatAgentsResponseText | UpdateAgentResponseFormatAgentsResponseJSONObject | UpdateAgentResponseFormatAgentsResponse200JSONSchema; reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max"; verbosity?: string; seed?: number; stop?: string | string[]; thinking?: ThinkingConfigDisabledSchema | ThinkingConfigEnabledSchema | ThinkingConfigAdaptiveSchema; temperature?: number; topP?: number; topK?: number; toolChoice?: UpdateAgentToolChoiceAgentsResponse1 | UpdateAgentToolChoiceAgentsResponse2; parallelToolCalls?: boolean; modalities?: ("text" | "audio")[]; guardrails?: { id: UpdateAgentIdAgentsResponse1 | string; executeOn: "input" | "output"; }[]; plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[]; fallbacks?: { model: string; }[]; cache?: { ttl?: number; type: "exact_match"; }; loadBalancer?: UpdateAgentLoadBalancerAgentsResponse1; timeout?: { callTimeout: number; }; cacheControl?: { type: "ephemeral"; ttl?: "5m" | "1h"; }; promptCacheKey?: string; }; retry?: { count?: number; onCodes?: number[]; }; fallbackModels?: (string | UpdateAgentFallbackModelConfigurationAgents2)[]; }; } ``` ### 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="", 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("", { 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(); ``` ```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"}} { key: string; // required taskId?: string; message: { // required messageId?: string; role: RoleUserMessage | RoleToolMessage; // required parts: (TextPart | FilePart | ToolResultPart | ErrorPart)[]; // required }; variables?: Record; identity?: { id: string; // required displayName?: string; email?: string; metadata?: Record[]; logoUrl?: string; tags?: string[]; }; contact?: { id: string; // required displayName?: string; email?: string; metadata?: Record[]; logoUrl?: string; tags?: string[]; }; thread?: { id: string; // required tags?: string[]; }; memory?: { entityId: string; // required }; metadata?: Record; engine?: "text" | "jinja" | "mustache"; configuration?: { blocking?: boolean; }; } ``` ```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; }[]; metadata?: Record; } ``` ### 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="", model="openai/gpt-6-astra", role="", instructions="", message={ "role": "tool", "parts": [ { "kind": "text", "text": "", }, ], }, path="Default", settings={}, fallback_models=[ "", ], 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: "", model: "openai/gpt-6-astra", fallbackModels: [ "", ], role: "", instructions: "", message: { role: "tool", parts: [ { kind: "text", text: "", }, ], }, 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(); ``` ```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": 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: string | RunAgentModelConfiguration2; // required 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; identity?: { id: string; // required displayName?: string; email?: string; metadata?: Record[]; logoUrl?: string; tags?: string[]; }; contact?: { id: string; // required displayName?: string; email?: string; metadata?: Record[]; 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; engine?: "text" | "jinja" | "mustache"; } ``` ```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; }[]; metadata?: Record; } ``` ### 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="", model="openai/gpt-6-astra", role="", instructions="", message={ "role": "user", "parts": [ { "kind": "file", "file": { "uri": "https://example.com/report.pdf", }, }, ], }, path="Default", settings={}, fallback_models=[ "", ], 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: "", model: "openai/gpt-6-astra", fallbackModels: [ "", ], role: "", instructions: "", 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(); ``` ```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": 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: string | StreamRunAgentModelConfiguration2; // required 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; identity?: { id: string; // required displayName?: string; email?: string; metadata?: Record[]; logoUrl?: string; tags?: string[]; }; contact?: { id: string; // required displayName?: string; email?: string; metadata?: Record[]; 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; engine?: "text" | "jinja" | "mustache"; streamTimeoutSeconds?: 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="", 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({ agentKey: "", 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", ], }, }); for await (const event of result) { console.log(event); } } run(); ``` ```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"}} { key: string; // required taskId?: string; message: { // required messageId?: string; role: StreamAgentRoleUserMessage | StreamAgentRoleToolMessage; // required parts: (TextPart | FilePart | ToolResultPart | ErrorPart)[]; // required }; variables?: Record; identity?: { id: string; // required displayName?: string; email?: string; metadata?: Record[]; logoUrl?: string; tags?: string[]; }; contact?: { id: string; // required displayName?: string; email?: string; metadata?: Record[]; logoUrl?: string; tags?: string[]; }; thread?: { id: string; // required tags?: string[]; }; memory?: { entityId: string; // required }; metadata?: Record; engine?: "text" | "jinja" | "mustache"; configuration?: { blocking?: boolean; }; streamTimeoutSeconds?: number; } ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.