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();
Updated 20 days ago