> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents Framework & API Guide

> Step-by-step guide to building agents with the Orq.ai Agents Framework and API. Covers tools, memory, knowledge bases, and multi-agent patterns.

## 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:

1. **Creation** - Define your agent configuration via `POST /v2/agents`
2. **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

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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": []
    }
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

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

  agent = client.agents.create(
      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": []
      }
  )

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

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const client = new Orq({
    apiKey: process.env.ORQ_API_KEY ?? "",
  });

  async function createAgent() {
    const agent = await client.agents.create({
      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: {
        maxIterations: 5,
        maxExecutionTime: 300,
        tools: []
      }
    });

    console.log(`Agent created: ${agent.key}`);
  }

  createAgent();
  ```
</CodeGroup>

### Model Parameter Formats

The `model` parameter supports two formats:

**String Format** (simple, recommended for basic use):

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
"model": "anthropic/claude-sonnet-4-6"
```

Use this when you want default model behavior without custom parameters.

**Object Format** (for advanced configuration):

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
"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        |

<Info>
  To learn more about tools, see the [Tools Documentation](/docs/ai-studio/ai-engineering/build-agents#add-tools).
</Info>

## Step 2: Executing Agents

### Basic Execution

Execute an agent using the Responses API:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

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

  try:
      response = client.responses.create(
          model="agent/support-agent",
          input="I have a question about my account",
      )

      if response.output and len(response.output) > 0:
          content = response.output[0].get("content", [])
          if content:
              print(content[0].get("text", ""))
  except Exception as e:
      print(f"Error: {e}")
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const client = new Orq({
    apiKey: process.env.ORQ_API_KEY ?? "",
  });

  async function executeAgent() {
    try {
      const response = await client.responses.create({
        model: "agent/support-agent",
        input: "I have a question about my account",
      });

      if (response?.output && response.output.length > 0) {
        const content = response.output[0]?.content;
        if (content && content.length > 0) {
          console.log(content[0]?.text);
        }
      }
    } catch (error) {
      console.error(`Error: ${error}`);
    }
  }

  executeAgent();
  ```
</CodeGroup>

### 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`:

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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?"
  }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

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

  try:
      # Continue conversation with previous_response_id
      response = client.responses.create(
          model="agent/support-agent",
          previous_response_id="resp_01K6D8QESESZ6SAXQPJPFQXPFT",
          input="Can you help me reset my password?",
      )

      if response.output and len(response.output) > 0:
          content = response.output[0].get("content", [])
          if content:
              print(content[0].get("text", ""))
  except Exception as e:
      print(f"Error: {e}")
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const client = new Orq({
    apiKey: process.env.ORQ_API_KEY ?? "",
  });

  async function continueConversation() {
    try {
      const response = await client.responses.create({
        model: "agent/support-agent",
        previousResponseId: "resp_01K6D8QESESZ6SAXQPJPFQXPFT",
        input: "Can you help me reset my password?",
      });

      if (response?.output && response.output.length > 0) {
        const content = response.output[0]?.content;
        if (content && content.length > 0) {
          console.log(content[0]?.text);
        }
      }
    } catch (error) {
      console.error(`Error: ${error}`);
    }
  }

  continueConversation();
  ```
</CodeGroup>

<Tip>
  **Key Benefits:**

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

## 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

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  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}")
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const client = new Orq({
    apiKey: process.env.ORQ_API_KEY ?? "",
  });

  async function conversationalLoop() {
    try {
      // Create agent
      const agent = await 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: {
          maxIterations: 5,
          maxExecutionTime: 300,
          tools: []
        }
      });

      console.log(`Agent created: ${agent.key}\n`);

      // Start conversation
      let previousResponseId: string | null = null;
      const messages = [
        "Hello, how are you?",
        "What can you help me with?",
        "Tell me about machine learning"
      ];

      for (const userMessage of messages) {
        console.log(`User: ${userMessage}`);

        const response = await client.responses.create({
          model: "agent/chatbot",
          previousResponseId: previousResponseId ?? undefined,
          input: userMessage,
        });

        // Extract response
        if (response?.output && response.output.length > 0) {
          const content = response.output[0]?.content;
          if (content && content.length > 0) {
            const agentResponse = content[0]?.text;
            console.log(`Agent: ${agentResponse}\n`);

            // Store id for next turn to maintain conversation context
            previousResponseId = response.id;
          }
        }
      }
    } catch (error) {
      console.error(`Error in conversation: ${error}`);
    }
  }

  conversationalLoop();
  ```
</CodeGroup>

## Next Steps

* [**Tools with Agents**](/docs/ai-studio/ai-engineering/build-agents#add-tools) - Add capabilities like web search and custom functions
* [**Multi-Agent Workflows**](/docs/ai-studio/ai-engineering/run-agents#multi-agent-workflows) - Orchestrate multiple agents together
* [**API Reference**](/reference/agents/create-agent) - Detailed endpoint documentation