Custom Tools

Audience: Developers

Custom Tools (API & MCP)

GL Open DeepResearch provides native support for dynamically extending the agent's capabilities using Custom Tools. Instead of writing Python code, you can register HTTP integrations (API Tools) or Model Context Protocol servers (MCP Tools) directly via the API. Once registered, these tools can be attached to any Profile.

---

1. Types of Custom Tools

API Tools (api_config)

API Tools allow the agent to make HTTP queries to external or internal systems (e.g. searching a database, triggering a webhook, or querying a specialized service). The agent is provided with the parameter schema and autonomously decides when and how to call the API.

Key Features:

• Support for GET, POST, PUT, PATCH, DELETE.

• Dynamic Request Bodies: Use {{param_name}} templates in the request_body payload to dynamically inject the agent's parameters into nested JSON structures.

• Response Extraction: Use extract_fields to specify dot-notation JSON paths to isolate the exact data the agent needs, ignoring bloated API responses.

• Authentication: Built-in secure support for api-key, bearer-token, and basic auth.

MCP Tools (mcp_config)

Model Context Protocol (MCP) is an open standard for securely connecting AI models to data sources. Registering an MCP server allows the agent to automatically discover and use all the sub-tools exposed by that server.

Key Features:

• Supports both sse (Server-Sent Events) and stdio transports.

• Sub-tool filtering via allowed_tools.

• Automatic negotiation of tool schemas directly from the MCP Server.

At runtime, mcp_config in the research request may use UUID keys (registered configs) or custom name keys (inline servers). Inline name keys are honored only if the selected profile has params.allow_inject_mcp_server: true; otherwise the API returns a validation error.

---

2. Managing Custom Tools

You can govern Custom Tools via the REST API endpoints. See the detailed schemas in the API Contract - Tools.

Example: Creating an API Tool

curl -X POST "http://localhost:8000/v1/tools/api" \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "company_directory_search",
    "description": "Search the internal employee directory by name or department.",
    "method": "POST",
    "url": "https://api.internal/v1/search",
    "parameters": [
      { "name": "query_string", "type": "string", "required": true }
    ],
    "request_body": {
      "filters": {
        "query": "{{query_string}}"
      }
    },
    "extract_fields": ["data.results"],
    "authentication": {
      "type": "api-key",
      "key": "x-api-key",
      "value": "secret-token"
    }
  }'

The response will include the unique id (UUID) for this tool.

---

3. Attaching Tools to a Profile

To make the tool available to the deep research agent, you must add the tool's UUID to the params.tools list within a Profile.

{
  "name": "HR_RESEARCHER",
  "provider": "tongyi",
  "params": {
    "model": "qwen-max",
    "tools": [
      "fetch_web_page",
      "c280ab14-8c7e-40bf-8afc-5c17ddc86597" // <-- ID of the custom tool
    ]
  }
}

Whenever a task is launched using the HR_RESEARCHER profile, the agent will have the ability to call the company_directory_search tool dynamically.

---

4. Runtime Configurations (Overriding Tools per Request)

In many production environments, you may not want to store sensitive authentication tokens (like user-specific OAuth tokens) globally in the database.

GL Open DeepResearch allows you to securely inject or override tool configurations at runtime when creating a Task or Taskgroup. You can pass the api_config or mcp_config maps in the POST /v1/tasks or POST /v1/taskgroups payloads.

The key in the map must match the tool's UUID.

Example: Supplying User-Specific Auth at Runtime

Python

from gl_odr import DeepResearchClient

client = DeepResearchClient(api_key="your-api-key")

task = client.tasks.create(
    query="Find the contact info for the VP of Engineering",
    profile="HR_RESEARCHER",
    api_config={
        "c280ab14-8c7e-40bf-8afc-5c17ddc86597": {
            "url": "https://api.internal/v1/search",
            "authentication": {
                "type": "bearer-token",
                "token": "user-specific-oauth-token-12345"
            }
        }
    }
)

cURL

This ensures the agent performs the tool call perfectly scoped to the permissions of the user initiating the task, without ever persisting their token in the system configurations!