Tools with Agents

Overview

Tools extend agent capabilities by providing access to external systems, APIs, and custom functionality. Agents can leverage multiple tool types to handle complex tasks requiring data processing, web interactions, or custom business logic.

To declare a tool during an agent run, use the settings.tools array to import a Tool.

Standard Tools

Agents come pre-packaged with standard tools usable during generation.

Tool	Name	Description
Current Date	`current_date`	Provides the Current Date to the Model
Google Search	`google_search`	Lets an Agent perform a Google Search
Web Scraper	`web_scraper`	Lets an Agent Scrape a Web Page

{
 "settings": {
        "tools": [
            {
                "type": "current_date"
            },
            {
                "type": "google_search"
            },
            {
                "type": "web_scraper"
            }
        ]
  }
}

Function Tools

Custom business logic with OpenAPI-style schemas

curl -X POST https://api.orq.ai/v2/agents/run \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "journey-plan-orchestrator-1",
  "role": "Itinerary Assistant",
  "description": "A very well mannered overall orchestrator agent who helps plan trips",
  "instructions": "You are able to help anybody plan their journey into any country",
  "system_prompt": "You are a helpful agent who has multiple tools available. Call your date tool first as your temporal info is probably outdated.",
  "settings": {
    "max_iterations": 5,
    "max_execution_time": 300,
    "tools": [
      {
        "type": "current_date"
      },
      {
        "type": "function",
        "key": "get_local_events",
        "display_name": "Get Local Events",
        "description": "Retrieves local events",
        "function": {
          "name": "get_local_events",
          "parameters": {
            "type": "object",
            "properties": {
              "city": {
                "type": "string",
                "description": "The name of the city"
              },
              "date": {
                "type": "string",
                "description": "The date (YYYY-MM-DD)"
              }
            },
            "required": [
              "city",
              "date"
            ]
          }
        }
      }
    ]
  },
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "Whats happening in budapest on the 26th and 27th of august this year?"
      }
    ]
  },
  "model": "openai/gpt-4o",
  "path": "Default/agents"
}'

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.run(request={
        "key": "journey-plan-orchestrator-1",
        "role": "Itinerary Assistant",
        "description": "A very well mannered overall orchestrator agent who helps plan trips",
        "instructions": "You are able to help anybody plan their journey into any country",
        "system_prompt": "You are a helpful agent who has multiple tools available. Call your date tool first as your temporal info is probably outdated.",
        "settings": {
            "max_iterations": 5,
            "max_execution_time": 300,
            "tools": [
                {
                    "type": "current_date"
                },
                {
                    "type": "function",
                    "key": "get_local_events",
                    "display_name": "Get Local Events",
                    "description": "Retrieves local events",
                    "function": {
                        "name": "get_local_events",
                        "parameters": {
                            "type": "object",
                            "properties": {
                                "city": {
                                    "type": "string",
                                    "description": "The name of the city"
                                },
                                "date": {
                                    "type": "string",
                                    "description": "The date (YYYY-MM-DD)"
                                }
                            },
                            "required": [
                                "city",
                                "date"
                            ]
                        }
                    }
                }
            ]
        },
        "message": {
            "role": "user",
            "parts": [
                {
                    "kind": "text",
                    "text": "Whats happening in budapest on the 26th and 27th of august this year?"
                }
            ]
        },
        "model": "openai/gpt-4o",
        "path": "Default/agents"
    })

    assert res is not None
    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.run({
    key: "journey-plan-orchestrator-1",
    role: "Itinerary Assistant",
    description: "A very well mannered overall orchestrator agent who helps plan trips",
    instructions: "You are able to help anybody plan their journey into any country",
    systemPrompt: "You are a helpful agent who has multiple tools available. Call your date tool first as your temporal info is probably outdated.",
    settings: {
      maxIterations: 5,
      maxExecutionTime: 300,
      tools: [
        {
          type: "current_date"
        },
        {
          type: "function",
          key: "get_local_events",
          displayName: "Get Local Events",
          description: "Retrieves local events",
          function: {
            name: "get_local_events",
            parameters: {
              type: "object",
              properties: {
                city: {
                  type: "string",
                  description: "The name of the city"
                },
                date: {
                  type: "string",
                  description: "The date (YYYY-MM-DD)"
                }
              },
              required: [
                "city",
                "date"
              ]
            }
          }
        }
      ]
    },
    message: {
      role: "user",
      parts: [
        {
          kind: "text",
          text: "Whats happening in budapest on the 26th and 27th of august this year?"
        }
      ]
    },
    model: "openai/gpt-4o",
    path: "Default/agents"
  });

  console.log(result);
}

