Agents Framework & API Guide - Orq.ai Documentation

Overview

The Orq.ai Agents Framework provides a powerful API for creating, configuring, and executing intelligent AI agents. This guide covers the complete workflow for building agents programmatically and integrating them into your applications using the Agents API and SDKs.

Core Concepts

Agent Lifecycle

Agents follow a simple two-step lifecycle:

Creation - Define your agent configuration via POST /v2/agents
Execution - Send messages via POST /v3/router/responses with model: "agent/{key}"

Input Format

Agent input is passed as a plain string via the input field. For multimodal content (images, files), pass an array of input items instead.

Response IDs and Context

Each agent execution returns a response id. Pass the same id as previous_response_id in subsequent requests to continue conversations without replaying the full history.

Step 1: Creating Agents

Agent Configuration

An agent requires the following configuration:

key (required): Unique identifier within your workspace
role: The agent’s function or purpose
description: Brief summary of capabilities
instructions: Behavioral guidelines and system prompt
model: Model to use (string or object format)
path: Storage location in your project structure
settings: Execution parameters (max_iterations, max_execution_time, tools)

Creating a Simple Agent

curl -X POST https://api.orq.ai/v2/agents \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "support-agent",
  "role": "Customer Support Assistant",
  "description": "Handles customer inquiries and provides support",
  "instructions": "You are a helpful customer support assistant. Answer customer questions clearly and concisely. If you cannot help, escalate to a human agent.",
  "path": "Default/agents",
  "model": "openai/gpt-4o",
  "settings": {
    "max_iterations": 5,
    "max_execution_time": 300,
    "tools": []
  }
}'

Model Parameter Formats

The model parameter supports two formats: String Format (simple, recommended for basic use):

"model": "anthropic/claude-sonnet-4-6"

Use this when you want default model behavior without custom parameters. Object Format (for advanced configuration):

"model": {
  "id": "openai/gpt-4o",
  "parameters": {
    "temperature": 0.7,
    "max_tokens": 1000
  }
}

Use this when you need to customize temperature, token limits, or other model-specific parameters.

Agent Settings

Configure execution behavior with the settings object:

Parameter	Type	Description	Default
`max_iterations`	number	Maximum agent processing loops	100
`max_execution_time`	number	Maximum execution time in seconds	300
`tools`	array	Tools available to the agent	[]
`tool_approval_required`	string	Tool approval mode	”respect_tool”

Tool Approval Modes:

"respect_tool" (default) - Use tool’s individual approval settings. Each tool defines whether approval is required
"none" - Never require approval, execute all tools automatically. Use for trusted tools and automated workflows
"always" - Always require manual approval before any tool execution. Use for high-risk operations (coming soon)

Mode	Best For	Example
`respect_tool`	Mixed trust levels	Some tools (web search) are safe, others (CRM inserts) need approval
`none`	Automated, trusted tools	Retrieving current date, reading knowledge bases
`always`	High-risk operations	Financial transactions, account deletions, data modifications

To learn more about tools, see the Tools Documentation.

Step 2: Executing Agents

Basic Execution

Execute an agent using the Responses API:

curl -X POST https://api.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "agent/support-agent",
  "input": "I have a question about my account"
}'

Response Structure

The response includes:

output: Array of output items with the agent’s responses
id: Identifier for continuing this conversation
usage: Token consumption details
model: Model used for execution

Step 3: Multi-Turn Conversations

Using Response IDs for Context

Continue conversations by providing the id from a previous response as previous_response_id:

curl -X POST https://api.orq.ai/v3/router/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "agent/support-agent",
  "previous_response_id": "resp_01K6D8QESESZ6SAXQPJPFQXPFT",
  "input": "Can you help me reset my password?"
}'

Key Benefits:

Full conversation context is maintained automatically
No need to replay previous messages
Efficient token usage
Natural multi-turn interactions

Advanced Configuration

Execution Mode

The /v3/router/responses endpoint waits for the agent to finish and returns the complete response including all output, tool results, and token usage. Pass stream: true to receive the response as a stream of server-sent events instead.

Agent State Management

The /responses endpoint returns:

id: Pass as previous_response_id to continue multi-turn conversations
output: Array of output items with the agent’s response
usage: Token consumption details

Reuse the response id as previous_response_id in subsequent requests to maintain conversation context.

Best Practices

Instructions Design

Write clear, concise instructions
Define expected outputs and formats
Specify when to escalate or ask for clarification
Include examples when helpful

Performance Optimization

Set appropriate max_iterations limits
Use max_execution_time to prevent runaway processes
Leverage previous_response_id to avoid context replay
Batch related requests when possible

Complete Example: Conversational Loop

from orq_ai_sdk import Orq
import os

client = Orq(api_key=os.getenv("ORQ_API_KEY", ""))

# Create agent
agent = client.agents.create(
    key="chatbot",
    role="Conversational Assistant",
    description="A friendly conversational assistant",
    instructions="You are a helpful assistant. Answer questions accurately and engage in natural conversation.",
    path="Default/agents",
    model="openai/gpt-4o",
    settings={
        "max_iterations": 5,
        "max_execution_time": 300,
        "tools": []
    }
)

print(f"Agent created: {agent.key}\n")

# Start conversation
previous_response_id = None
messages = [
    "Hello, how are you?",
    "What can you help me with?",
    "Tell me about machine learning"
]

try:
    for user_message in messages:
        print(f"User: {user_message}")

        response = client.responses.create(
            model="agent/chatbot",
            previous_response_id=previous_response_id,
            input=user_message,
        )

        # Extract response
        if response.output and len(response.output) > 0:
            content = response.output[0].get("content", [])
            if content:
                agent_response = content[0].get("text", "")
                print(f"Agent: {agent_response}\n")

                # Store id for next turn to maintain conversation context
                previous_response_id = response.id
except Exception as e:
    print(f"Error in conversation: {e}")

Next Steps

Tools with Agents - Add capabilities like web search and custom functions
Multi-Agent Workflows - Orchestrate multiple agents together
API Reference - Detailed endpoint documentation

​Overview

​Core Concepts

​Agent Lifecycle

​Input Format

​Response IDs and Context

​Step 1: Creating Agents

​Agent Configuration

​Creating a Simple Agent

​Model Parameter Formats

​Agent Settings

​Step 2: Executing Agents

​Basic Execution

​Response Structure

​Step 3: Multi-Turn Conversations

​Using Response IDs for Context

​Advanced Configuration

​Execution Mode

​Agent State Management

​Best Practices

​Instructions Design

​Performance Optimization

​Complete Example: Conversational Loop

​Next Steps

Overview

Core Concepts

Agent Lifecycle

Input Format

Response IDs and Context

Step 1: Creating Agents

Agent Configuration

Creating a Simple Agent

Model Parameter Formats

Agent Settings

Step 2: Executing Agents

Basic Execution

Response Structure

Step 3: Multi-Turn Conversations

Using Response IDs for Context

Advanced Configuration

Execution Mode

Agent State Management

Best Practices

Instructions Design

Performance Optimization

Complete Example: Conversational Loop

Next Steps