Agents
Create an Agent
Create a new agent with the specified model, instructions, tools, and knowledge bases. Supports fallback models and configurable execution settings.from orq_ai_sdk import Orq
import os
with Orq(
api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:
res = orq.agents.create(key="<key>", role="<value>", description="alongside beneath doubtfully behest validity bah after furthermore", instructions="<value>", path="Default", model={
"id": "<id>",
"retry": {
"count": 3,
"on_codes": [
429,
500,
502,
503,
504,
],
},
}, settings={
"tools": [
{
"type": "mcp",
"id": "01KA84ND5J0SWQMA2Q8HY5WZZZ",
"tool_id": "01KXYZ123456789",
"requires_approval": False,
},
],
}, fallback_models=[
{
"id": "<id>",
"retry": {
"count": 3,
"on_codes": [
429,
500,
502,
503,
504,
],
},
},
], knowledge_bases=[
{
"knowledge_id": "customer-knowledge-base",
},
], engine="text")
# Handle response
print(res)
import { Orq } from "@orq-ai/node";
const orq = new Orq({
apiKey: process.env["ORQ_API_KEY"] ?? "",
});
async function run() {
const result = await orq.agents.create({
key: "<key>",
role: "<value>",
description: "alongside beneath doubtfully behest validity bah after furthermore",
instructions: "<value>",
path: "Default",
model: {
id: "<id>",
retry: {
count: 3,
onCodes: [
429,
500,
502,
503,
504,
],
},
},
fallbackModels: [
{
id: "<id>",
parameters: {
fallbacks: [
{
model: "openai/gpt-4o-mini",
},
],
cache: {
ttl: 3600,
type: "exact_match",
},
loadBalancer: {
type: "weight_based",
models: [
{
model: "openai/gpt-4o",
weight: 0.7,
},
],
},
timeout: {
callTimeout: 30000,
},
},
retry: {
count: 3,
onCodes: [
429,
500,
502,
503,
504,
],
},
},
],
settings: {
tools: [
{
type: "mcp",
id: "01KA84ND5J0SWQMA2Q8HY5WZZZ",
toolId: "01KXYZ123456789",
requiresApproval: false,
},
],
},
knowledgeBases: [
{
knowledgeId: "customer-knowledge-base",
},
],
});
console.log(result);
}
run();
Show Parameters
Show Parameters
{
"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, 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"]],
}
{
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 | 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<string, any>;
source?: "internal" | "external" | "experiment";
engine?: "text" | "jinja" | "mustache";
}
Show Response
Show Response
{
"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[PIIRedactionPluginAuto, PIIRedactionPluginEn, PIIRedactionPluginNl, 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
},
}
{
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<string, any>;
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<string, any>;
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?: (PIIRedactionPluginAuto | PIIRedactionPluginEn | PIIRedactionPluginNl | 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.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)
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();
Show Parameters
Show Parameters
{
"limit": Optional[float],
"starting_after": Optional[str],
"ending_before": Optional[str],
"type": Optional[Literal["internal"]],
}
{
limit?: number;
startingAfter?: string;
endingBefore?: string;
}
Show Response
Show Response
{
"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[PIIRedactionPluginAuto, PIIRedactionPluginEn, PIIRedactionPluginNl, 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,
}
{
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<string, any>;
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<string, any>;
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?: (PIIRedactionPluginAuto | PIIRedactionPluginEn | PIIRedactionPluginNl | 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.from orq_ai_sdk import Orq
import os
with Orq(
api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:
orq.agents.delete(agent_key="<value>")
# Use the SDK ...
import { Orq } from "@orq-ai/node";
const orq = new Orq({
apiKey: process.env["ORQ_API_KEY"] ?? "",
});
async function run() {
await orq.agents.delete("<value>");
}
run();
Show Parameters
Show Parameters
{
"agent_key": str, # required
}
{
agentKey: string; // required
}
Retrieve an Agent
Retrieve the complete agent manifest by key, including model assignments, tools, knowledge bases, memory stores, and execution parameters.from orq_ai_sdk import Orq
import os
with Orq(
api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:
res = orq.agents.retrieve(agent_key="<value>")
# Handle response
print(res)
import { Orq } from "@orq-ai/node";
const orq = new Orq({
apiKey: process.env["ORQ_API_KEY"] ?? "",
});
async function run() {
const result = await orq.agents.retrieve("<value>");
console.log(result);
}
run();
Show Parameters
Show Parameters
{
"agent_key": str, # required
}
{
agentKey: string; // required
}
Show Response
Show Response
{
"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[PIIRedactionPluginAuto, PIIRedactionPluginEn, PIIRedactionPluginNl, 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
},
}
{
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<string, any>;
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<string, any>;
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?: (PIIRedactionPluginAuto | PIIRedactionPluginEn | PIIRedactionPluginNl | 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.from orq_ai_sdk import Orq
import os
with Orq(
api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:
res = orq.agents.update(agent_key="<value>", model="El Camino", fallback_models=[
"<value>",
], settings={
"tools": [
{
"type": "mcp",
"id": "01KA84ND5J0SWQMA2Q8HY5WZZZ",
"tool_id": "01KXYZ123456789",
"requires_approval": False,
},
],
}, path="Default", knowledge_bases=[
{
"knowledge_id": "customer-knowledge-base",
},
])
# Handle response
print(res)
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: "<value>",
model: "El Camino",
fallbackModels: [
"<value>",
],
settings: {
tools: [
{
type: "mcp",
id: "01KA84ND5J0SWQMA2Q8HY5WZZZ",
toolId: "01KXYZ123456789",
requiresApproval: false,
},
],
},
path: "Default",
knowledgeBases: [
{
knowledgeId: "customer-knowledge-base",
},
],
});
console.log(result);
}
run();
Show Parameters
Show Parameters
{
"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, 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],
}
{
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 | 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<string, any>;
engine?: "text" | "jinja" | "mustache";
versionIncrement?: "major" | "minor" | "patch";
versionDescription?: string;
}
Show Response
Show Response
{
"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[PIIRedactionPluginAuto, PIIRedactionPluginEn, PIIRedactionPluginNl, 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
},
}
{
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<string, any>;
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<string, any>;
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?: (PIIRedactionPluginAuto | PIIRedactionPluginEn | PIIRedactionPluginNl | 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.from orq_ai_sdk import Orq
import os
with Orq(
api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:
res = orq.agents.invoke(key="<key>", message={
"role": "user",
"parts": [],
}, identity={
"id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
"display_name": "Jane Doe",
"email": "jane.doe@example.com",
"metadata": [
{
"department": "Engineering",
"role": "Senior Developer",
},
],
"logo_url": "https://example.com/avatars/jane-doe.jpg",
"tags": [
"hr",
"engineering",
],
}, thread={
"id": "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
"tags": [
"customer-support",
"priority-high",
],
})
# Handle response
print(res)
import { Orq } from "@orq-ai/node";
const orq = new Orq({
apiKey: process.env["ORQ_API_KEY"] ?? "",
});
async function run() {
const result = await orq.agents.invoke("<key>", {
message: {
role: "user",
parts: [],
},
identity: {
id: "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
displayName: "Jane Doe",
email: "jane.doe@example.com",
metadata: [
{
"department": "Engineering",
"role": "Senior Developer",
},
],
logoUrl: "https://example.com/avatars/jane-doe.jpg",
tags: [
"hr",
"engineering",
],
},
thread: {
id: "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
tags: [
"customer-support",
"priority-high",
],
},
});
console.log(result);
}
run();
Show Parameters
Show Parameters
{
"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],
},
}
{
key: string; // required
taskId?: string;
message: { // required
messageId?: string;
role: RoleUserMessage | RoleToolMessage; // required
parts: (TextPart | FilePart | ToolResultPart | ErrorPart)[]; // required
};
variables?: Record<string, any>;
identity?: {
id: string; // required
displayName?: string;
email?: string;
metadata?: Record<string, any>[];
logoUrl?: string;
tags?: string[];
};
contact?: {
id: string; // required
displayName?: string;
email?: string;
metadata?: Record<string, any>[];
logoUrl?: string;
tags?: string[];
};
thread?: {
id: string; // required
tags?: string[];
};
memory?: {
entityId: string; // required
};
metadata?: Record<string, any>;
engine?: "text" | "jinja" | "mustache";
configuration?: {
blocking?: boolean;
};
}
Show Response
Show Response
{
"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
}
{
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.from orq_ai_sdk import Orq
import os
with Orq(
api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:
res = orq.agents.run(key="<key>", model="F-150", role="<value>", instructions="<value>", message={
"role": "tool",
"parts": [
{
"kind": "text",
"text": "<value>",
},
],
}, path="Default", settings={}, fallback_models=[
"<value>",
], identity={
"id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
"display_name": "Jane Doe",
"email": "jane.doe@example.com",
"metadata": [
{
"department": "Engineering",
"role": "Senior Developer",
},
],
"logo_url": "https://example.com/avatars/jane-doe.jpg",
"tags": [
"hr",
"engineering",
],
}, thread={
"id": "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
"tags": [
"customer-support",
"priority-high",
],
}, knowledge_bases=[
{
"knowledge_id": "customer-knowledge-base",
},
], engine="text")
# Handle response
print(res)
import { Orq } from "@orq-ai/node";
const orq = new Orq({
apiKey: process.env["ORQ_API_KEY"] ?? "",
});
async function run() {
const result = await orq.agents.run({
key: "<key>",
model: "F-150",
fallbackModels: [
"<value>",
],
role: "<value>",
instructions: "<value>",
message: {
role: "tool",
parts: [
{
kind: "text",
text: "<value>",
},
],
},
identity: {
id: "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
displayName: "Jane Doe",
email: "jane.doe@example.com",
metadata: [
{
"department": "Engineering",
"role": "Senior Developer",
},
],
logoUrl: "https://example.com/avatars/jane-doe.jpg",
tags: [
"hr",
"engineering",
],
},
thread: {
id: "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
tags: [
"customer-support",
"priority-high",
],
},
path: "Default",
knowledgeBases: [
{
knowledgeId: "customer-knowledge-base",
},
],
settings: {},
});
console.log(result);
}
run();
Show Parameters
Show Parameters
{
"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, 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"]],
}
{
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<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 | 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";
}
Show Response
Show Response
{
"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
}
{
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>;
}
Stream Run [deprecated]
Run an agent with streaming via SSE, combining inline configuration with real-time updates including messages, tool executions, and status.from orq_ai_sdk import Orq
import os
with Orq(
api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:
res = orq.agents.stream_run(key="<key>", model="Alpine", role="<value>", instructions="<value>", message={
"role": "user",
"parts": [
{
"kind": "file",
"file": {
"uri": "https://jumbo-zebra.info/",
},
},
],
}, path="Default", settings={}, fallback_models=[
"<value>",
], identity={
"id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
"display_name": "Jane Doe",
"email": "jane.doe@example.com",
"metadata": [
{
"department": "Engineering",
"role": "Senior Developer",
},
],
"logo_url": "https://example.com/avatars/jane-doe.jpg",
"tags": [
"hr",
"engineering",
],
}, thread={
"id": "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
"tags": [
"customer-support",
"priority-high",
],
}, knowledge_bases=[
{
"knowledge_id": "customer-knowledge-base",
},
], engine="text")
with res as event_stream:
for event in event_stream:
# handle event
print(event, flush=True)
import { Orq } from "@orq-ai/node";
const orq = new Orq({
apiKey: process.env["ORQ_API_KEY"] ?? "",
});
async function run() {
const result = await orq.agents.streamRun({
key: "<key>",
model: "Alpine",
fallbackModels: [
"<value>",
],
role: "<value>",
instructions: "<value>",
message: {
role: "user",
parts: [
{
kind: "file",
file: {
uri: "https://jumbo-zebra.info/",
},
},
],
},
identity: {
id: "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
displayName: "Jane Doe",
email: "jane.doe@example.com",
metadata: [
{
"department": "Engineering",
"role": "Senior Developer",
},
],
logoUrl: "https://example.com/avatars/jane-doe.jpg",
tags: [
"hr",
"engineering",
],
},
thread: {
id: "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
tags: [
"customer-support",
"priority-high",
],
},
path: "Default",
knowledgeBases: [
{
knowledgeId: "customer-knowledge-base",
},
],
settings: {},
});
for await (const event of result) {
console.log(event);
}
}
run();
Show Parameters
Show Parameters
{
"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, 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],
}
{
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<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 | 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;
}
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.from orq_ai_sdk import Orq
import os
with Orq(
api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:
res = orq.agents.stream(key="<key>", message={
"role": "user",
"parts": [],
}, identity={
"id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
"display_name": "Jane Doe",
"email": "jane.doe@example.com",
"metadata": [
{
"department": "Engineering",
"role": "Senior Developer",
},
],
"logo_url": "https://example.com/avatars/jane-doe.jpg",
"tags": [
"hr",
"engineering",
],
}, thread={
"id": "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
"tags": [
"customer-support",
"priority-high",
],
})
with res as event_stream:
for event in event_stream:
# handle event
print(event, flush=True)
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: "<key>",
message: {
role: "user",
parts: [],
},
identity: {
id: "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
displayName: "Jane Doe",
email: "jane.doe@example.com",
metadata: [
{
"department": "Engineering",
"role": "Senior Developer",
},
],
logoUrl: "https://example.com/avatars/jane-doe.jpg",
tags: [
"hr",
"engineering",
],
},
thread: {
id: "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
tags: [
"customer-support",
"priority-high",
],
},
});
for await (const event of result) {
console.log(event);
}
}
run();
Show Parameters
Show Parameters
{
"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],
}
{
key: string; // required
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;
}