run();

For the above method, using the Stream Run execution, we're getting the following payloads showing the agent's reasoning process:

Iteration 1: Agent Calls Current Date Tool

What's happening: The agent analyzes the user's question and decides it needs to know the current date first (following system instructions). It calls the orq_current_date tool.

{
  "type": "event.agents.thought",
  "data": {
    "message_difference": {
      "2": {
        "role": "agent",
        "parts": [
          {
            "kind": "tool_call",
            "tool_name": "orq_current_date",
            "tool_call_id": "call_VHTcKDA3nWxQUYOnqPHedURK",
            "arguments": {"timezone": "UTC"}
          }
        ]
      }
    },
    "iteration": 1
  }
}

Tool Result: Date Retrieved

What's happening: The orq_current_date tool returns 2025-10-03, so the agent now knows the user is asking about past events (August 26-27, 2025 has already occurred).

{
  "type": "event.workflow_events.tool_execution_finished",
  "data": {
    "result": {
      "currentDate": "2025-10-03T04:22:50.867Z"
    }
  }
}

Iteration 2: Agent Calls Function Tools

What's happening: With date context established, the agent decides to make TWO parallel calls to the get_local_events function tool (one for each date requested).

{
  "type": "event.agents.thought",
  "data": {
    "message_difference": {
      "4": {
        "role": "agent",
        "parts": [
          {
            "kind": "tool_call",
            "tool_name": "get_local_events",
            "arguments": {"city": "Budapest", "date": "2025-08-26"}
          },
          {
            "kind": "tool_call",
            "tool_name": "get_local_events",
            "arguments": {"city": "Budapest", "date": "2025-08-27"}
          }
        ]
      }
    },
    "iteration": 2,
    "accumulated_execution_time": 920.9
  }
}

Agent Paused: Awaiting Function Implementation

What's happening: Since get_local_events is a function tool (not a built-in tool), the agent pauses and waits for you to implement the function and provide results via the continuation API.

{
  "type": "event.agents.inactive",
  "data": {
    "finish_reason": "function_call",
    "pending_tool_calls": [
      {
        "id": "call_pvC8CFzY8tjw8epqPkgHFMY4",
        "function": {
          "name": "get_local_events",
          "arguments": "{\"city\": \"Budapest\", \"date\": \"2025-08-26\"}"
        }
      },
      {
        "id": "call_QsVc8ZPMfJXHV3socDnYSC1a",
        "function": {
          "name": "get_local_events",
          "arguments": "{\"city\": \"Budapest\", \"date\": \"2025-08-27\"}"
        }
      }
    ]
  }
}

Note: You must implement the function and submit results via the continuation API. The agent will then resume and synthesize a final answer.

Code Tools (Python)

Embed code tools with executable python code, for this example we'll be embedding a password generator.

  import random
  import string

  def generate_password(length, include_numbers, include_symbols):
      """Generate a secure random password."""
      # Start with letters
      chars = string.ascii_letters

      # Add numbers if requested
      if include_numbers:
          chars += string.digits

      # Add symbols if requested
      if include_symbols:
          chars += '!@#$%^&*()_+-=[]{}|;:,.<>?'

      # Generate password
      password = ''.join(random.choice(chars) for _ in range(length))

      return {
          "password": password,
          "length": len(password),
          "includes_numbers": include_numbers,
          "includes_symbols": include_symbols,
          "character_types": len(chars)
      }

  # Execute with params
  result = generate_password(
      params.get('length', 12),
      params.get('include_numbers', True),
      params.get('include_symbols', True)
  )

