Skip to content

Custom Tools

Custom Tools let you write Python functions and expose them as agent tools — without spinning up an MCP server. Upload a .py file, lock it to an agent, and the function is available in every workflow that uses that agent.


How it works

graph LR
    User -->|Upload .py file| API[POST /api/custom-tools]
    API -->|Validate + infer schema| DB[(MongoDB)]
    Agent -->|custom_tool_ids| DB
    Workflow --> Engine[Agent Engine]
    Engine -->|load custom tools| DB
    Engine -->|subprocess call| Runner[custom_tool_runner]
    Runner -->|JSON result| Engine
    Engine --> LLM
  1. You upload a Python source file (or paste source code directly).
  2. TBD Agents validates the function, infers a JSON Schema from its type hints, and stores everything in MongoDB.
  3. You lock the tool to an agent by adding its ID to custom_tool_ids.
  4. At runtime, the engine loads the enabled tools, adds them to the model's tool definitions, and routes tool_use events to the subprocess runner.

Writing a Custom Tool

A custom tool is a single Python function in a .py file. The filename stem becomes the tool name.

weather.py
import httpx

def weather(city: str, units: str = "metric") -> dict:
    """Return current weather for a city."""
    resp = httpx.get(
        "https://api.open-meteo.com/v1/forecast",
        params={"latitude": 0, "longitude": 0, "current_weather": True},
        timeout=10,
    )
    resp.raise_for_status()
    return resp.json()

Rules

Rule Detail
One function per file The function name must match the filename stem (e.g. weather.py → def weather)
Type annotations Parameters with Python type hints (str, int, float, bool, list, dict) have their JSON Schema inferred automatically. Unannotated parameters default to string.
Return value Return a dict (rendered as-is) or any JSON-serialisable value (wrapped as {"result": value}).
Async support Both def and async def are supported.
Imports Any package installed in the same virtual environment can be imported.
Timeout Execution is capped at 30 seconds.

Registering a Tool

curl -X POST http://localhost:8000/api/custom-tools/upload \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -F "file=@weather.py"

The tool name is derived from the filename (weather).

curl -X POST http://localhost:8000/api/custom-tools \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "weather",
    "description": "Fetch current weather for a city",
    "source_code": "def weather(city: str) -> dict:\n    return {\"city\": city, \"temp\": 22}",
    "tags": ["utility", "weather"]
  }'

Both routes validate the source code and infer the JSON Schema before saving.

Dashboard coverage

The current Flutter Custom Tools page focuses on operations and credential mapping: it lists bundled plugins and user-defined tools, shows enabled state, schema/parameter counts, environment requirements, and lets you map stored tokens to required environment variables. Creating, uploading, editing, and deleting custom Python tools are API workflows.

Response: 201 Created

{
  "id": "6601a1b2c3d4e5f607890abc",
  "name": "weather",
  "description": "Fetch current weather for a city",
  "parameters_schema": {
    "type": "object",
    "properties": {
      "city": {"type": "string"}
    },
    "required": ["city"]
  },
  "tags": ["utility", "weather"],
  "is_enabled": true,
  "created_at": "2026-04-21T07:10:00Z",
  "updated_at": "2026-04-21T07:10:00Z"
}

Validating Source Before Saving

Check whether source code is valid and see the inferred schema without persisting anything:

curl -X POST http://localhost:8000/api/custom-tools/validate \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "weather",
    "source_code": "def weather(city: str, units: str = \"metric\") -> dict:\n    return {\"city\": city}"
  }'
{
  "valid": true,
  "inferred_schema": {
    "type": "object",
    "properties": {
      "city":  {"type": "string"},
      "units": {"type": "string"}
    },
    "required": ["city"]
  },
  "error": null
}

Locking a Tool to an Agent

Add the tool ID(s) to custom_tool_ids when creating or updating an agent:

curl -X PUT http://localhost:8000/api/agents/<AGENT_ID> \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "custom_tool_ids": ["6601a1b2c3d4e5f607890abc"]
  }'

The tools are additive — they are merged with any MCP servers and built-in tools the agent already has.


Ad-hoc Testing

Run a tool against live arguments without a full workflow:

