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 Function tools allow you to define custom functions that agents can call. First, create an agent with function tools configured, then invoke it using the responses endpoint.

​
Step 1: Create Agent with Function Tools

curl -X POST https://api.orq.ai/v2/agents \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "journey-plan-agent",
  "role": "Itinerary Assistant",
  "description": "An agent that helps plan trips and find local events",
  "instructions": "Help users plan their journey. Call the current_date tool first to know the current date, then use get_local_events to find events.",
  "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 for a given city and date",
        "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"]
          }
        }
      }
    ]
  },
  "model": "openai/gpt-4o",
  "path": "Default/agents"
}'

​
Step 2: Invoke the Agent

curl -X POST https://api.orq.ai/v2/agents/journey-plan-agent/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "What is happening in Budapest on the 26th and 27th of August this year?"
      }
    ]
  }
}'
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/password-helper-agent/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "Generate a 16-character password with numbers and symbols for my new database account"
      }
    ]
  }
}'

​
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/weather-analyst-1/responses \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "message": {
    "role": "user",
    "parts": [
      {
        "kind": "text",
        "text": "What is the current weather in Paris, France?"
      }
    ]
  }
}'