💡
Tip: Converting Python Code to Payload String
To convert your Python code into a JSON-safe string for the payload, use this shell command:
cat your_script.py | jq -Rs .

Once the payload string is generated, it can be embedded within the code_tool section as follows:

The tool is then usable as any other tool. Callable by its key (here password_generator.

The tool has access to the declared parameters as input for execution.

curl -X POST https://api.orq.ai/v2/agents/run \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d @- << 'EOF'
{
  "key": "password-helper-agent",
  "role": "Security Assistant",
  "description": "Agent that helps generate secure passwords",
  "instructions": "You help users create secure passwords with custom requirements.",
  "settings": {
    "max_iterations": 3,
    "max_execution_time": 300,
    "tools": [
      {
        "key": "password_generator",
        "path": "Default/agents",
        "type": "code",
        "display_name": "Password Generator",
        "description": "Generates a secure random password with specified criteria",
        "requires_approval": false,
        "code_tool": {
          "language": "python",
          "code": "import random\nimport string\n\ndef generate_password(length, include_numbers, include_symbols):\n    \"\"\"Generate a secure random password.\"\"\"\n    chars = string.ascii_letters\n    \n    if include_numbers:\n        chars += string.digits\n    \n    if include_symbols:\n        chars += '!@#$%^&*()_+-=[]{}|;:,.<>?'\n    \n    password = ''.join(random.choice(chars) for _ in range(length))\n    \n    return {\n        \"password\": password,\n        \"length\": len(password),\n        \"includes_numbers\": include_numbers,\n        \"includes_symbols\": include_symbols,\n        \"character_types\": len(chars)\n    }\n\nresult = generate_password(\n    params.get('length', 12),\n    params.get('include_numbers', True),\n    params.get('include_symbols', True)\n)",
          "parameters": {
            "type": "object",
            "properties": {
              "length": {
                "type": "integer",
                "description": "Password length (default: 12)",
                "default": 12
              },
              "include_numbers": {
                "type": "boolean",
                "description": "Include numbers in password (default: true)",
                "default": true
              },
              "include_symbols": {
                "type": "boolean",
                "description": "Include special symbols (default: true)",
                "default": true
              }
            },
            "required": ["length", "include_numbers", "include_symbols"],
            "additionalProperties": false
          }
        }
      }
    ]
  },
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "Generate a 16-character password with numbers and symbols for my new database account"
      }
    ]
  },
  "model": "openai/gpt-4o",
  "path": "Default/agents"
}
EOF

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.run(request={
        "key": "password-helper-agent",
        "role": "Security Assistant",
        "description": "Agent that helps generate secure passwords",
        "instructions": "You help users create secure passwords with custom requirements.",
        "settings": {
            "max_iterations": 3,
            "max_execution_time": 300,
            "tools": [
                {
                    "key": "password_generator",
                    "path": "Default/agents",
                    "type": "code",
                    "display_name": "Password Generator",
                    "description": "Generates a secure random password with specified criteria",
                    "requires_approval": False,
                    "code_tool": {
                        "language": "python",
                        "code": "import random\nimport string\n\ndef generate_password(length, include_numbers, include_symbols):\n    \"\"\"Generate a secure random password.\"\"\"\n    # Start with letters\n    chars = string.ascii_letters\n    \n    # Add numbers if requested\n    if include_numbers:\n        chars += string.digits\n    \n    # Add symbols if requested\n    if include_symbols:\n        chars += '!@#$%^&*()_+-=[]{}|;:,.<>?'\n    \n    # Generate password\n    password = ''.join(random.choice(chars) for _ in range(length))\n    \n    return {\n        \"password\": password,\n        \"length\": len(password),\n        \"includes_numbers\": include_numbers,\n        \"includes_symbols\": include_symbols,\n        \"character_types\": len(chars)\n    }\n\n# Execute with params\nresult = generate_password(\n    params.get('length', 12),\n    params.get('include_numbers', True),\n    params.get('include_symbols', True)\n)",
                        "parameters": {
                            "type": "object",
                            "properties": {
                                "length": {
                                    "type": "integer",
                                    "description": "Password length (default: 12)",
                                    "default": 12
                                },
                                "include_numbers": {
                                    "type": "boolean",
                                    "description": "Include numbers in password (default: true)",
                                    "default": True
                                },
                                "include_symbols": {
                                    "type": "boolean",
                                    "description": "Include special symbols (default: true)",
                                    "default": True
                                }
                            },
                            "required": ["length", "include_numbers", "include_symbols"],
                            "additionalProperties": False
                        }
                    }
                }
            ]
        },
        "message": {
            "role": "user",
            "parts": [
                {
                    "kind": "text",
                    "text": "Generate a 16-character password with numbers and symbols for my new database account"
                }
            ]
        },
        "model": "openai/gpt-4o",
        "path": "Default/agents"
    })

    assert res is not None
    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.run({
    key: "password-helper-agent",
    role: "Security Assistant",
    description: "Agent that helps generate secure passwords",
    instructions: "You help users create secure passwords with custom requirements.",
    settings: {
      maxIterations: 3,
      maxExecutionTime: 300,
      tools: [
        {
          key: "password_generator",
          path: "Default/agents",
          type: "code",
          displayName: "Password Generator",
          description: "Generates a secure random password with specified criteria",
          requiresApproval: false,
          codeTool: {
            language: "python",
            code: "import random\nimport string\n\ndef generate_password(length, include_numbers, include_symbols):\n    \"\"\"Generate a secure random password.\"\"\"\n    # Start with letters\n    chars = string.ascii_letters\n    \n    # Add numbers if requested\n    if include_numbers:\n        chars += string.digits\n    \n    # Add symbols if requested\n    if include_symbols:\n        chars += '!@#$%^&*()_+-=[]{}|;:,.<>?'\n    \n    # Generate password\n    password = ''.join(random.choice(chars) for _ in range(length))\n    \n    return {\n        \"password\": password,\n        \"length\": len(password),\n        \"includes_numbers\": include_numbers,\n        \"includes_symbols\": include_symbols,\n        \"character_types\": len(chars)\n    }\n\n# Execute with params\nresult = generate_password(\n    params.get('length', 12),\n    params.get('include_numbers', True),\n    params.get('include_symbols', True)\n)",
            parameters: {
              type: "object",
              properties: {
                length: {
                  type: "integer",
                  description: "Password length (default: 12)",
                  default: 12
                },
                includeNumbers: {
                  type: "boolean",
                  description: "Include numbers in password (default: true)",
                  default: true
                },
                includeSymbols: {
                  type: "boolean",
                  description: "Include special symbols (default: true)",
                  default: true
                }
              },
              required: ["length", "includeNumbers", "includeSymbols"],
              additionalProperties: false
            }
          }
        }
      ]
    },
    message: {
      role: "user",
      parts: [
        {
          kind: "text",
          text: "Generate a 16-character password with numbers and symbols for my new database account"
        }
      ]
    },
    model: "openai/gpt-4o",
    path: "Default/agents"
  });

  console.log(result);
}