curl -X POST http://localhost:8000/api/custom-tools/<TOOL_ID>/run \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {"city": "London", "units": "metric"}
  }'
{
  "tool_name": "weather",
  "result": "{\"city\": \"London\", \"temp\": 18}",
  "success": true,
  "error": null
}

Disabled tools

Running a disabled tool returns 409 Conflict. Enable the tool with a PUT request first.


Managing Tools

List all tools

curl http://localhost:8000/api/custom-tools \
  -H "Authorization: Bearer $GITHUB_TOKEN"

Get a single tool

curl http://localhost:8000/api/custom-tools/<TOOL_ID> \
  -H "Authorization: Bearer $GITHUB_TOKEN"

Update a tool

curl -X PUT http://localhost:8000/api/custom-tools/<TOOL_ID> \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "Updated description",
    "is_enabled": false
  }'

Schema re-inference

If you update source_code or name, the schema is automatically re-inferred from the new function signature unless you explicitly provide parameters_schema.

Delete a tool

curl -X DELETE http://localhost:8000/api/custom-tools/<TOOL_ID> \
  -H "Authorization: Bearer $GITHUB_TOKEN"

Response: 204 No Content


Mapping Token-backed Environment Variables

Tools and bundled plugins can declare required environment variables through env_config. Use the API or the dashboard's MAP TOKENS action to map those variables to encrypted token names:

curl -X PUT http://localhost:8000/api/custom-tools/<TOOL_ID>/env-mapping \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "env_mapping": {
      "DATADOG_API_KEY": "datadog-api-key",
      "DATADOG_APP_KEY": "datadog-app-key"
    }
  }'

At runtime, the tool receives resolved environment variables without exposing token values in tool configuration or API responses.


Execution Model

Custom tools run in a sandboxed subprocess using the same Python interpreter as the main application:

  • Isolation — each call spawns a fresh subprocess; state does not persist between calls
  • Timeout — 30-second wall-clock limit; a {"error": "timed out"} is returned on expiry
  • Async — async def functions are executed via asyncio.run()
  • Imports — all packages in the application virtual environment are available
  • Error handling — uncaught exceptions are captured and returned as {"error": "<message>"}

Multi-tenant environments

For shared deployments, consider additional OS-level sandboxing (e.g. gVisor or seccomp) since custom tool executions can import arbitrary packages.


Execution Paths

Custom tools are injected into all three execution paths:

Path How tools are exposed
GitHub Copilot SDK Not natively supported — use MCP servers instead for Copilot SDK workflows. Custom tools on agents with provider_id=null are silently skipped.
BYOK / OpenAI-compatible Tools added to the tools array in OpenAI function-calling format. tool_calls responses are routed to the subprocess runner.
Claude Agent SDK Tools registered as custom type in the Claude agent definition. agent.custom_tool_use events are routed to the subprocess runner.

Example: Data Processing Tool

summarise_csv.py
import csv
import io
import statistics

def summarise_csv(csv_text: str, column: str) -> dict:
    """Compute basic statistics for a numeric column in a CSV string."""
    reader = csv.DictReader(io.StringIO(csv_text))
    values = []
    for row in reader:
        try:
            values.append(float(row[column]))
        except (KeyError, ValueError):
            pass
    if not values:
        return {"error": f"No numeric data found in column '{column}'"}
    return {
        "column": column,
        "count": len(values),
        "mean": round(statistics.mean(values), 4),
        "median": round(statistics.median(values), 4),
        "stdev": round(statistics.stdev(values), 4) if len(values) > 1 else 0,
        "min": min(values),
        "max": max(values),
    }

Register and test:

# Upload
curl -X POST http://localhost:8000/api/custom-tools/upload \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -F "file=@summarise_csv.py"

# Test
curl -X POST http://localhost:8000/api/custom-tools/<TOOL_ID>/run \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {
      "csv_text": "name,score\nalice,92\nbob,87\ncarol,95",
      "column": "score"
    }
  }'

Custom Tools vs MCP Servers

Custom Tools MCP Servers
Setup Upload a .py file Run a separate server process
Language Python only Any language
Isolation Subprocess per call Separate process
Schema Auto-inferred from type hints Declared by the MCP server
State Stateless Can be stateful
Best for Quick utilities, data transforms, API wrappers Complex integrations, shared tool infrastructure