Skip to main content
POST
/
api
/
v1
/
agent
/
{agent_id}
/
tools
Register Tool
curl --request POST \
  --url https://api.example.com/api/v1/agent/{agent_id}/tools

​
Path Parameters

ParameterTypeDescription
agent_idstringThe agent’s unique identifier

​
Request Body

Send a ToolRegistrationRequest with the tool code and any registration options. function_code may define a sync or async Python function; async functions are awaited by the runtime. In the Python SDK, use client.agents.tools.create(agent_id, ...) for this source-backed registration contract. 
{
  "name": "calculate_roi",
  "description": "Calculate return on investment with an annualized rate.",
  "function_code": "async def calculate_roi(investment: float, returns: float, period_months: int) -> dict:\n    roi = (returns - investment) / investment\n    annualized = (1 + roi) ** (12 / period_months) - 1\n    return {'roi_percentage': round(roi * 100, 2), 'annualized_rate': round(annualized * 100, 2)}",
  "tags": ["finance", "analytics"],
  "group": "Analytics",
  "args_schema": {
    "type": "object",
    "properties": {
      "investment": { "type": "number" },
      "returns": { "type": "number" },
      "period_months": { "type": "integer" }
    },
    "required": ["investment", "returns", "period_months"]
  },
  "require_approval": false,
  "secure_execution": true,
  "execution_timeout": 10
}
FieldTypeRequiredDescription
namestringyesTool name used by agents and direct execution
descriptionstringyesHuman-readable tool description
function_codestringyesPython function source for the tool
parametersobjectnoOptional parameter metadata
tagsstring[]noTool tags for filtering and display
groupstringnoUI grouping label
icon, icon_type, icon_color, icon_variantstringnoOptional visual metadata
require_approvalbooleannoRequire approval before execution
args_schemaobjectnoJSON schema for tool arguments
param_descriptionsobjectnoPer-parameter descriptions
secure_executionbooleannoRun the tool in secure execution mode; defaults to true
execution_timeoutnumbernoTool timeout in seconds
target_sub_agent_idstringnoAlso attach the tool to a sub-agent
target_agent_idsstring[]noAlso attach the tool to additional agents
llm_usageobjectnoOptional LLM usage configuration for the tool
credentialsobjectnoOptional credential configuration
Tool registration requires a bearer token with permission to administer tools for the target agent. Registered tools are persisted and assigned to the agent durably.

​
Response

Returns 200 OK with the persisted tool identifiers. 
{
  "message": "Tool 'calculate_roi' registered successfully with agent 'agent_abc123'",
  "tool_id": "tool_456",
  "persisted_tool_id": "tool_456",
  "persisted": true
}
tool_id is the canonical persisted identifier. Use it for updates, deletes, approval configuration, and direct execution; name-based lookup remains supported for compatibility.