run();

HTTP Tools

External API integrations supporting:

Blueprint: URL templates with parameter substitution using {{parameter}} syntax
Method: HTTP methods (GET, POST, PUT, DELETE, etc.)
Headers: Custom headers including authentication
Arguments: Parameter definitions with types and descriptions
send_to_model: Controls whether parameter values are visible to the LLM
- default_value: Default values for parameters not provided by the LLM

Example

curl -X POST https://api.orq.ai/v2/agents/run \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "weather-analyst-1",
  "role": "Weather Analyst",
  "description": "Analyzes location data and provides weather information",
  "instructions": "Use the weather API to provide current weather information for requested locations",
  "settings": {
    "max_iterations": 5,
    "max_execution_time": 600,
    "tool_approval_required": "none",
    "tools": [
      {
        "key": "openweather_get_api_6",
        "description": "Fetches weather data from the OpenWeatherMap API",
        "display_name": "openweather_get_api_6",
        "type": "http",
        "http": {
          "blueprint": {
            "url": "https://api.openweathermap.org/data/2.5/weather?lat={{lat}}&lon={{lon}}&appid={{appid}}",
            "method": "GET",
            "headers": {
              "Content-Type": "application/json"
            }
          },
          "arguments": {
            "lat": {
              "type": "number",
              "description": "Latitude of the location",
              "send_to_model": true
            },
            "lon": {
              "type": "number",
              "description": "Longitude of the location",
              "send_to_model": true
            },
            "appid": {
              "type": "string",
              "description": "Your OpenWeatherMap API key",
              "send_to_model": false,
              "default_value": "5b8c6acc332d6526b9123731a011ff64_random"
            }
          }
        }
      }
    ]
  },
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "What is the current weather in Paris, France?"
      }
    ]
  },
  "model": "openai/gpt-4o",
  "path": "Default/agents"
}'

