H2h2o
Agents

Add Custom Agent Tools

Add Custom Agent Tools

post/agents/custom_tools

Request

Request body multipart/form-data

filestring binary nullable

The tool file to upload. Requirements vary by tool_type:

  • local_mcp: .zip file containing MCP server code
  • remote_mcp: Optional configuration file — any extension accepted (common: .json, .yml, .yaml, .py, .zip, .toml, .ini, .conf, .config, .env, .txt)
  • browser_action: .py file (must start with 'browser_') or .zip containing browser action scripts
  • general_code: .py or .zip file with custom code
tool_type'local_mcp' | 'remote_mcp' | 'browser_action' | 'general_code' required

The type of custom tool being added:

  • local_mcp: Model Context Protocol server running locally
  • remote_mcp: Model Context Protocol server running remotely
  • browser_action: Custom browser automation actions
  • general_code: General purpose code execution tools
tool_argsstring required

JSON string containing tool-specific arguments. The structure varies by tool_type:

For remote_mcp: { "mcp_config_json": "JSON string with MCP server configuration", "enable_by_default": true/false (optional, defaults to true) }

For local_mcp, browser_action, and general_code: { "tool_name": "string (optional, defaults to filename without extension)", "description": "string (optional, tool description)", "enable_by_default": true/false (optional, defaults to true), "should_unzip": true/false (optional, for general_code .zip files only), "tool_usage_mode": ["runner", "creator"] (optional list of strings), "system_prompt": "string (automatically added when generate_system_prompt=true)" }

custom_tool_pathstring nullable
filenamestring nullable

Optional filename to use when storing the uploaded file

generate_system_promptboolean nullable

If true and tool_type is "general_code", generates a system prompt for the tool using LLM analysis. The generated system prompt will be automatically added to tool_args["system_prompt"] after generation completes. Only valid for general_code tool type.

WARNING: This is a long-running synchronous operation. The server holds the HTTP connection open while the LLM analyzes the uploaded code. Ensure your HTTP client timeout and any intermediate proxies (nginx, ALB, Cloudflare, etc.) are configured with sufficient timeout. Default proxy timeouts of 60-120s will cause 504 Gateway Timeout errors. See system_prompt_generation_timeout to constrain the wait budget on the server side.

system_prompt_generation_timeoutnumber double nullable

Optional wait budget in seconds for synchronous system prompt generation (only used when generate_system_prompt is true). Set this below your proxy/ingress read timeout so the API returns a 408 instead of letting the proxy emit a 504. If omitted, defaults to the server-side cap of 600 seconds (10 minutes).

Example request

{
  "tool_args": "{\"tool_name\": \"my_tool\", \"description\": \"My custom tool\", \"enable_by_default\": true}"
}

Response

Custom agent tool created successfully

agent_custom_tool_idstring

The ID of the created custom agent tool

Changes

No recorded changes to this operation across all 1 revision of this API.