curl --request POST \
--url https://api.orq.ai/v2/agents/run \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"key": "<string>",
"model": "<string>",
"role": "<string>",
"instructions": "<string>",
"message": {
"role": "user",
"parts": [
{
"kind": "text",
"text": "<string>"
}
],
"messageId": "<string>"
},
"path": "Default",
"settings": {
"tools": [],
"tool_approval_required": "none",
"max_iterations": 100,
"max_execution_time": 300,
"evaluators": [
{
"id": "<string>",
"execute_on": "input",
"sample_rate": 50
}
],
"guardrails": [
{
"id": "<string>",
"execute_on": "input",
"sample_rate": 50
}
]
},
"task_id": "<string>",
"fallback_models": [
"<string>"
],
"variables": {},
"contact": {
"id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
"display_name": "Jane Doe",
"email": "[email protected]",
"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"
]
},
"memory": {
"entity_id": "<string>"
},
"description": "<string>",
"system_prompt": "<string>",
"memory_stores": [],
"knowledge_bases": [],
"team_of_agents": [],
"metadata": {}
}
'{
"id": "<string>",
"contextId": "<string>",
"kind": "task",
"status": {
"state": "submitted",
"timestamp": "<string>",
"message": {
"kind": "message",
"messageId": "<string>",
"role": "user",
"parts": [
{
"kind": "text",
"text": "<string>"
}
]
}
},
"metadata": {}
}Run an agent with configuration
Executes an agent using inline configuration or references an existing agent. Supports dynamic agent creation where the system automatically manages agent versioning - reusing existing agents with matching configurations or creating new versions when configurations differ. Ideal for programmatic agent execution with flexible configuration management. The agent processes messages in A2A format with support for memory context, tool execution, and automatic model fallback on failure.
curl --request POST \
--url https://api.orq.ai/v2/agents/run \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"key": "<string>",
"model": "<string>",
"role": "<string>",
"instructions": "<string>",
"message": {
"role": "user",
"parts": [
{
"kind": "text",
"text": "<string>"
}
],
"messageId": "<string>"
},
"path": "Default",
"settings": {
"tools": [],
"tool_approval_required": "none",
"max_iterations": 100,
"max_execution_time": 300,
"evaluators": [
{
"id": "<string>",
"execute_on": "input",
"sample_rate": 50
}
],
"guardrails": [
{
"id": "<string>",
"execute_on": "input",
"sample_rate": 50
}
]
},
"task_id": "<string>",
"fallback_models": [
"<string>"
],
"variables": {},
"contact": {
"id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
"display_name": "Jane Doe",
"email": "[email protected]",
"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"
]
},
"memory": {
"entity_id": "<string>"
},
"description": "<string>",
"system_prompt": "<string>",
"memory_stores": [],
"knowledge_bases": [],
"team_of_agents": [],
"metadata": {}
}
'{
"id": "<string>",
"contextId": "<string>",
"kind": "task",
"status": {
"state": "submitted",
"timestamp": "<string>",
"message": {
"kind": "message",
"messageId": "<string>",
"role": "user",
"parts": [
{
"kind": "text",
"text": "<string>"
}
]
}
},
"metadata": {}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Body
A unique identifier for the agent. This key must be unique within the same workspace and cannot be reused. When executing the agent, this key determines if the agent already exists. If the agent version differs, a new version is created at the end of the execution, except for the task. All agent parameters are evaluated to decide if a new version is needed.
1Model configuration for this execution. Can override the agent manifest defaults if the agent already exists.
Specifies the agent's function and area of expertise.
1Provides context and purpose for the agent. Combined with the system prompt template to generate the agent's instructions.
1The A2A format message containing the task for the agent to perform.
Show child attributes
Show child attributes
Message role (user or tool for continuing executions)
user A2A message parts (text, file, or tool_result only)
Message part that can be provided by users. Use "text" for regular messages, "file" for attachments, or "tool_result" when responding to tool call requests.
Optional A2A message ID in ULID format
Entity storage path in the format: project/folder/subfolder/...
The first element identifies the project, followed by nested folders (auto-created as needed).
With project-based API keys, the first element is treated as a folder name, as the project is predetermined by the API key.
"Default"
Show child attributes
Show child attributes
Tools available to the agent
Tool configuration for agent run operations. Built-in tools only require a type and requires_approval, while custom tools (HTTP, Code, Function, MCP) support full inline definitions for on-the-fly creation.
- Google search tool
- Web scraper tool
- Call sub agent tool
- Retrieve agents tool
- Query memory store tool
- Write memory store tool
- Retrieve memory stores tool
- Delete memory document tool
- Retrieve knowledge bases tool
- Query knowledge base tool
- Current date tool
- HTTP Tool (Run)
- Code Tool (Run)
- Function Tool (Run)
- MCP Tool (Run)
If all, the agent will require approval for all tools. If respect_tool, the agent will require approval for tools that have the requires_approval flag set to true. If none, the agent will not require approval for any tools.
all, respect_tool, none Maximum iterations(llm calls) before the agent will stop executing.
x > 1Maximum time (in seconds) for the agent thinking process. This does not include the time for tool calls and sub agent calls. It will be loosely enforced, the in progress LLM calls will not be terminated and the last assistant message will be returned.
x > 2Configuration for an evaluator applied to the agent
Show child attributes
Show child attributes
Unique key or identifier of the evaluator
Determines whether the evaluator runs on the agent input (user message) or output (agent response).
input, output The percentage of executions to evaluate with this evaluator (1-100). For example, a value of 50 means the evaluator will run on approximately half of the executions.
1 <= x <= 100Configuration for a guardrail applied to the agent
Show child attributes
Show child attributes
Unique key or identifier of the evaluator
Determines whether the evaluator runs on the agent input (user message) or output (agent response).
input, output The percentage of executions to evaluate with this evaluator (1-100). For example, a value of 50 means the evaluator will run on approximately half of the executions.
1 <= x <= 100Optional task ID to continue an existing agent execution. When provided, the agent will continue the conversation from the existing task state. The task must be in an inactive state to continue.
Optional array of fallback models used when the primary model fails. Fallbacks are attempted in order. All models must support tool calling.
Fallback model for automatic failover when primary model request fails. Supports optional parameter overrides. Can be a simple model ID string or a configuration object with model-specific parameters. Fallbacks are tried in order.
Information about the contact making the request. If the contact does not exist, it will be created automatically.
Show child attributes
Show child attributes
Unique identifier for the contact
"contact_01ARZ3NDEKTSV4RRFFQ69G5FAV"
Display name of the contact
"Jane Doe"
Email address of the contact
URL to the contact's avatar or logo
"https://example.com/avatars/jane-doe.jpg"
A list of tags associated with the contact
["hr", "engineering"]
Thread information to group related requests
Memory configuration for the agent execution. Used to associate memory stores with specific entities like users or sessions.
Show child attributes
Show child attributes
An entity ID used to link memory stores to a specific user, session, or conversation. This ID is used to isolate and retrieve memories specific to the entity across agent executions.
A brief summary of the agent's purpose.
1A custom system prompt template for the agent. If omitted, the default template is used.
1Array of memory store identifiers that are accessible to the agent. Accepts both memory store IDs and keys.
The agents that are accessible to this orchestrator. The main agent can hand off to these agents to perform tasks.
Response
Agent execution initiated successfully. Returns task details including the task ID, execution status, and agent response. The task ID can be used to track execution progress and retrieve results.
Response format following the Agent-to-Agent (A2A) protocol. Returned when starting or continuing an agent task execution.
The unique ID of the created agent execution task
The correlation ID for this execution (used for tracking)
A2A entity type identifier
task Current task status information
Show child attributes
Show child attributes
Current state of the agent task execution. Values: submitted (queued), working (executing), input-required (awaiting user input), completed (finished successfully), failed (error occurred). Note: auth-required, canceled, and rejected statuses are defined for A2A protocol compatibility but are not currently supported in task execution.
submitted, working, input-required, auth-required, completed, failed, canceled, rejected ISO 8601 timestamp of when the status was updated
Optional A2A message providing additional context about the current status
Show child attributes
Show child attributes
message Role of the message sender in the A2A protocol. Values: user (end user), agent (AI agent), tool (tool execution result), system (system instructions/prompts).
user, agent, tool, system A text content part containing plain text or markdown. Used for agent messages, user input, and text-based responses.
Was this page helpful?