from orq_ai_sdk import Orq
import os

with Orq(
    api_key=os.getenv("ORQ_API_KEY", ""),
) as orq:

    res = orq.agents.run(request={
        "key": "weather-analyst-1",
        "role": "Weather Analyst",
        "description": "Analyzes location data and provides weather information",
        "instructions": "Use the weather API to provide current weather information for requested locations",
        "settings": {
            "max_iterations": 5,
            "max_execution_time": 600,
            "tool_approval_required": "none",
            "tools": [
                {
                    "key": "openweather_get_api_6",
                    "description": "Fetches weather data from the OpenWeatherMap API",
                    "display_name": "openweather_get_api_6",
                    "type": "http",
                    "http": {
                        "blueprint": {
                            "url": "https://api.openweathermap.org/data/2.5/weather?lat={{lat}}&lon={{lon}}&appid={{appid}}",
                            "method": "GET",
                            "headers": {
                                "Content-Type": "application/json"
                            }
                        },
                        "arguments": {
                            "lat": {
                                "type": "number",
                                "description": "Latitude of the location",
                                "send_to_model": True
                            },
                            "lon": {
                                "type": "number",
                                "description": "Longitude of the location",
                                "send_to_model": True
                            },
                            "appid": {
                                "type": "string",
                                "description": "Your OpenWeatherMap API key",
                                "send_to_model": False,
                                "default_value": "5b8c6acc332d6526b9123731a011ff64_random"
                            }
                        }
                    }
                }
            ]
        },
        "message": {
            "role": "user",
            "parts": [
                {
                    "kind": "text",
                    "text": "What is the current weather in Paris, France?"
                }
            ]
        },
        "model": "openai/gpt-4o",
        "path": "Default/agents"
    })

    assert res is not None
    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.run({
    key: "weather-analyst-1",
    role: "Weather Analyst",
    description: "Analyzes location data and provides weather information",
    instructions: "Use the weather API to provide current weather information for requested locations",
    settings: {
      maxIterations: 5,
      maxExecutionTime: 600,
      toolApprovalRequired: "none",
      tools: [
        {
          key: "openweather_get_api_6",
          description: "Fetches weather data from the OpenWeatherMap API",
          displayName: "openweather_get_api_6",
          type: "http",
          http: {
            blueprint: {
              url: "https://api.openweathermap.org/data/2.5/weather?lat={{lat}}&lon={{lon}}&appid={{appid}}",
              method: "GET",
              headers: {
                "Content-Type": "application/json"
              }
            },
            arguments: {
              lat: {
                type: "number",
                description: "Latitude of the location",
                sendToModel: true
              },
              lon: {
                type: "number",
                description: "Longitude of the location",
                sendToModel: true
              },
              appid: {
                type: "string",
                description: "Your OpenWeatherMap API key",
                sendToModel: false,
                defaultValue: "5b8c6acc332d6526b9123731a011ff64_random"
              }
            }
          }
        }
      ]
    },
    message: {
      role: "user",
      parts: [
        {
          kind: "text",
          text: "What is the current weather in Paris, France?"
        }
      ]
    },
    model: "openai/gpt-4o",
    path: "Default/agents"
  });

  console.log(result);
}

run();