Skip to main content

​
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.
ToolNameDescription
Current Datecurrent_dateProvides the Current Date to the Model
Google Searchgoogle_searchLets an Agent perform a Google Search
Web Scraperweb_scraperLets 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"
}'
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 StringTo convert your Python code into a JSON-safe string for the payload, use this shell command:Bash
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

​
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"
}'