Agents.Responses
Create a Response [deprecated]
Create an agent response for a given message. Return the complete conversation including messages, tool interactions, and token usage.from orq_ai_sdk import Orq
import os
with Orq(
api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:
res = orq.agents.responses.create(agent_key="<value>", message={
"role": "tool",
"parts": [],
}, identity={
"id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
"display_name": "Jane Doe",
"email": "jane.doe@example.com",
"metadata": [
{
"department": "Engineering",
"role": "Senior Developer",
},
],
"logo_url": "https://example.com/avatars/jane-doe.jpg",
"tags": [
"hr",
"engineering",
],
}, thread={
"id": "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
"tags": [
"customer-support",
"priority-high",
],
}, background=False, stream=False)
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.responses.create({
agentKey: "<value>",
message: {
role: "tool",
parts: [],
},
identity: {
id: "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
displayName: "Jane Doe",
email: "jane.doe@example.com",
metadata: [
{
"department": "Engineering",
"role": "Senior Developer",
},
],
logoUrl: "https://example.com/avatars/jane-doe.jpg",
tags: [
"hr",
"engineering",
],
},
thread: {
id: "thread_01ARZ3NDEKTSV4RRFFQ69G5FAV",
tags: [
"customer-support",
"priority-high",
],
},
});
console.log(result);
}
run();
Show Parameters
Show Parameters
{
"agent_key": str, # required
"message": { # required
"message_id": Optional[str],
"role": Union[RoleUserMessage, RoleToolMessage], # 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],
},
"background": Optional[bool],
"stream": Optional[bool],
"conversation": { # optional
"id": str, # required
},
}
{
agentKey: string; // required
taskId?: string;
message: { // required
messageId?: string;
role: RoleUserMessage | RoleToolMessage; // required
parts: (TextPart | FilePart | ToolResultPart | ErrorPart)[]; // required
};
variables?: Record<string, any>;
identity?: {
id: string; // required
displayName?: string;
email?: string;
metadata?: Record<string, any>[];
logoUrl?: string;
tags?: string[];
};
contact?: {
id: string; // required
displayName?: string;
email?: string;
metadata?: Record<string, any>[];
logoUrl?: string;
tags?: string[];
};
thread?: {
id: string; // required
tags?: string[];
};
memory?: {
entityId: string; // required
};
metadata?: Record<string, any>;
engine?: "text" | "jinja" | "mustache";
configuration?: {
blocking?: boolean;
};
background?: boolean;
stream?: boolean;
conversation?: {
id: string; // required
};
}
Show Response
Show Response
{
"id": str,
"task_id": str,
"output": [{
"message_id": str,
"role": Literal["user", "agent", "tool", "system"],
"parts": List[Union[TextPart, ErrorPart, DataPart, FilePart, ToolCallPart, ToolResultPart]],
"metadata": Dict[str, Any], # optional
}],
"created_at": str,
"model": str,
"usage": { # optional
"completion_tokens": Optional[float],
"prompt_tokens": Optional[float],
"total_tokens": Optional[float],
"prompt_tokens_details": { # optional
"cached_tokens": Optional[int],
"cache_creation_tokens": Optional[int],
"audio_tokens": Optional[int],
},
"completion_tokens_details": { # optional
"reasoning_tokens": Optional[float],
"accepted_prediction_tokens": Optional[float],
"rejected_prediction_tokens": Optional[float],
"audio_tokens": Optional[int],
},
},
"finish_reason": Optional[Literal["stop", "length", "tool_calls", "content_filter", "function_call", "max_iterations", "max_time"]],
"pending_tool_calls": [{ # optional
"id": str,
"type": Literal["function"],
"function": {
"name": Optional[str],
"arguments": Optional[str],
},
}],
"telemetry": { # optional
"trace_id": str,
"span_id": str,
},
}
{
id: string;
taskId: string;
output: {
messageId: string;
role: "user" | "agent" | "tool" | "system";
parts: (TextPart | ErrorPart | DataPart | FilePart | ToolCallPart | ToolResultPart)[];
metadata?: Record<string, any>;
}[];
createdAt: string;
model: string;
usage?: {
completionTokens?: number;
promptTokens?: number;
totalTokens?: number;
promptTokensDetails?: {
cachedTokens?: number;
cacheCreationTokens?: number;
audioTokens?: number;
};
completionTokensDetails?: {
reasoningTokens?: number;
acceptedPredictionTokens?: number;
rejectedPredictionTokens?: number;
audioTokens?: number;
};
};
finishReason?: "stop" | "length" | "tool_calls" | "content_filter" | "function_call" | "max_iterations" | "max_time";
pendingToolCalls?: {
id: string;
type: "function";
function: {
name?: string;
arguments?: string;
};
}[];
telemetry?: {
traceId: string;
spanId: string;
};
}
Retrieve a Response [deprecated]
Retrieve an agent response by task ID, including output, model info, token usage, and execution status.from orq_ai_sdk import Orq
import os
with Orq(
api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:
res = orq.agents.responses.get(agent_key="<value>", task_id="<id>")
# 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.responses.get({
agentKey: "<value>",
taskId: "<id>",
});
console.log(result);
}
run();
Show Parameters
Show Parameters
{
"agent_key": str, # required
"task_id": str, # required
}
{
agentKey: string; // required
taskId: string; // required
}
Show Response
Show Response
{
"id": str,
"task_id": str,
"output": [{
"message_id": str,
"role": Literal["user", "agent", "tool", "system"],
"parts": List[Union[TextPart, ErrorPart, DataPart, FilePart, ToolCallPart, ToolResultPart]],
"metadata": Dict[str, Any], # optional
}],
"created_at": str,
"model": str,
"usage": { # optional
"completion_tokens": Optional[float],
"prompt_tokens": Optional[float],
"total_tokens": Optional[float],
"prompt_tokens_details": { # optional
"cached_tokens": Optional[int],
"cache_creation_tokens": Optional[int],
"audio_tokens": Optional[int],
},
"completion_tokens_details": { # optional
"reasoning_tokens": Optional[float],
"accepted_prediction_tokens": Optional[float],
"rejected_prediction_tokens": Optional[float],
"audio_tokens": Optional[int],
},
},
"finish_reason": Optional[Literal["stop", "length", "tool_calls", "content_filter", "function_call", "max_iterations", "max_time"]],
"pending_tool_calls": [{ # optional
"id": str,
"type": Literal["function"],
"function": {
"name": Optional[str],
"arguments": Optional[str],
},
}],
"telemetry": { # optional
"trace_id": str,
"span_id": str,
},
"status": Literal["in_progress", "completed", "failed"],
"error": Optional[str],
}
{
id: string;
taskId: string;
output: {
messageId: string;
role: "user" | "agent" | "tool" | "system";
parts: (TextPart | ErrorPart | DataPart | FilePart | ToolCallPart | ToolResultPart)[];
metadata?: Record<string, any>;
}[];
createdAt: string;
model: string;
usage?: {
completionTokens?: number;
promptTokens?: number;
totalTokens?: number;
promptTokensDetails?: {
cachedTokens?: number;
cacheCreationTokens?: number;
audioTokens?: number;
};
completionTokensDetails?: {
reasoningTokens?: number;
acceptedPredictionTokens?: number;
rejectedPredictionTokens?: number;
audioTokens?: number;
};
};
finishReason?: "stop" | "length" | "tool_calls" | "content_filter" | "function_call" | "max_iterations" | "max_time";
pendingToolCalls?: {
id: string;
type: "function";
function: {
name?: string;
arguments?: string;
};
}[];
telemetry?: {
traceId: string;
spanId: string;
};
status: "in_progress" | "completed" | "failed";
error?: string;
}