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="Customer support triage agent", instructions="<value>", path="Default", model={
"id": "<id>",
"retry": {
"count": 3,
"on_codes": [
429,
500,
502,
503,
504,
],
},
}, settings={
"tools": [
{
"type": "mcp",
"id": "<id>",
"tool_id": "<id>",
"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: "Customer support triage agent",
instructions: "<value>",
path: "Default",
model: {
id: "<id>",
retry: {
count: 3,
onCodes: [
429,
500,
502,
503,
504,
],
},
},
fallbackModels: [
{
id: "<id>",
retry: {
count: 3,
onCodes: [
429,
500,
502,
503,
504,
],
},
},
],
settings: {
tools: [
{
type: "mcp",
id: "<id>",
toolId: "<id>",
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": { # required
# one of: ModelConfiguration2, str
"id": str, # required
"parameters": { # optional
"name": Optional[str],
"frequency_penalty": Optional[float],
"max_tokens": Optional[int],
"max_completion_tokens": Optional[int],
"presence_penalty": Optional[float],
"response_format": { # optional
# one of: Text, JSONObject, JSONSchema
"type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]], # required
"json_schema": { # required (variant-specific)
"description": Optional[str],
"name": str, # required
"schema_": Optional[Any],
"strict": Optional[bool],
},
},
"reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]],
"verbosity": Optional[str],
"seed": Optional[float],
"stop": Union[str, List[str]], # optional
"thinking": { # optional
# one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
"type": Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]], # required
"budget_tokens": float, # required (variant-specific)
"thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
},
"temperature": Optional[float],
"top_p": Optional[float],
"top_k": Optional[float],
"tool_choice": { # optional
# one of: ToolChoice1, ToolChoice2
"type": Optional[Literal["function"]],
"function": { # required (variant-specific)
"name": str, # required
},
},
"parallel_tool_calls": Optional[bool],
"modalities": List[Literal["text", "audio"]], # optional
"guardrails": [{ # optional
"id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str], # required
"execute_on": Literal["input", "output"], # required
}],
"plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]], # optional
"fallbacks": [{ # optional
"model": str, # required
}],
"cache": { # optional
"ttl": Optional[float],
"type": Literal["exact_match"], # required
},
"load_balancer": { # optional
# one of: LoadBalancer1
"type": Literal["weight_based"], # required
"models": [{ # required
"model": str, # required
"weight": Optional[float],
}],
},
"timeout": { # optional
"call_timeout": float, # required
},
"cache_control": { # optional
"type": Literal["ephemeral"], # required
"ttl": Optional[Literal["5m", "1h"]],
},
"prompt_cache_key": Optional[str],
},
"retry": { # optional
"count": Optional[float],
"on_codes": List[float], # optional
},
},
"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"]],
}
{
key: string; // required
displayName?: string;
role: string; // required
description: string; // required
instructions: string; // required
systemPrompt?: string;
path: string; // required
model: { // required
// one of: ModelConfiguration2, string
id: string; // required
parameters?: {
name?: string;
frequencyPenalty?: number;
maxTokens?: number;
maxCompletionTokens?: number;
presencePenalty?: number;
responseFormat?: {
// one of: Text, JSONObject, JSONSchema
type: "text" | "json_object" | "json_schema"; // required
jsonSchema: { // required (variant-specific)
description?: string;
name: string; // required
schema?: any;
strict?: boolean;
};
};
reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
verbosity?: string;
seed?: number;
stop?: string | string[];
thinking?: {
// one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
type: "disabled" | "enabled" | "adaptive"; // required
budgetTokens: number; // required (variant-specific)
thinkingLevel?: "minimal" | "low" | "medium" | "high";
};
temperature?: number;
topP?: number;
topK?: number;
toolChoice?: {
// one of: ToolChoice1, ToolChoice2
type?: "function";
function: { // required (variant-specific)
name: string; // required
};
};
parallelToolCalls?: boolean;
modalities?: ("text" | "audio")[];
guardrails?: {
id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string; // required
executeOn: "input" | "output"; // required
}[];
plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
fallbacks?: {
model: string; // required
}[];
cache?: {
ttl?: number;
type: "exact_match"; // required
};
loadBalancer?: {
// one of: LoadBalancer1
type: "weight_based"; // required
models: { // required
model: string; // required
weight?: number;
}[];
};
timeout?: {
callTimeout: number; // required
};
cacheControl?: {
type: "ephemeral"; // required
ttl?: "5m" | "1h";
};
promptCacheKey?: string;
};
retry?: {
count?: number;
onCodes?: number[];
};
};
fallbackModels?: (string | 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<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
"agent_plugins": [{ # optional
"id": str,
"version": str,
}],
"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": { # optional
# one of: CreateAgentRequestResponseFormatText, CreateAgentRequestResponseFormatJSONObject, CreateAgentRequestResponseFormatAgentsResponse201JSONSchema
"type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]],
"json_schema": {
"description": Optional[str],
"name": str,
"schema_": Optional[Any],
"strict": Optional[bool],
},
},
"reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]],
"verbosity": Optional[str],
"seed": Optional[float],
"stop": Union[str, List[str]], # optional
"thinking": { # optional
# one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
"type": Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]],
"budget_tokens": float,
"thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
},
"temperature": Optional[float],
"top_p": Optional[float],
"top_k": Optional[float],
"tool_choice": { # optional
# one of: CreateAgentRequestToolChoiceAgents1, CreateAgentRequestToolChoiceAgents2
"type": Optional[Literal["function"]],
"function": {
"name": str,
},
},
"parallel_tool_calls": Optional[bool],
"modalities": List[Literal["text", "audio"]], # optional
"guardrails": [{ # optional
"id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str],
"execute_on": Literal["input", "output"],
}],
"plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]], # optional
"fallbacks": [{ # optional
"model": str,
}],
"cache": { # optional
"ttl": Optional[float],
"type": Literal["exact_match"],
},
"load_balancer": { # optional
# one of: CreateAgentRequestLoadBalancerAgents1
"type": Literal["weight_based"],
"models": [{
"model": str,
"weight": Optional[float],
}],
},
"timeout": { # optional
"call_timeout": float,
},
"cache_control": { # optional
"type": Literal["ephemeral"],
"ttl": Optional[Literal["5m", "1h"]],
},
"prompt_cache_key": Optional[str],
},
"retry": { # optional
"count": Optional[float],
"on_codes": List[float], # optional
},
"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[];
agentPlugins?: {
id: string;
version: 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?: {
// one of: CreateAgentRequestResponseFormatText, CreateAgentRequestResponseFormatJSONObject, CreateAgentRequestResponseFormatAgentsResponse201JSONSchema
type: "text" | "json_object" | "json_schema";
jsonSchema: {
description?: string;
name: string;
schema?: any;
strict?: boolean;
};
};
reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
verbosity?: string;
seed?: number;
stop?: string | string[];
thinking?: {
// one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
type: "disabled" | "enabled" | "adaptive";
budgetTokens: number;
thinkingLevel?: "minimal" | "low" | "medium" | "high";
};
temperature?: number;
topP?: number;
topK?: number;
toolChoice?: {
// one of: CreateAgentRequestToolChoiceAgents1, CreateAgentRequestToolChoiceAgents2
type?: "function";
function: {
name: string;
};
};
parallelToolCalls?: boolean;
modalities?: ("text" | "audio")[];
guardrails?: {
id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string;
executeOn: "input" | "output";
}[];
plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
fallbacks?: {
model: string;
}[];
cache?: {
ttl?: number;
type: "exact_match";
};
loadBalancer?: {
// one of: CreateAgentRequestLoadBalancerAgents1
type: "weight_based";
models: {
model: string;
weight?: number;
}[];
};
timeout?: {
callTimeout: number;
};
cacheControl?: {
type: "ephemeral";
ttl?: "5m" | "1h";
};
promptCacheKey?: string;
};
retry?: {
count?: number;
onCodes?: number[];
};
fallbackModels?: (string | CreateAgentRequestFallbackModelConfiguration2)[];
};
}
Show Variant types
Show Variant types
FallbackModelConfiguration2
{
"id": str,
"parameters": { # optional
"name": Optional[str],
"frequency_penalty": Optional[float],
"max_tokens": Optional[int],
"max_completion_tokens": Optional[int],
"presence_penalty": Optional[float],
"response_format": { # optional
# one of: ResponseFormatText, ResponseFormatJSONObject, CreateAgentRequestResponseFormatJSONSchema
"type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]],
"json_schema": {
"description": Optional[str],
"name": str,
"schema_": Optional[Any],
"strict": Optional[bool],
},
},
"reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]],
"verbosity": Optional[str],
"seed": Optional[float],
"stop": Union[str, List[str]], # optional
"thinking": { # optional
# one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
"type": Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]],
"budget_tokens": float,
"thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
},
"temperature": Optional[float],
"top_p": Optional[float],
"top_k": Optional[float],
"tool_choice": { # optional
# one of: CreateAgentRequestToolChoice1, CreateAgentRequestToolChoice2
"type": Optional[Literal["function"]],
"function": {
"name": str,
},
},
"parallel_tool_calls": Optional[bool],
"modalities": List[Literal["text", "audio"]], # optional
"guardrails": [{ # optional
"id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str],
"execute_on": Literal["input", "output"],
}],
"plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]], # optional
"fallbacks": [{ # optional
"model": str,
}],
"cache": { # optional
"ttl": Optional[float],
"type": Literal["exact_match"],
},
"load_balancer": { # optional
# one of: CreateAgentRequestLoadBalancer1
"type": Literal["weight_based"],
"models": [{
"model": str,
"weight": Optional[float],
}],
},
"timeout": { # optional
"call_timeout": float,
},
"cache_control": { # optional
"type": Literal["ephemeral"],
"ttl": Optional[Literal["5m", "1h"]],
},
"prompt_cache_key": Optional[str],
},
"retry": { # optional
"count": Optional[float],
"on_codes": List[float], # optional
},
}
{
id: string;
parameters?: {
name?: string;
frequencyPenalty?: number;
maxTokens?: number;
maxCompletionTokens?: number;
presencePenalty?: number;
responseFormat?: {
// one of: ResponseFormatText, ResponseFormatJSONObject, CreateAgentRequestResponseFormatJSONSchema
type: "text" | "json_object" | "json_schema";
jsonSchema: {
description?: string;
name: string;
schema?: any;
strict?: boolean;
};
};
reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
verbosity?: string;
seed?: number;
stop?: string | string[];
thinking?: {
// one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
type: "disabled" | "enabled" | "adaptive";
budgetTokens: number;
thinkingLevel?: "minimal" | "low" | "medium" | "high";
};
temperature?: number;
topP?: number;
topK?: number;
toolChoice?: {
// one of: CreateAgentRequestToolChoice1, CreateAgentRequestToolChoice2
type?: "function";
function: {
name: string;
};
};
parallelToolCalls?: boolean;
modalities?: ("text" | "audio")[];
guardrails?: {
id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string;
executeOn: "input" | "output";
}[];
plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
fallbacks?: {
model: string;
}[];
cache?: {
ttl?: number;
type: "exact_match";
};
loadBalancer?: {
// one of: CreateAgentRequestLoadBalancer1
type: "weight_based";
models: {
model: string;
weight?: number;
}[];
};
timeout?: {
callTimeout: number;
};
cacheControl?: {
type: "ephemeral";
ttl?: "5m" | "1h";
};
promptCacheKey?: string;
};
retry?: {
count?: number;
onCodes?: number[];
};
}
CreateAgentRequestFallbackModelConfiguration2
{
"id": str,
"parameters": { # optional
"name": Optional[str],
"frequency_penalty": Optional[float],
"max_tokens": Optional[int],
"max_completion_tokens": Optional[int],
"presence_penalty": Optional[float],
"response_format": { # optional
# one of: CreateAgentRequestResponseFormatAgentsText, CreateAgentRequestResponseFormatAgentsJSONObject, CreateAgentRequestResponseFormatAgentsResponse201ApplicationJSONResponseBodyJSONSchema
"type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]],
"json_schema": {
"description": Optional[str],
"name": str,
"schema_": Optional[Any],
"strict": Optional[bool],
},
},
"reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]],
"verbosity": Optional[str],
"seed": Optional[float],
"stop": Union[str, List[str]], # optional
"thinking": { # optional
# one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
"type": Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]],
"budget_tokens": float,
"thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
},
"temperature": Optional[float],
"top_p": Optional[float],
"top_k": Optional[float],
"tool_choice": { # optional
# one of: CreateAgentRequestToolChoiceAgentsResponse1, CreateAgentRequestToolChoiceAgentsResponse2
"type": Optional[Literal["function"]],
"function": {
"name": str,
},
},
"parallel_tool_calls": Optional[bool],
"modalities": List[Literal["text", "audio"]], # optional
"guardrails": [{ # optional
"id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str],
"execute_on": Literal["input", "output"],
}],
"plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]], # optional
"fallbacks": [{ # optional
"model": str,
}],
"cache": { # optional
"ttl": Optional[float],
"type": Literal["exact_match"],
},
"load_balancer": { # optional
# one of: CreateAgentRequestLoadBalancerAgentsResponse1
"type": Literal["weight_based"],
"models": [{
"model": str,
"weight": Optional[float],
}],
},
"timeout": { # optional
"call_timeout": float,
},
"cache_control": { # optional
"type": Literal["ephemeral"],
"ttl": Optional[Literal["5m", "1h"]],
},
"prompt_cache_key": Optional[str],
},
"retry": { # optional
"count": Optional[float],
"on_codes": List[float], # optional
},
}
{
id: string;
parameters?: {
name?: string;
frequencyPenalty?: number;
maxTokens?: number;
maxCompletionTokens?: number;
presencePenalty?: number;
responseFormat?: {
// one of: CreateAgentRequestResponseFormatAgentsText, CreateAgentRequestResponseFormatAgentsJSONObject, CreateAgentRequestResponseFormatAgentsResponse201ApplicationJSONResponseBodyJSONSchema
type: "text" | "json_object" | "json_schema";
jsonSchema: {
description?: string;
name: string;
schema?: any;
strict?: boolean;
};
};
reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
verbosity?: string;
seed?: number;
stop?: string | string[];
thinking?: {
// one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
type: "disabled" | "enabled" | "adaptive";
budgetTokens: number;
thinkingLevel?: "minimal" | "low" | "medium" | "high";
};
temperature?: number;
topP?: number;
topK?: number;
toolChoice?: {
// one of: CreateAgentRequestToolChoiceAgentsResponse1, CreateAgentRequestToolChoiceAgentsResponse2
type?: "function";
function: {
name: string;
};
};
parallelToolCalls?: boolean;
modalities?: ("text" | "audio")[];
guardrails?: {
id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string;
executeOn: "input" | "output";
}[];
plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
fallbacks?: {
model: string;
}[];
cache?: {
ttl?: number;
type: "exact_match";
};
loadBalancer?: {
// one of: CreateAgentRequestLoadBalancerAgentsResponse1
type: "weight_based";
models: {
model: string;
weight?: number;
}[];
};
timeout?: {
callTimeout: number;
};
cacheControl?: {
type: "ephemeral";
ttl?: "5m" | "1h";
};
promptCacheKey?: string;
};
retry?: {
count?: number;
onCodes?: number[];
};
}
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"]],
}
// orq.agents.list(limit?, startingAfter?, endingBefore?, type?)
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
"agent_plugins": [{ # optional
"id": str,
"version": str,
}],
"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": { # optional
# one of: ListAgentsResponseFormatText, ListAgentsResponseFormatJSONObject, ListAgentsResponseFormatAgentsJSONSchema
"type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]],
"json_schema": {
"description": Optional[str],
"name": str,
"schema_": Optional[Any],
"strict": Optional[bool],
},
},
"reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]],
"verbosity": Optional[str],
"seed": Optional[float],
"stop": Union[str, List[str]], # optional
"thinking": { # optional
# one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
"type": Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]],
"budget_tokens": float,
"thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
},
"temperature": Optional[float],
"top_p": Optional[float],
"top_k": Optional[float],
"tool_choice": { # optional
# one of: ListAgentsToolChoice1, ListAgentsToolChoice2
"type": Optional[Literal["function"]],
"function": {
"name": str,
},
},
"parallel_tool_calls": Optional[bool],
"modalities": List[Literal["text", "audio"]], # optional
"guardrails": [{ # optional
"id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str],
"execute_on": Literal["input", "output"],
}],
"plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]], # optional
"fallbacks": [{ # optional
"model": str,
}],
"cache": { # optional
"ttl": Optional[float],
"type": Literal["exact_match"],
},
"load_balancer": { # optional
# one of: ListAgentsLoadBalancer1
"type": Literal["weight_based"],
"models": [{
"model": str,
"weight": Optional[float],
}],
},
"timeout": { # optional
"call_timeout": float,
},
"cache_control": { # optional
"type": Literal["ephemeral"],
"ttl": Optional[Literal["5m", "1h"]],
},
"prompt_cache_key": Optional[str],
},
"retry": { # optional
"count": Optional[float],
"on_codes": List[float], # optional
},
"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[];
agentPlugins?: {
id: string;
version: 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?: {
// one of: ListAgentsResponseFormatText, ListAgentsResponseFormatJSONObject, ListAgentsResponseFormatAgentsJSONSchema
type: "text" | "json_object" | "json_schema";
jsonSchema: {
description?: string;
name: string;
schema?: any;
strict?: boolean;
};
};
reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
verbosity?: string;
seed?: number;
stop?: string | string[];
thinking?: {
// one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
type: "disabled" | "enabled" | "adaptive";
budgetTokens: number;
thinkingLevel?: "minimal" | "low" | "medium" | "high";
};
temperature?: number;
topP?: number;
topK?: number;
toolChoice?: {
// one of: ListAgentsToolChoice1, ListAgentsToolChoice2
type?: "function";
function: {
name: string;
};
};
parallelToolCalls?: boolean;
modalities?: ("text" | "audio")[];
guardrails?: {
id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string;
executeOn: "input" | "output";
}[];
plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
fallbacks?: {
model: string;
}[];
cache?: {
ttl?: number;
type: "exact_match";
};
loadBalancer?: {
// one of: ListAgentsLoadBalancer1
type: "weight_based";
models: {
model: string;
weight?: number;
}[];
};
timeout?: {
callTimeout: number;
};
cacheControl?: {
type: "ephemeral";
ttl?: "5m" | "1h";
};
promptCacheKey?: string;
};
retry?: {
count?: number;
onCodes?: number[];
};
fallbackModels?: (string | ListAgentsFallbackModelConfiguration2)[];
};
}[];
hasMore: boolean;
}
Show Variant types
Show Variant types
ListAgentsFallbackModelConfiguration2
{
"id": str,
"parameters": { # optional
"name": Optional[str],
"frequency_penalty": Optional[float],
"max_tokens": Optional[int],
"max_completion_tokens": Optional[int],
"presence_penalty": Optional[float],
"response_format": { # optional
# one of: ListAgentsResponseFormatAgentsText, ListAgentsResponseFormatAgentsJSONObject, ListAgentsResponseFormatAgentsResponse200JSONSchema
"type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]],
"json_schema": {
"description": Optional[str],
"name": str,
"schema_": Optional[Any],
"strict": Optional[bool],
},
},
"reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]],
"verbosity": Optional[str],
"seed": Optional[float],
"stop": Union[str, List[str]], # optional
"thinking": { # optional
# one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
"type": Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]],
"budget_tokens": float,
"thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
},
"temperature": Optional[float],
"top_p": Optional[float],
"top_k": Optional[float],
"tool_choice": { # optional
# one of: ListAgentsToolChoiceAgents1, ListAgentsToolChoiceAgents2
"type": Optional[Literal["function"]],
"function": {
"name": str,
},
},
"parallel_tool_calls": Optional[bool],
"modalities": List[Literal["text", "audio"]], # optional
"guardrails": [{ # optional
"id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str],
"execute_on": Literal["input", "output"],
}],
"plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]], # optional
"fallbacks": [{ # optional
"model": str,
}],
"cache": { # optional
"ttl": Optional[float],
"type": Literal["exact_match"],
},
"load_balancer": { # optional
# one of: ListAgentsLoadBalancerAgents1
"type": Literal["weight_based"],
"models": [{
"model": str,
"weight": Optional[float],
}],
},
"timeout": { # optional
"call_timeout": float,
},
"cache_control": { # optional
"type": Literal["ephemeral"],
"ttl": Optional[Literal["5m", "1h"]],
},
"prompt_cache_key": Optional[str],
},
"retry": { # optional
"count": Optional[float],
"on_codes": List[float], # optional
},
}
{
id: string;
parameters?: {
name?: string;
frequencyPenalty?: number;
maxTokens?: number;
maxCompletionTokens?: number;
presencePenalty?: number;
responseFormat?: {
// one of: ListAgentsResponseFormatAgentsText, ListAgentsResponseFormatAgentsJSONObject, ListAgentsResponseFormatAgentsResponse200JSONSchema
type: "text" | "json_object" | "json_schema";
jsonSchema: {
description?: string;
name: string;
schema?: any;
strict?: boolean;
};
};
reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
verbosity?: string;
seed?: number;
stop?: string | string[];
thinking?: {
// one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
type: "disabled" | "enabled" | "adaptive";
budgetTokens: number;
thinkingLevel?: "minimal" | "low" | "medium" | "high";
};
temperature?: number;
topP?: number;
topK?: number;
toolChoice?: {
// one of: ListAgentsToolChoiceAgents1, ListAgentsToolChoiceAgents2
type?: "function";
function: {
name: string;
};
};
parallelToolCalls?: boolean;
modalities?: ("text" | "audio")[];
guardrails?: {
id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string;
executeOn: "input" | "output";
}[];
plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
fallbacks?: {
model: string;
}[];
cache?: {
ttl?: number;
type: "exact_match";
};
loadBalancer?: {
// one of: ListAgentsLoadBalancerAgents1
type: "weight_based";
models: {
model: string;
weight?: number;
}[];
};
timeout?: {
callTimeout: number;
};
cacheControl?: {
type: "ephemeral";
ttl?: "5m" | "1h";
};
promptCacheKey?: string;
};
retry?: {
count?: number;
onCodes?: number[];
};
}
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
}
// orq.agents.delete(agentKey)
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
}
// orq.agents.retrieve(agentKey)
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
"agent_plugins": [{ # optional
"id": str,
"version": str,
}],
"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": { # optional
# one of: RetrieveAgentRequestResponseFormatText, RetrieveAgentRequestResponseFormatJSONObject, RetrieveAgentRequestResponseFormatAgentsJSONSchema
"type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]],
"json_schema": {
"description": Optional[str],
"name": str,
"schema_": Optional[Any],
"strict": Optional[bool],
},
},
"reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]],
"verbosity": Optional[str],
"seed": Optional[float],
"stop": Union[str, List[str]], # optional
"thinking": { # optional
# one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
"type": Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]],
"budget_tokens": float,
"thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
},
"temperature": Optional[float],
"top_p": Optional[float],
"top_k": Optional[float],
"tool_choice": { # optional
# one of: RetrieveAgentRequestToolChoice1, RetrieveAgentRequestToolChoice2
"type": Optional[Literal["function"]],
"function": {
"name": str,
},
},
"parallel_tool_calls": Optional[bool],
"modalities": List[Literal["text", "audio"]], # optional
"guardrails": [{ # optional
"id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str],
"execute_on": Literal["input", "output"],
}],
"plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]], # optional
"fallbacks": [{ # optional
"model": str,
}],
"cache": { # optional
"ttl": Optional[float],
"type": Literal["exact_match"],
},
"load_balancer": { # optional
# one of: RetrieveAgentRequestLoadBalancer1
"type": Literal["weight_based"],
"models": [{
"model": str,
"weight": Optional[float],
}],
},
"timeout": { # optional
"call_timeout": float,
},
"cache_control": { # optional
"type": Literal["ephemeral"],
"ttl": Optional[Literal["5m", "1h"]],
},
"prompt_cache_key": Optional[str],
},
"retry": { # optional
"count": Optional[float],
"on_codes": List[float], # optional
},
"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[];
agentPlugins?: {
id: string;
version: 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?: {
// one of: RetrieveAgentRequestResponseFormatText, RetrieveAgentRequestResponseFormatJSONObject, RetrieveAgentRequestResponseFormatAgentsJSONSchema
type: "text" | "json_object" | "json_schema";
jsonSchema: {
description?: string;
name: string;
schema?: any;
strict?: boolean;
};
};
reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
verbosity?: string;
seed?: number;
stop?: string | string[];
thinking?: {
// one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
type: "disabled" | "enabled" | "adaptive";
budgetTokens: number;
thinkingLevel?: "minimal" | "low" | "medium" | "high";
};
temperature?: number;
topP?: number;
topK?: number;
toolChoice?: {
// one of: RetrieveAgentRequestToolChoice1, RetrieveAgentRequestToolChoice2
type?: "function";
function: {
name: string;
};
};
parallelToolCalls?: boolean;
modalities?: ("text" | "audio")[];
guardrails?: {
id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string;
executeOn: "input" | "output";
}[];
plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
fallbacks?: {
model: string;
}[];
cache?: {
ttl?: number;
type: "exact_match";
};
loadBalancer?: {
// one of: RetrieveAgentRequestLoadBalancer1
type: "weight_based";
models: {
model: string;
weight?: number;
}[];
};
timeout?: {
callTimeout: number;
};
cacheControl?: {
type: "ephemeral";
ttl?: "5m" | "1h";
};
promptCacheKey?: string;
};
retry?: {
count?: number;
onCodes?: number[];
};
fallbackModels?: (string | RetrieveAgentRequestFallbackModelConfiguration2)[];
};
}
Show Variant types
Show Variant types
RetrieveAgentRequestFallbackModelConfiguration2
{
"id": str,
"parameters": { # optional
"name": Optional[str],
"frequency_penalty": Optional[float],
"max_tokens": Optional[int],
"max_completion_tokens": Optional[int],
"presence_penalty": Optional[float],
"response_format": { # optional
# one of: RetrieveAgentRequestResponseFormatAgentsText, RetrieveAgentRequestResponseFormatAgentsJSONObject, RetrieveAgentRequestResponseFormatAgentsResponse200JSONSchema
"type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]],
"json_schema": {
"description": Optional[str],
"name": str,
"schema_": Optional[Any],
"strict": Optional[bool],
},
},
"reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]],
"verbosity": Optional[str],
"seed": Optional[float],
"stop": Union[str, List[str]], # optional
"thinking": { # optional
# one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
"type": Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]],
"budget_tokens": float,
"thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
},
"temperature": Optional[float],
"top_p": Optional[float],
"top_k": Optional[float],
"tool_choice": { # optional
# one of: RetrieveAgentRequestToolChoiceAgents1, RetrieveAgentRequestToolChoiceAgents2
"type": Optional[Literal["function"]],
"function": {
"name": str,
},
},
"parallel_tool_calls": Optional[bool],
"modalities": List[Literal["text", "audio"]], # optional
"guardrails": [{ # optional
"id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str],
"execute_on": Literal["input", "output"],
}],
"plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]], # optional
"fallbacks": [{ # optional
"model": str,
}],
"cache": { # optional
"ttl": Optional[float],
"type": Literal["exact_match"],
},
"load_balancer": { # optional
# one of: RetrieveAgentRequestLoadBalancerAgents1
"type": Literal["weight_based"],
"models": [{
"model": str,
"weight": Optional[float],
}],
},
"timeout": { # optional
"call_timeout": float,
},
"cache_control": { # optional
"type": Literal["ephemeral"],
"ttl": Optional[Literal["5m", "1h"]],
},
"prompt_cache_key": Optional[str],
},
"retry": { # optional
"count": Optional[float],
"on_codes": List[float], # optional
},
}
{
id: string;
parameters?: {
name?: string;
frequencyPenalty?: number;
maxTokens?: number;
maxCompletionTokens?: number;
presencePenalty?: number;
responseFormat?: {
// one of: RetrieveAgentRequestResponseFormatAgentsText, RetrieveAgentRequestResponseFormatAgentsJSONObject, RetrieveAgentRequestResponseFormatAgentsResponse200JSONSchema
type: "text" | "json_object" | "json_schema";
jsonSchema: {
description?: string;
name: string;
schema?: any;
strict?: boolean;
};
};
reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
verbosity?: string;
seed?: number;
stop?: string | string[];
thinking?: {
// one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
type: "disabled" | "enabled" | "adaptive";
budgetTokens: number;
thinkingLevel?: "minimal" | "low" | "medium" | "high";
};
temperature?: number;
topP?: number;
topK?: number;
toolChoice?: {
// one of: RetrieveAgentRequestToolChoiceAgents1, RetrieveAgentRequestToolChoiceAgents2
type?: "function";
function: {
name: string;
};
};
parallelToolCalls?: boolean;
modalities?: ("text" | "audio")[];
guardrails?: {
id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string;
executeOn: "input" | "output";
}[];
plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
fallbacks?: {
model: string;
}[];
cache?: {
ttl?: number;
type: "exact_match";
};
loadBalancer?: {
// one of: RetrieveAgentRequestLoadBalancerAgents1
type: "weight_based";
models: {
model: string;
weight?: number;
}[];
};
timeout?: {
callTimeout: number;
};
cacheControl?: {
type: "ephemeral";
ttl?: "5m" | "1h";
};
promptCacheKey?: string;
};
retry?: {
count?: number;
onCodes?: number[];
};
}
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="openai/gpt-6-astra", fallback_models=[
"<value>",
], settings={
"tools": [
{
"type": "mcp",
"id": "<id>",
"tool_id": "<id>",
"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({
model: "openai/gpt-6-astra",
fallbackModels: [
"<value>",
],
settings: {
tools: [
{
type: "mcp",
id: "<id>",
toolId: "<id>",
requiresApproval: false,
},
],
},
path: "Default",
knowledgeBases: [
{
knowledgeId: "customer-knowledge-base",
},
],
}, "<value>");
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": { # optional
# one of: UpdateAgentModelConfiguration2, str
"id": str, # required
"parameters": { # optional
"name": Optional[str],
"frequency_penalty": Optional[float],
"max_tokens": Optional[int],
"max_completion_tokens": Optional[int],
"presence_penalty": Optional[float],
"response_format": { # optional
# one of: UpdateAgentResponseFormatText, UpdateAgentResponseFormatJSONObject, UpdateAgentResponseFormatJSONSchema
"type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]], # required
"json_schema": { # required (variant-specific)
"description": Optional[str],
"name": str, # required
"schema_": Optional[Any],
"strict": Optional[bool],
},
},
"reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]],
"verbosity": Optional[str],
"seed": Optional[float],
"stop": Union[str, List[str]], # optional
"thinking": { # optional
# one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
"type": Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]], # required
"budget_tokens": float, # required (variant-specific)
"thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
},
"temperature": Optional[float],
"top_p": Optional[float],
"top_k": Optional[float],
"tool_choice": { # optional
# one of: UpdateAgentToolChoice1, UpdateAgentToolChoice2
"type": Optional[Literal["function"]],
"function": { # required (variant-specific)
"name": str, # required
},
},
"parallel_tool_calls": Optional[bool],
"modalities": List[Literal["text", "audio"]], # optional
"guardrails": [{ # optional
"id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str], # required
"execute_on": Literal["input", "output"], # required
}],
"plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]], # optional
"fallbacks": [{ # optional
"model": str, # required
}],
"cache": { # optional
"ttl": Optional[float],
"type": Literal["exact_match"], # required
},
"load_balancer": { # optional
# one of: UpdateAgentLoadBalancer1
"type": Literal["weight_based"], # required
"models": [{ # required
"model": str, # required
"weight": Optional[float],
}],
},
"timeout": { # optional
"call_timeout": float, # required
},
"cache_control": { # optional
"type": Literal["ephemeral"], # required
"ttl": Optional[Literal["5m", "1h"]],
},
"prompt_cache_key": Optional[str],
},
"retry": { # optional
"count": Optional[float],
"on_codes": List[float], # optional
},
},
"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
"agent_plugins": [{ # optional
"id": str, # required
"version": str, # required
}],
"variables": Dict[str, Any], # optional
"engine": Optional[Literal["text", "jinja", "mustache"]],
"version_increment": Optional[Literal["major", "minor", "patch"]],
"version_description": Optional[str],
}
{
key?: string;
displayName?: string;
projectId?: string;
role?: string;
description?: string;
instructions?: string;
systemPrompt?: string;
model?: {
// one of: UpdateAgentModelConfiguration2, string
id: string; // required
parameters?: {
name?: string;
frequencyPenalty?: number;
maxTokens?: number;
maxCompletionTokens?: number;
presencePenalty?: number;
responseFormat?: {
// one of: UpdateAgentResponseFormatText, UpdateAgentResponseFormatJSONObject, UpdateAgentResponseFormatJSONSchema
type: "text" | "json_object" | "json_schema"; // required
jsonSchema: { // required (variant-specific)
description?: string;
name: string; // required
schema?: any;
strict?: boolean;
};
};
reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
verbosity?: string;
seed?: number;
stop?: string | string[];
thinking?: {
// one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
type: "disabled" | "enabled" | "adaptive"; // required
budgetTokens: number; // required (variant-specific)
thinkingLevel?: "minimal" | "low" | "medium" | "high";
};
temperature?: number;
topP?: number;
topK?: number;
toolChoice?: {
// one of: UpdateAgentToolChoice1, UpdateAgentToolChoice2
type?: "function";
function: { // required (variant-specific)
name: string; // required
};
};
parallelToolCalls?: boolean;
modalities?: ("text" | "audio")[];
guardrails?: {
id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string; // required
executeOn: "input" | "output"; // required
}[];
plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
fallbacks?: {
model: string; // required
}[];
cache?: {
ttl?: number;
type: "exact_match"; // required
};
loadBalancer?: {
// one of: UpdateAgentLoadBalancer1
type: "weight_based"; // required
models: { // required
model: string; // required
weight?: number;
}[];
};
timeout?: {
callTimeout: number; // required
};
cacheControl?: {
type: "ephemeral"; // required
ttl?: "5m" | "1h";
};
promptCacheKey?: string;
};
retry?: {
count?: number;
onCodes?: number[];
};
};
fallbackModels?: (string | 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[];
agentPlugins?: {
id: string; // required
version: string; // required
}[];
variables?: Record<string, any>;
engine?: "text" | "jinja" | "mustache";
versionIncrement?: "major" | "minor" | "patch";
versionDescription?: string;
// agentKey is passed as an argument beyond the request object
}
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
"agent_plugins": [{ # optional
"id": str,
"version": str,
}],
"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": { # optional
# one of: UpdateAgentResponseFormatAgentsResponseText, UpdateAgentResponseFormatAgentsResponseJSONObject, UpdateAgentResponseFormatAgentsResponse200JSONSchema
"type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]],
"json_schema": {
"description": Optional[str],
"name": str,
"schema_": Optional[Any],
"strict": Optional[bool],
},
},
"reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]],
"verbosity": Optional[str],
"seed": Optional[float],
"stop": Union[str, List[str]], # optional
"thinking": { # optional
# one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
"type": Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]],
"budget_tokens": float,
"thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
},
"temperature": Optional[float],
"top_p": Optional[float],
"top_k": Optional[float],
"tool_choice": { # optional
# one of: UpdateAgentToolChoiceAgentsResponse1, UpdateAgentToolChoiceAgentsResponse2
"type": Optional[Literal["function"]],
"function": {
"name": str,
},
},
"parallel_tool_calls": Optional[bool],
"modalities": List[Literal["text", "audio"]], # optional
"guardrails": [{ # optional
"id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str],
"execute_on": Literal["input", "output"],
}],
"plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]], # optional
"fallbacks": [{ # optional
"model": str,
}],
"cache": { # optional
"ttl": Optional[float],
"type": Literal["exact_match"],
},
"load_balancer": { # optional
# one of: UpdateAgentLoadBalancerAgentsResponse1
"type": Literal["weight_based"],
"models": [{
"model": str,
"weight": Optional[float],
}],
},
"timeout": { # optional
"call_timeout": float,
},
"cache_control": { # optional
"type": Literal["ephemeral"],
"ttl": Optional[Literal["5m", "1h"]],
},
"prompt_cache_key": Optional[str],
},
"retry": { # optional
"count": Optional[float],
"on_codes": List[float], # optional
},
"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[];
agentPlugins?: {
id: string;
version: 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?: {
// one of: UpdateAgentResponseFormatAgentsResponseText, UpdateAgentResponseFormatAgentsResponseJSONObject, UpdateAgentResponseFormatAgentsResponse200JSONSchema
type: "text" | "json_object" | "json_schema";
jsonSchema: {
description?: string;
name: string;
schema?: any;
strict?: boolean;
};
};
reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
verbosity?: string;
seed?: number;
stop?: string | string[];
thinking?: {
// one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
type: "disabled" | "enabled" | "adaptive";
budgetTokens: number;
thinkingLevel?: "minimal" | "low" | "medium" | "high";
};
temperature?: number;
topP?: number;
topK?: number;
toolChoice?: {
// one of: UpdateAgentToolChoiceAgentsResponse1, UpdateAgentToolChoiceAgentsResponse2
type?: "function";
function: {
name: string;
};
};
parallelToolCalls?: boolean;
modalities?: ("text" | "audio")[];
guardrails?: {
id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string;
executeOn: "input" | "output";
}[];
plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
fallbacks?: {
model: string;
}[];
cache?: {
ttl?: number;
type: "exact_match";
};
loadBalancer?: {
// one of: UpdateAgentLoadBalancerAgentsResponse1
type: "weight_based";
models: {
model: string;
weight?: number;
}[];
};
timeout?: {
callTimeout: number;
};
cacheControl?: {
type: "ephemeral";
ttl?: "5m" | "1h";
};
promptCacheKey?: string;
};
retry?: {
count?: number;
onCodes?: number[];
};
fallbackModels?: (string | UpdateAgentFallbackModelConfigurationAgents2)[];
};
}
Show Variant types
Show Variant types
UpdateAgentFallbackModelConfiguration2
{
"id": str,
"parameters": { # optional
"name": Optional[str],
"frequency_penalty": Optional[float],
"max_tokens": Optional[int],
"max_completion_tokens": Optional[int],
"presence_penalty": Optional[float],
"response_format": { # optional
# one of: UpdateAgentResponseFormatAgentsText, UpdateAgentResponseFormatAgentsJSONObject, UpdateAgentResponseFormatAgentsRequestJSONSchema
"type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]],
"json_schema": {
"description": Optional[str],
"name": str,
"schema_": Optional[Any],
"strict": Optional[bool],
},
},
"reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]],
"verbosity": Optional[str],
"seed": Optional[float],
"stop": Union[str, List[str]], # optional
"thinking": { # optional
# one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
"type": Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]],
"budget_tokens": float,
"thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
},
"temperature": Optional[float],
"top_p": Optional[float],
"top_k": Optional[float],
"tool_choice": { # optional
# one of: UpdateAgentToolChoiceAgents1, UpdateAgentToolChoiceAgents2
"type": Optional[Literal["function"]],
"function": {
"name": str,
},
},
"parallel_tool_calls": Optional[bool],
"modalities": List[Literal["text", "audio"]], # optional
"guardrails": [{ # optional
"id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str],
"execute_on": Literal["input", "output"],
}],
"plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]], # optional
"fallbacks": [{ # optional
"model": str,
}],
"cache": { # optional
"ttl": Optional[float],
"type": Literal["exact_match"],
},
"load_balancer": { # optional
# one of: UpdateAgentLoadBalancerAgents1
"type": Literal["weight_based"],
"models": [{
"model": str,
"weight": Optional[float],
}],
},
"timeout": { # optional
"call_timeout": float,
},
"cache_control": { # optional
"type": Literal["ephemeral"],
"ttl": Optional[Literal["5m", "1h"]],
},
"prompt_cache_key": Optional[str],
},
"retry": { # optional
"count": Optional[float],
"on_codes": List[float], # optional
},
}
{
id: string;
parameters?: {
name?: string;
frequencyPenalty?: number;
maxTokens?: number;
maxCompletionTokens?: number;
presencePenalty?: number;
responseFormat?: {
// one of: UpdateAgentResponseFormatAgentsText, UpdateAgentResponseFormatAgentsJSONObject, UpdateAgentResponseFormatAgentsRequestJSONSchema
type: "text" | "json_object" | "json_schema";
jsonSchema: {
description?: string;
name: string;
schema?: any;
strict?: boolean;
};
};
reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
verbosity?: string;
seed?: number;
stop?: string | string[];
thinking?: {
// one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
type: "disabled" | "enabled" | "adaptive";
budgetTokens: number;
thinkingLevel?: "minimal" | "low" | "medium" | "high";
};
temperature?: number;
topP?: number;
topK?: number;
toolChoice?: {
// one of: UpdateAgentToolChoiceAgents1, UpdateAgentToolChoiceAgents2
type?: "function";
function: {
name: string;
};
};
parallelToolCalls?: boolean;
modalities?: ("text" | "audio")[];
guardrails?: {
id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string;
executeOn: "input" | "output";
}[];
plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
fallbacks?: {
model: string;
}[];
cache?: {
ttl?: number;
type: "exact_match";
};
loadBalancer?: {
// one of: UpdateAgentLoadBalancerAgents1
type: "weight_based";
models: {
model: string;
weight?: number;
}[];
};
timeout?: {
callTimeout: number;
};
cacheControl?: {
type: "ephemeral";
ttl?: "5m" | "1h";
};
promptCacheKey?: string;
};
retry?: {
count?: number;
onCodes?: number[];
};
}
UpdateAgentFallbackModelConfigurationAgents2
{
"id": str,
"parameters": { # optional
"name": Optional[str],
"frequency_penalty": Optional[float],
"max_tokens": Optional[int],
"max_completion_tokens": Optional[int],
"presence_penalty": Optional[float],
"response_format": { # optional
# one of: UpdateAgentResponseFormatAgentsResponse200Text, UpdateAgentResponseFormatAgentsResponse200JSONObject, UpdateAgentResponseFormatAgentsResponse200ApplicationJSONResponseBodyJSONSchema
"type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]],
"json_schema": {
"description": Optional[str],
"name": str,
"schema_": Optional[Any],
"strict": Optional[bool],
},
},
"reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]],
"verbosity": Optional[str],
"seed": Optional[float],
"stop": Union[str, List[str]], # optional
"thinking": { # optional
# one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
"type": Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]],
"budget_tokens": float,
"thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
},
"temperature": Optional[float],
"top_p": Optional[float],
"top_k": Optional[float],
"tool_choice": { # optional
# one of: UpdateAgentToolChoiceAgentsResponse2001, UpdateAgentToolChoiceAgentsResponse2002
"type": Optional[Literal["function"]],
"function": {
"name": str,
},
},
"parallel_tool_calls": Optional[bool],
"modalities": List[Literal["text", "audio"]], # optional
"guardrails": [{ # optional
"id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str],
"execute_on": Literal["input", "output"],
}],
"plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]], # optional
"fallbacks": [{ # optional
"model": str,
}],
"cache": { # optional
"ttl": Optional[float],
"type": Literal["exact_match"],
},
"load_balancer": { # optional
# one of: UpdateAgentLoadBalancerAgentsResponse2001
"type": Literal["weight_based"],
"models": [{
"model": str,
"weight": Optional[float],
}],
},
"timeout": { # optional
"call_timeout": float,
},
"cache_control": { # optional
"type": Literal["ephemeral"],
"ttl": Optional[Literal["5m", "1h"]],
},
"prompt_cache_key": Optional[str],
},
"retry": { # optional
"count": Optional[float],
"on_codes": List[float], # optional
},
}
{
id: string;
parameters?: {
name?: string;
frequencyPenalty?: number;
maxTokens?: number;
maxCompletionTokens?: number;
presencePenalty?: number;
responseFormat?: {
// one of: UpdateAgentResponseFormatAgentsResponse200Text, UpdateAgentResponseFormatAgentsResponse200JSONObject, UpdateAgentResponseFormatAgentsResponse200ApplicationJSONResponseBodyJSONSchema
type: "text" | "json_object" | "json_schema";
jsonSchema: {
description?: string;
name: string;
schema?: any;
strict?: boolean;
};
};
reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
verbosity?: string;
seed?: number;
stop?: string | string[];
thinking?: {
// one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
type: "disabled" | "enabled" | "adaptive";
budgetTokens: number;
thinkingLevel?: "minimal" | "low" | "medium" | "high";
};
temperature?: number;
topP?: number;
topK?: number;
toolChoice?: {
// one of: UpdateAgentToolChoiceAgentsResponse2001, UpdateAgentToolChoiceAgentsResponse2002
type?: "function";
function: {
name: string;
};
};
parallelToolCalls?: boolean;
modalities?: ("text" | "audio")[];
guardrails?: {
id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string;
executeOn: "input" | "output";
}[];
plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
fallbacks?: {
model: string;
}[];
cache?: {
ttl?: number;
type: "exact_match";
};
loadBalancer?: {
// one of: UpdateAgentLoadBalancerAgentsResponse2001
type: "weight_based";
models: {
model: string;
weight?: number;
}[];
};
timeout?: {
callTimeout: number;
};
cacheControl?: {
type: "ephemeral";
ttl?: "5m" | "1h";
};
promptCacheKey?: string;
};
retry?: {
count?: number;
onCodes?: number[];
};
}
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": [{"kind": "text", "text": "What is the weather in Paris?"}],
}, identity={
"id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
"display_name": "Jane Doe",
"email": "jane.doe@example.com",
"metadata": [
{
"department": "Engineering",
"role": "Senior Developer",
},
],
"logo_url": "https://example.com/avatars/jane-doe.jpg",
"tags": [
"hr",
"engineering",
],
}, thread={
"id": "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
"tags": [
"customer-support",
"priority-high",
],
})
# Handle response
print(res)
import { Orq } from "@orq-ai/node";
const orq = new Orq({
apiKey: process.env["ORQ_API_KEY"] ?? "",
});
async function run() {
const result = await orq.agents.invoke("<key>", {
message: {
role: "user",
parts: [{ kind: "text", text: "What is the weather in Paris?" }],
},
identity: {
id: "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
displayName: "Jane Doe",
email: "jane.doe@example.com",
metadata: [
{
"department": "Engineering",
"role": "Senior Developer",
},
],
logoUrl: "https://example.com/avatars/jane-doe.jpg",
tags: [
"hr",
"engineering",
],
},
thread: {
id: "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
tags: [
"customer-support",
"priority-high",
],
},
});
console.log(result);
}
run();
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],
},
}
{
taskId?: string;
message: { // required
messageId?: string;
role: RoleUserMessage | RoleToolMessage; // required
parts: (TextPart | FilePart | ToolResultPart | ErrorPart)[]; // required
};
variables?: Record<string, any>;
identity?: {
id: string; // required
displayName?: string;
email?: string;
metadata?: Record<string, any>[];
logoUrl?: string;
tags?: string[];
};
contact?: {
id: string; // required
displayName?: string;
email?: string;
metadata?: Record<string, any>[];
logoUrl?: string;
tags?: string[];
};
thread?: {
id: string; // required
tags?: string[];
};
memory?: {
entityId: string; // required
};
metadata?: Record<string, any>;
engine?: "text" | "jinja" | "mustache";
configuration?: {
blocking?: boolean;
};
// key is passed as an argument beyond the request object
}
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="openai/gpt-6-astra", role="<value>", instructions="<value>", message={
"role": "user",
"parts": [
{
"kind": "file",
"file": {
"uri": "https://example.com/report.pdf",
},
},
],
}, path="Default", settings={}, fallback_models=[
"<value>",
], identity={
"id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
"display_name": "Jane Doe",
"email": "jane.doe@example.com",
"metadata": [
{
"department": "Engineering",
"role": "Senior Developer",
},
],
"logo_url": "https://example.com/avatars/jane-doe.jpg",
"tags": [
"hr",
"engineering",
],
}, thread={
"id": "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
"tags": [
"customer-support",
"priority-high",
],
}, knowledge_bases=[
{
"knowledge_id": "customer-knowledge-base",
},
], engine="text")
# 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: "openai/gpt-6-astra",
fallbackModels: [
"<value>",
],
role: "<value>",
instructions: "<value>",
message: {
role: "user",
parts: [
{
kind: "file",
file: {
uri: "https://example.com/report.pdf",
},
},
],
},
identity: {
id: "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
displayName: "Jane Doe",
email: "jane.doe@example.com",
metadata: [
{
"department": "Engineering",
"role": "Senior Developer",
},
],
logoUrl: "https://example.com/avatars/jane-doe.jpg",
tags: [
"hr",
"engineering",
],
},
thread: {
id: "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
tags: [
"customer-support",
"priority-high",
],
},
path: "Default",
knowledgeBases: [
{
knowledgeId: "customer-knowledge-base",
},
],
settings: {},
});
console.log(result);
}
run();
Show Parameters
Show Parameters
{
"key": str, # required
"model": { # required
# one of: RunAgentModelConfiguration2, str
"id": str, # required
"parameters": { # optional
"name": Optional[str],
"frequency_penalty": Optional[float],
"max_tokens": Optional[int],
"max_completion_tokens": Optional[int],
"presence_penalty": Optional[float],
"response_format": { # optional
# one of: RunAgentResponseFormatText, RunAgentResponseFormatJSONObject, RunAgentResponseFormatJSONSchema
"type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]], # required
"json_schema": { # required (variant-specific)
"description": Optional[str],
"name": str, # required
"schema_": Optional[Any],
"strict": Optional[bool],
},
},
"reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]],
"verbosity": Optional[str],
"seed": Optional[float],
"stop": Union[str, List[str]], # optional
"thinking": { # optional
# one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
"type": Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]], # required
"budget_tokens": float, # required (variant-specific)
"thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
},
"temperature": Optional[float],
"top_p": Optional[float],
"top_k": Optional[float],
"tool_choice": { # optional
# one of: RunAgentToolChoice1, RunAgentToolChoice2
"type": Optional[Literal["function"]],
"function": { # required (variant-specific)
"name": str, # required
},
},
"parallel_tool_calls": Optional[bool],
"modalities": List[Literal["text", "audio"]], # optional
"guardrails": [{ # optional
"id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str], # required
"execute_on": Literal["input", "output"], # required
}],
"plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]], # optional
"fallbacks": [{ # optional
"model": str, # required
}],
"cache": { # optional
"ttl": Optional[float],
"type": Literal["exact_match"], # required
},
"load_balancer": { # optional
# one of: RunAgentLoadBalancer1
"type": Literal["weight_based"], # required
"models": [{ # required
"model": str, # required
"weight": Optional[float],
}],
},
"timeout": { # optional
"call_timeout": float, # required
},
"cache_control": { # optional
"type": Literal["ephemeral"], # required
"ttl": Optional[Literal["5m", "1h"]],
},
"prompt_cache_key": Optional[str],
},
"retry": { # optional
"count": Optional[float],
"on_codes": List[float], # optional
},
},
"role": str, # required
"instructions": str, # required
"message": { # required
"message_id": Optional[str],
"role": Union[RunAgentRoleUserMessage, RunAgentRoleToolMessage], # required
"parts": List[Union[TextPart, FilePart, ToolResultPart, ErrorPart]], # required
},
"path": str, # required
"settings": { # required
"tools": List[Union[GoogleSearchToolInput, WebScraperToolInput, CallSubAgentToolInput, RetrieveAgentsToolInput, QueryMemoryStoreToolInput, WriteMemoryStoreToolInput, RetrieveMemoryStoresToolInput, DeleteMemoryDocumentToolInput, RetrieveKnowledgeBasesToolInput, QueryKnowledgeBaseToolInput, CurrentDateToolInput, AdvisorToolInput, SidekickToolInput, CodeInterpreterToolInput, FileSystemToolInput, HTTPToolRun, CodeToolRun, FunctionToolRun, JSONSchemaToolRun, MCPToolRun]], # optional
"tool_approval_required": Optional[Literal["all", "respect_tool", "none"]],
"max_iterations": Optional[int],
"max_execution_time": Optional[int],
"max_cost": Optional[float],
"chat_exposed": Optional[bool],
"evaluators": [{ # optional
"id": str, # required
"sample_rate": Optional[float],
"execute_on": Literal["input", "output"], # required
}],
"guardrails": [{ # optional
"id": str, # required
"sample_rate": Optional[float],
"execute_on": Literal["input", "output"], # required
}],
},
"task_id": Optional[str],
"fallback_models": List[Union[str, RunAgentFallbackModelConfiguration2]], # optional
"variables": Dict[str, Any], # optional
"identity": { # optional
"id": str, # required
"display_name": Optional[str],
"email": Optional[str],
"metadata": List[Dict[str, Any]], # optional
"logo_url": Optional[str],
"tags": List[str], # optional
},
"contact": { # optional
"id": str, # required
"display_name": Optional[str],
"email": Optional[str],
"metadata": List[Dict[str, Any]], # optional
"logo_url": Optional[str],
"tags": List[str], # optional
},
"thread": { # optional
"id": str, # required
"tags": List[str], # optional
},
"memory": { # optional
"entity_id": str, # required
},
"description": Optional[str],
"system_prompt": Optional[str],
"memory_stores": List[str], # optional
"knowledge_bases": [{ # optional
"knowledge_id": str, # required
}],
"team_of_agents": [{ # optional
"key": str, # required
"role": Optional[str],
}],
"metadata": Dict[str, Any], # optional
"engine": Optional[Literal["text", "jinja", "mustache"]],
}
{
key: string; // required
taskId?: string;
model: { // required
// one of: RunAgentModelConfiguration2, string
id: string; // required
parameters?: {
name?: string;
frequencyPenalty?: number;
maxTokens?: number;
maxCompletionTokens?: number;
presencePenalty?: number;
responseFormat?: {
// one of: RunAgentResponseFormatText, RunAgentResponseFormatJSONObject, RunAgentResponseFormatJSONSchema
type: "text" | "json_object" | "json_schema"; // required
jsonSchema: { // required (variant-specific)
description?: string;
name: string; // required
schema?: any;
strict?: boolean;
};
};
reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
verbosity?: string;
seed?: number;
stop?: string | string[];
thinking?: {
// one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
type: "disabled" | "enabled" | "adaptive"; // required
budgetTokens: number; // required (variant-specific)
thinkingLevel?: "minimal" | "low" | "medium" | "high";
};
temperature?: number;
topP?: number;
topK?: number;
toolChoice?: {
// one of: RunAgentToolChoice1, RunAgentToolChoice2
type?: "function";
function: { // required (variant-specific)
name: string; // required
};
};
parallelToolCalls?: boolean;
modalities?: ("text" | "audio")[];
guardrails?: {
id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string; // required
executeOn: "input" | "output"; // required
}[];
plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
fallbacks?: {
model: string; // required
}[];
cache?: {
ttl?: number;
type: "exact_match"; // required
};
loadBalancer?: {
// one of: RunAgentLoadBalancer1
type: "weight_based"; // required
models: { // required
model: string; // required
weight?: number;
}[];
};
timeout?: {
callTimeout: number; // required
};
cacheControl?: {
type: "ephemeral"; // required
ttl?: "5m" | "1h";
};
promptCacheKey?: string;
};
retry?: {
count?: number;
onCodes?: number[];
};
};
fallbackModels?: (string | RunAgentFallbackModelConfiguration2)[];
role: string; // required
instructions: string; // required
message: { // required
messageId?: string;
role: RunAgentRoleUserMessage | RunAgentRoleToolMessage; // required
parts: (TextPart | FilePart | ToolResultPart | ErrorPart)[]; // required
};
variables?: Record<string, any>;
identity?: {
id: string; // required
displayName?: string;
email?: string;
metadata?: Record<string, any>[];
logoUrl?: string;
tags?: string[];
};
contact?: {
id: string; // required
displayName?: string;
email?: string;
metadata?: Record<string, any>[];
logoUrl?: string;
tags?: string[];
};
thread?: {
id: string; // required
tags?: string[];
};
memory?: {
entityId: string; // required
};
path: string; // required
description?: string;
systemPrompt?: string;
memoryStores?: string[];
knowledgeBases?: {
knowledgeId: string; // required
}[];
teamOfAgents?: {
key: string; // required
role?: string;
}[];
settings: { // required
tools?: (GoogleSearchToolInput | WebScraperToolInput | CallSubAgentToolInput | RetrieveAgentsToolInput | QueryMemoryStoreToolInput | WriteMemoryStoreToolInput | RetrieveMemoryStoresToolInput | DeleteMemoryDocumentToolInput | RetrieveKnowledgeBasesToolInput | QueryKnowledgeBaseToolInput | CurrentDateToolInput | AdvisorToolInput | SidekickToolInput | CodeInterpreterToolInput | FileSystemToolInput | HTTPToolRun | CodeToolRun | FunctionToolRun | JSONSchemaToolRun | MCPToolRun)[];
toolApprovalRequired?: "all" | "respect_tool" | "none";
maxIterations?: number;
maxExecutionTime?: number;
maxCost?: number;
chatExposed?: boolean;
evaluators?: {
id: string; // required
sampleRate?: number;
executeOn: "input" | "output"; // required
}[];
guardrails?: {
id: string; // required
sampleRate?: number;
executeOn: "input" | "output"; // required
}[];
};
metadata?: Record<string, any>;
engine?: "text" | "jinja" | "mustache";
}
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>;
}
Show Variant types
Show Variant types
RunAgentFallbackModelConfiguration2
{
"id": str,
"parameters": { # optional
"name": Optional[str],
"frequency_penalty": Optional[float],
"max_tokens": Optional[int],
"max_completion_tokens": Optional[int],
"presence_penalty": Optional[float],
"response_format": { # optional
# one of: RunAgentResponseFormatAgentsText, RunAgentResponseFormatAgentsJSONObject, RunAgentResponseFormatAgentsRequestJSONSchema
"type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]],
"json_schema": {
"description": Optional[str],
"name": str,
"schema_": Optional[Any],
"strict": Optional[bool],
},
},
"reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]],
"verbosity": Optional[str],
"seed": Optional[float],
"stop": Union[str, List[str]], # optional
"thinking": { # optional
# one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
"type": Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]],
"budget_tokens": float,
"thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
},
"temperature": Optional[float],
"top_p": Optional[float],
"top_k": Optional[float],
"tool_choice": { # optional
# one of: RunAgentToolChoiceAgents1, RunAgentToolChoiceAgents2
"type": Optional[Literal["function"]],
"function": {
"name": str,
},
},
"parallel_tool_calls": Optional[bool],
"modalities": List[Literal["text", "audio"]], # optional
"guardrails": [{ # optional
"id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str],
"execute_on": Literal["input", "output"],
}],
"plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]], # optional
"fallbacks": [{ # optional
"model": str,
}],
"cache": { # optional
"ttl": Optional[float],
"type": Literal["exact_match"],
},
"load_balancer": { # optional
# one of: RunAgentLoadBalancerAgents1
"type": Literal["weight_based"],
"models": [{
"model": str,
"weight": Optional[float],
}],
},
"timeout": { # optional
"call_timeout": float,
},
"cache_control": { # optional
"type": Literal["ephemeral"],
"ttl": Optional[Literal["5m", "1h"]],
},
"prompt_cache_key": Optional[str],
},
"retry": { # optional
"count": Optional[float],
"on_codes": List[float], # optional
},
}
{
id: string;
parameters?: {
name?: string;
frequencyPenalty?: number;
maxTokens?: number;
maxCompletionTokens?: number;
presencePenalty?: number;
responseFormat?: {
// one of: RunAgentResponseFormatAgentsText, RunAgentResponseFormatAgentsJSONObject, RunAgentResponseFormatAgentsRequestJSONSchema
type: "text" | "json_object" | "json_schema";
jsonSchema: {
description?: string;
name: string;
schema?: any;
strict?: boolean;
};
};
reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
verbosity?: string;
seed?: number;
stop?: string | string[];
thinking?: {
// one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
type: "disabled" | "enabled" | "adaptive";
budgetTokens: number;
thinkingLevel?: "minimal" | "low" | "medium" | "high";
};
temperature?: number;
topP?: number;
topK?: number;
toolChoice?: {
// one of: RunAgentToolChoiceAgents1, RunAgentToolChoiceAgents2
type?: "function";
function: {
name: string;
};
};
parallelToolCalls?: boolean;
modalities?: ("text" | "audio")[];
guardrails?: {
id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string;
executeOn: "input" | "output";
}[];
plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
fallbacks?: {
model: string;
}[];
cache?: {
ttl?: number;
type: "exact_match";
};
loadBalancer?: {
// one of: RunAgentLoadBalancerAgents1
type: "weight_based";
models: {
model: string;
weight?: number;
}[];
};
timeout?: {
callTimeout: number;
};
cacheControl?: {
type: "ephemeral";
ttl?: "5m" | "1h";
};
promptCacheKey?: string;
};
retry?: {
count?: number;
onCodes?: number[];
};
}
Stream Run [deprecated]
Run an agent with streaming via SSE, combining inline configuration with real-time updates including messages, tool executions, and status.from orq_ai_sdk import Orq
import os
with Orq(
api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:
res = orq.agents.stream_run(key="<key>", model="openai/gpt-6-astra", role="<value>", instructions="<value>", message={
"role": "user",
"parts": [
{
"kind": "file",
"file": {
"uri": "https://example.com/report.pdf",
},
},
],
}, path="Default", settings={}, fallback_models=[
"<value>",
], identity={
"id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
"display_name": "Jane Doe",
"email": "jane.doe@example.com",
"metadata": [
{
"department": "Engineering",
"role": "Senior Developer",
},
],
"logo_url": "https://example.com/avatars/jane-doe.jpg",
"tags": [
"hr",
"engineering",
],
}, thread={
"id": "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
"tags": [
"customer-support",
"priority-high",
],
}, knowledge_bases=[
{
"knowledge_id": "customer-knowledge-base",
},
], engine="text")
with res as event_stream:
for event in event_stream:
# handle event
print(event, flush=True)
import { Orq } from "@orq-ai/node";
const orq = new Orq({
apiKey: process.env["ORQ_API_KEY"] ?? "",
});
async function run() {
const result = await orq.agents.streamRun({
key: "<key>",
model: "openai/gpt-6-astra",
fallbackModels: [
"<value>",
],
role: "<value>",
instructions: "<value>",
message: {
role: "user",
parts: [
{
kind: "file",
file: {
uri: "https://example.com/report.pdf",
},
},
],
},
identity: {
id: "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
displayName: "Jane Doe",
email: "jane.doe@example.com",
metadata: [
{
"department": "Engineering",
"role": "Senior Developer",
},
],
logoUrl: "https://example.com/avatars/jane-doe.jpg",
tags: [
"hr",
"engineering",
],
},
thread: {
id: "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
tags: [
"customer-support",
"priority-high",
],
},
path: "Default",
knowledgeBases: [
{
knowledgeId: "customer-knowledge-base",
},
],
settings: {},
});
for await (const event of result) {
console.log(event);
}
}
run();
Show Parameters
Show Parameters
{
"key": str, # required
"model": { # required
# one of: StreamRunAgentModelConfiguration2, str
"id": str, # required
"parameters": { # optional
"name": Optional[str],
"frequency_penalty": Optional[float],
"max_tokens": Optional[int],
"max_completion_tokens": Optional[int],
"presence_penalty": Optional[float],
"response_format": { # optional
# one of: StreamRunAgentResponseFormatText, StreamRunAgentResponseFormatJSONObject, StreamRunAgentResponseFormatJSONSchema
"type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]], # required
"json_schema": { # required (variant-specific)
"description": Optional[str],
"name": str, # required
"schema_": Optional[Any],
"strict": Optional[bool],
},
},
"reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]],
"verbosity": Optional[str],
"seed": Optional[float],
"stop": Union[str, List[str]], # optional
"thinking": { # optional
# one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
"type": Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]], # required
"budget_tokens": float, # required (variant-specific)
"thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
},
"temperature": Optional[float],
"top_p": Optional[float],
"top_k": Optional[float],
"tool_choice": { # optional
# one of: StreamRunAgentToolChoice1, StreamRunAgentToolChoice2
"type": Optional[Literal["function"]],
"function": { # required (variant-specific)
"name": str, # required
},
},
"parallel_tool_calls": Optional[bool],
"modalities": List[Literal["text", "audio"]], # optional
"guardrails": [{ # optional
"id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str], # required
"execute_on": Literal["input", "output"], # required
}],
"plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]], # optional
"fallbacks": [{ # optional
"model": str, # required
}],
"cache": { # optional
"ttl": Optional[float],
"type": Literal["exact_match"], # required
},
"load_balancer": { # optional
# one of: StreamRunAgentLoadBalancer1
"type": Literal["weight_based"], # required
"models": [{ # required
"model": str, # required
"weight": Optional[float],
}],
},
"timeout": { # optional
"call_timeout": float, # required
},
"cache_control": { # optional
"type": Literal["ephemeral"], # required
"ttl": Optional[Literal["5m", "1h"]],
},
"prompt_cache_key": Optional[str],
},
"retry": { # optional
"count": Optional[float],
"on_codes": List[float], # optional
},
},
"role": str, # required
"instructions": str, # required
"message": { # required
"message_id": Optional[str],
"role": Union[StreamRunAgentRoleUserMessage, StreamRunAgentRoleToolMessage], # required
"parts": List[Union[TextPart, FilePart, ToolResultPart, ErrorPart]], # required
},
"path": str, # required
"settings": { # required
"tools": List[Union[GoogleSearchToolInput, WebScraperToolInput, CallSubAgentToolInput, RetrieveAgentsToolInput, QueryMemoryStoreToolInput, WriteMemoryStoreToolInput, RetrieveMemoryStoresToolInput, DeleteMemoryDocumentToolInput, RetrieveKnowledgeBasesToolInput, QueryKnowledgeBaseToolInput, CurrentDateToolInput, AdvisorToolInput, SidekickToolInput, CodeInterpreterToolInput, FileSystemToolInput, AgentToolInputRunHTTPToolRun, AgentToolInputRunCodeToolRun, AgentToolInputRunFunctionToolRun, AgentToolInputRunJSONSchemaToolRun, AgentToolInputRunMCPToolRun]], # optional
"tool_approval_required": Optional[Literal["all", "respect_tool", "none"]],
"max_iterations": Optional[int],
"max_execution_time": Optional[int],
"max_cost": Optional[float],
"chat_exposed": Optional[bool],
"evaluators": [{ # optional
"id": str, # required
"sample_rate": Optional[float],
"execute_on": Literal["input", "output"], # required
}],
"guardrails": [{ # optional
"id": str, # required
"sample_rate": Optional[float],
"execute_on": Literal["input", "output"], # required
}],
},
"task_id": Optional[str],
"fallback_models": List[Union[str, StreamRunAgentFallbackModelConfiguration2]], # optional
"variables": Dict[str, Any], # optional
"identity": { # optional
"id": str, # required
"display_name": Optional[str],
"email": Optional[str],
"metadata": List[Dict[str, Any]], # optional
"logo_url": Optional[str],
"tags": List[str], # optional
},
"contact": { # optional
"id": str, # required
"display_name": Optional[str],
"email": Optional[str],
"metadata": List[Dict[str, Any]], # optional
"logo_url": Optional[str],
"tags": List[str], # optional
},
"thread": { # optional
"id": str, # required
"tags": List[str], # optional
},
"memory": { # optional
"entity_id": str, # required
},
"description": Optional[str],
"system_prompt": Optional[str],
"memory_stores": List[str], # optional
"knowledge_bases": [{ # optional
"knowledge_id": str, # required
}],
"team_of_agents": [{ # optional
"key": str, # required
"role": Optional[str],
}],
"metadata": Dict[str, Any], # optional
"engine": Optional[Literal["text", "jinja", "mustache"]],
"stream_timeout_seconds": Optional[float],
}
{
key: string; // required
taskId?: string;
model: { // required
// one of: StreamRunAgentModelConfiguration2, string
id: string; // required
parameters?: {
name?: string;
frequencyPenalty?: number;
maxTokens?: number;
maxCompletionTokens?: number;
presencePenalty?: number;
responseFormat?: {
// one of: StreamRunAgentResponseFormatText, StreamRunAgentResponseFormatJSONObject, StreamRunAgentResponseFormatJSONSchema
type: "text" | "json_object" | "json_schema"; // required
jsonSchema: { // required (variant-specific)
description?: string;
name: string; // required
schema?: any;
strict?: boolean;
};
};
reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
verbosity?: string;
seed?: number;
stop?: string | string[];
thinking?: {
// one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
type: "disabled" | "enabled" | "adaptive"; // required
budgetTokens: number; // required (variant-specific)
thinkingLevel?: "minimal" | "low" | "medium" | "high";
};
temperature?: number;
topP?: number;
topK?: number;
toolChoice?: {
// one of: StreamRunAgentToolChoice1, StreamRunAgentToolChoice2
type?: "function";
function: { // required (variant-specific)
name: string; // required
};
};
parallelToolCalls?: boolean;
modalities?: ("text" | "audio")[];
guardrails?: {
id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string; // required
executeOn: "input" | "output"; // required
}[];
plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
fallbacks?: {
model: string; // required
}[];
cache?: {
ttl?: number;
type: "exact_match"; // required
};
loadBalancer?: {
// one of: StreamRunAgentLoadBalancer1
type: "weight_based"; // required
models: { // required
model: string; // required
weight?: number;
}[];
};
timeout?: {
callTimeout: number; // required
};
cacheControl?: {
type: "ephemeral"; // required
ttl?: "5m" | "1h";
};
promptCacheKey?: string;
};
retry?: {
count?: number;
onCodes?: number[];
};
};
fallbackModels?: (string | StreamRunAgentFallbackModelConfiguration2)[];
role: string; // required
instructions: string; // required
message: { // required
messageId?: string;
role: StreamRunAgentRoleUserMessage | StreamRunAgentRoleToolMessage; // required
parts: (TextPart | FilePart | ToolResultPart | ErrorPart)[]; // required
};
variables?: Record<string, any>;
identity?: {
id: string; // required
displayName?: string;
email?: string;
metadata?: Record<string, any>[];
logoUrl?: string;
tags?: string[];
};
contact?: {
id: string; // required
displayName?: string;
email?: string;
metadata?: Record<string, any>[];
logoUrl?: string;
tags?: string[];
};
thread?: {
id: string; // required
tags?: string[];
};
memory?: {
entityId: string; // required
};
path: string; // required
description?: string;
systemPrompt?: string;
memoryStores?: string[];
knowledgeBases?: {
knowledgeId: string; // required
}[];
teamOfAgents?: {
key: string; // required
role?: string;
}[];
settings: { // required
tools?: (GoogleSearchToolInput | WebScraperToolInput | CallSubAgentToolInput | RetrieveAgentsToolInput | QueryMemoryStoreToolInput | WriteMemoryStoreToolInput | RetrieveMemoryStoresToolInput | DeleteMemoryDocumentToolInput | RetrieveKnowledgeBasesToolInput | QueryKnowledgeBaseToolInput | CurrentDateToolInput | AdvisorToolInput | SidekickToolInput | CodeInterpreterToolInput | FileSystemToolInput | AgentToolInputRunHTTPToolRun | AgentToolInputRunCodeToolRun | AgentToolInputRunFunctionToolRun | AgentToolInputRunJSONSchemaToolRun | AgentToolInputRunMCPToolRun)[];
toolApprovalRequired?: "all" | "respect_tool" | "none";
maxIterations?: number;
maxExecutionTime?: number;
maxCost?: number;
chatExposed?: boolean;
evaluators?: {
id: string; // required
sampleRate?: number;
executeOn: "input" | "output"; // required
}[];
guardrails?: {
id: string; // required
sampleRate?: number;
executeOn: "input" | "output"; // required
}[];
};
metadata?: Record<string, any>;
engine?: "text" | "jinja" | "mustache";
streamTimeoutSeconds?: number;
}
Show Variant types
Show Variant types
StreamRunAgentFallbackModelConfiguration2
{
"id": str,
"parameters": { # optional
"name": Optional[str],
"frequency_penalty": Optional[float],
"max_tokens": Optional[int],
"max_completion_tokens": Optional[int],
"presence_penalty": Optional[float],
"response_format": { # optional
# one of: StreamRunAgentResponseFormatAgentsText, StreamRunAgentResponseFormatAgentsJSONObject, StreamRunAgentResponseFormatAgentsRequestJSONSchema
"type": Union[Union[Literal["text"], Literal["json_object"]], Literal["json_schema"]],
"json_schema": {
"description": Optional[str],
"name": str,
"schema_": Optional[Any],
"strict": Optional[bool],
},
},
"reasoning_effort": Optional[Literal["none", "minimal", "low", "medium", "high", "xhigh", "max"]],
"verbosity": Optional[str],
"seed": Optional[float],
"stop": Union[str, List[str]], # optional
"thinking": { # optional
# one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
"type": Union[Union[Literal["disabled"], Literal["enabled"]], Literal["adaptive"]],
"budget_tokens": float,
"thinking_level": Optional[Literal["minimal", "low", "medium", "high"]],
},
"temperature": Optional[float],
"top_p": Optional[float],
"top_k": Optional[float],
"tool_choice": { # optional
# one of: StreamRunAgentToolChoiceAgents1, StreamRunAgentToolChoiceAgents2
"type": Optional[Literal["function"]],
"function": {
"name": str,
},
},
"parallel_tool_calls": Optional[bool],
"modalities": List[Literal["text", "audio"]], # optional
"guardrails": [{ # optional
"id": Union[Literal["orq_pii_detection", "orq_secret_detection", "orq_sexual_moderation", "orq_harmful_moderation"], str],
"execute_on": Literal["input", "output"],
}],
"plugins": List[Union[PIIRedactionPlugin, ResponseHealingPlugin, TraceScrubbingPlugin]], # optional
"fallbacks": [{ # optional
"model": str,
}],
"cache": { # optional
"ttl": Optional[float],
"type": Literal["exact_match"],
},
"load_balancer": { # optional
# one of: StreamRunAgentLoadBalancerAgents1
"type": Literal["weight_based"],
"models": [{
"model": str,
"weight": Optional[float],
}],
},
"timeout": { # optional
"call_timeout": float,
},
"cache_control": { # optional
"type": Literal["ephemeral"],
"ttl": Optional[Literal["5m", "1h"]],
},
"prompt_cache_key": Optional[str],
},
"retry": { # optional
"count": Optional[float],
"on_codes": List[float], # optional
},
}
{
id: string;
parameters?: {
name?: string;
frequencyPenalty?: number;
maxTokens?: number;
maxCompletionTokens?: number;
presencePenalty?: number;
responseFormat?: {
// one of: StreamRunAgentResponseFormatAgentsText, StreamRunAgentResponseFormatAgentsJSONObject, StreamRunAgentResponseFormatAgentsRequestJSONSchema
type: "text" | "json_object" | "json_schema";
jsonSchema: {
description?: string;
name: string;
schema?: any;
strict?: boolean;
};
};
reasoningEffort?: "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
verbosity?: string;
seed?: number;
stop?: string | string[];
thinking?: {
// one of: ThinkingConfigDisabledSchema, ThinkingConfigEnabledSchema, ThinkingConfigAdaptiveSchema
type: "disabled" | "enabled" | "adaptive";
budgetTokens: number;
thinkingLevel?: "minimal" | "low" | "medium" | "high";
};
temperature?: number;
topP?: number;
topK?: number;
toolChoice?: {
// one of: StreamRunAgentToolChoiceAgents1, StreamRunAgentToolChoiceAgents2
type?: "function";
function: {
name: string;
};
};
parallelToolCalls?: boolean;
modalities?: ("text" | "audio")[];
guardrails?: {
id: "orq_pii_detection" | "orq_secret_detection" | "orq_sexual_moderation" | "orq_harmful_moderation" | string;
executeOn: "input" | "output";
}[];
plugins?: (PIIRedactionPlugin | ResponseHealingPlugin | TraceScrubbingPlugin)[];
fallbacks?: {
model: string;
}[];
cache?: {
ttl?: number;
type: "exact_match";
};
loadBalancer?: {
// one of: StreamRunAgentLoadBalancerAgents1
type: "weight_based";
models: {
model: string;
weight?: number;
}[];
};
timeout?: {
callTimeout: number;
};
cacheControl?: {
type: "ephemeral";
ttl?: "5m" | "1h";
};
promptCacheKey?: string;
};
retry?: {
count?: number;
onCodes?: number[];
};
}
Stream an Agent [deprecated]
Stream an existing agent execution in real-time via SSE, providing live message chunks, tool calls, and status updates until completion.from orq_ai_sdk import Orq
import os
with Orq(
api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:
res = orq.agents.stream(key="<key>", message={
"role": "user",
"parts": [{"kind": "text", "text": "What is the weather in Paris?"}],
}, identity={
"id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
"display_name": "Jane Doe",
"email": "jane.doe@example.com",
"metadata": [
{
"department": "Engineering",
"role": "Senior Developer",
},
],
"logo_url": "https://example.com/avatars/jane-doe.jpg",
"tags": [
"hr",
"engineering",
],
}, thread={
"id": "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
"tags": [
"customer-support",
"priority-high",
],
})
with res as event_stream:
for event in event_stream:
# handle event
print(event, flush=True)
import { Orq } from "@orq-ai/node";
const orq = new Orq({
apiKey: process.env["ORQ_API_KEY"] ?? "",
});
async function run() {
const result = await orq.agents.stream({
message: {
role: "user",
parts: [{ kind: "text", text: "What is the weather in Paris?" }],
},
identity: {
id: "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
displayName: "Jane Doe",
email: "jane.doe@example.com",
metadata: [
{
"department": "Engineering",
"role": "Senior Developer",
},
],
logoUrl: "https://example.com/avatars/jane-doe.jpg",
tags: [
"hr",
"engineering",
],
},
thread: {
id: "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
tags: [
"customer-support",
"priority-high",
],
},
}, "<key>");
for await (const event of result) {
console.log(event);
}
}
run();
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],
}
{
taskId?: string;
message: { // required
messageId?: string;
role: StreamAgentRoleUserMessage | StreamAgentRoleToolMessage; // required
parts: (TextPart | FilePart | ToolResultPart | ErrorPart)[]; // required
};
variables?: Record<string, any>;
identity?: {
id: string; // required
displayName?: string;
email?: string;
metadata?: Record<string, any>[];
logoUrl?: string;
tags?: string[];
};
contact?: {
id: string; // required
displayName?: string;
email?: string;
metadata?: Record<string, any>[];
logoUrl?: string;
tags?: string[];
};
thread?: {
id: string; // required
tags?: string[];
};
memory?: {
entityId: string; // required
};
metadata?: Record<string, any>;
engine?: "text" | "jinja" | "mustache";
configuration?: {
blocking?: boolean;
};
streamTimeoutSeconds?: number;
// key is passed as an argument beyond the request object
}