Skip to main content

​
Overview

The Agents Beta API provides powerful endpoints for creating, executing, and managing AI agents with support for tools, memory, knowledge bases, and real-time streaming.

​
Prerequisites

  • Set up a new Project, if you want to follow along you can name it agents. This will be also used as a path to create your resources.
Setting up a project in Orq.ai
  • Ensure sure you have an API Key ready to use.
  • Optionally install one of our SDKs.

​
Executing an Agent

Running an agent involves a two-step process:
  1. Create an Agent - Define the agent’s configuration (role, instructions, model, tools, etc.)
  2. Execute the Agent - Send a message to the agent using the Responses API
The Agents payloads are built on the A2A protocol, standardizing agent to agent communication, to learn more, see The A2A Protocol Website

​
Step 1: Create an Agent

curl -X POST https://api.orq.ai/v2/agents \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "simple-agent-1",
  "role": "Assistant",
  "description": "A helpful assistant for general tasks",
  "instructions": "Be helpful and concise",
  "path": "Default/agents",
  "model": {
    "id": "openai/gpt-4o"
  },
  "settings": {
    "max_iterations": 3,
    "max_execution_time": 300,
    "tools": []
  }
}'

​
Step 2: Execute the Agent

curl -X POST https://api.orq.ai/v2/agents/simple-agent-1/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_key": "simple-agent-1",
  "background": false,
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "I'\''m preparing a technical presentation on microservices architecture. Can you help me create an outline covering the key benefits, challenges, and best practices?"
      }
    ]
  }
}'
The response will be sent back with a task detail containing the status and metadata, including a unique id.
Set background: false (default) to wait for the agent execution to complete. Set background: true to return immediately without waiting for completion. Use the task id in subsequent calls to continue the conversation with the agent.

​
Model Parameter Format

The model parameter supports two formats: Object format (recommended) - Allows you to specify model parameters like temperature: 
"model": {
  "id": "openai/gpt-4o",
  "parameters": {
    "temperature": 0.5
  }
}
String format - For simple use cases without custom parameters: 
"model": "openai/gpt-4o"
For a complete list of supported model parameters, see the API Reference. 
{
  "id": "01K6D8QESESZ6SAXQPJPFQXPFT",
  "contextId": "0ae12412-cdea-408e-a165-9ff8086db400",
  "kind": "task",
  "status": {
    "state": "submitted",
    "timestamp": "2025-09-30T12:14:32.805Z"
  },
  "metadata": {
    "orq_workspace_id": "0ae12412-cdea-408e-a165-9ff8086db400",
    "orq_agent_id": "01K6D8QET4CR7DSDV07Y5WMDDG",
    "orq_agent_key": "simple-agent-1",
    "orq_created_by_id": null
  }
}

​
Continuing a Task

After receiving a task response, you can continue the conversation by sending additional messages to the same agent. This allows for multi-turn interactions where the agent maintains context from previous exchanges. To continue a task, use the /v2/agents/{key}/responses endpoint and provide the task_id from the previous response. The task must be in an inactive state to continue.
task_id: Optional task ID to continue an existing agent execution. When provided, the agent will continue the conversation from the existing task state. 
curl -X POST https://api.orq.ai/v2/agents/simple-agent-1/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "agent_key": "simple-agent-1",
  "task_id": "01K6D8QESESZ6SAXQPJPFQXPFT",
  "background": false,
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "Great outline! Can you expand on the challenges section? I want to dive deeper into data consistency approaches and monitoring best practices."
      }
    ]
  }
}'
The continuation will return a new task ID representing the extended conversation: 
{
  "id": "01K6D9XQZV34PDPMYX6SHEMY5A",
  "contextId": "0ae12412-cdea-408e-a165-9ff8086db400",
  "kind": "task",
  "status": {
    "state": "submitted",
    "timestamp": "2025-09-30T12:18:45.123Z"
  },
  "metadata": {
    "orq_workspace_id": "0ae12412-cdea-408e-a165-9ff8086db400",
    "orq_agent_id": "01K6D8QET4CR7DSDV07Y5WMDDG",
    "orq_agent_key": "simple-agent-1",
    "orq_created_by_id": null
  }
}
Note: The agent maintains full context from the previous conversation.

​
Agent and Tasks States

Agents run through the following states when processing tasks:
StateDescription
ActiveExecution in progress, continuation requests blocked
InactiveWaiting for user input or tool results, ready for continuation
ErrorExecution failed, continuation blocked
Approval RequiredTool execution requires manual approval (coming soon)
Tasks go through the following states:
StateDescription
SubmittedTask created and queued for execution
WorkingAgent actively processing
Input RequiredWaiting for user input or tool results
CompletedTask finished successfully
FailedTask encountered an error
CanceledTask was manually canceled

​
Advanced Usage

Tool Support

Attaching a File

Memory Management

Knowledge Bases

Multi-Agents Workflow