v1

latestOpenAPI 3.0.02026-08-04891301.4 MB

Create an agent tool

Creates a new tool and attaches it to the specified agent. Tools can be either "builtin" (a platform-provided capability identified by builtin_tool_key) or "custom" (a caller-defined tool with its own name, description, parameter schema, and handler).

New tools are created in "draft" status by default unless status: "active" is explicitly supplied. Draft tools are not exposed to the LLM during agent runs; call the activate endpoint to promote them.

For built-in tools that support multiple instances per agent (those whose catalog entry has a multi_instance_mode), supply name_prefix to namespace the LLM-facing tool names. Requires app scope.

post/api/v1/agents/{agent}/agent_tools

Path parameters

agentstring required

Agent ID (agt_...) to attach the tool to.

Request body

asyncboolean

When true, the tool executes asynchronously and the agent does not block waiting for a result. Applies to "custom" tools.

builtin_tool_configobject

Configuration object for the built-in tool. Shape is defined by the catalog entry's config_schema for the chosen builtin_tool_key. Applies only to "builtin" tools.

builtin_tool_keystring

Key identifying the built-in tool type to add (e.g. "knowledge_search"). Required when kind is "builtin". Must match a key in the tool catalog.

configstring

Config ID (cfg_...) referencing the script or workflow graph that implements the tool handler. Applies to "custom" tools.

descriptionstring

Human-readable description of what the tool does. Shown to the LLM as context. Applies primarily to "custom" tools.

handler_typestring

Execution handler for the tool. One of "script" or "workflow_graph". Applies to "custom" tools.

kindstring required

Tool kind. One of "builtin" or "custom".

lookup_keystring

Optional stable identifier you can use to look up this tool without its ID. Must be unique within the app. Useful for idempotent provisioning.

metadataobject

Arbitrary key-value metadata to attach to the tool. Not interpreted by the platform.

namestring

Display name for the tool. Required when kind is "custom".

name_prefixstring

Per-instance namespace for built-in tools that support multiple instances per agent. Stamped onto LLM-facing tool names (e.g. "org" produces "org_knowledge_search"). Must match ^[a-z][a-z0-9_]*$ and be at most 24 characters. Required for "namespaced" multi-instance tools; omit for single-instance tools.

parametersobject

JSON Schema object describing the tool's input parameters. Used by the LLM to construct valid tool calls. Applies to "custom" tools.

statusstring

Initial status of the tool. One of "draft" or "active". Defaults to "draft" when omitted.

Example request

{
  "async": true,
  "builtin_tool_config": {},
  "builtin_tool_key": "string",
  "config": "string",
  "description": "An example description.",
  "handler_type": "string",
  "kind": "string",
  "lookup_key": "string",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "name_prefix": "string",
  "parameters": {},
  "status": "string"
}

Response

Successful response

agentstring

ID of the agent this tool belongs to (agi_...).

appstring

ID of the application that owns this tool (dap_...).

asyncboolean

true when the tool executes asynchronously and returns a task handle rather than an immediate result.

builtin_tool_configobject

Provider-specific configuration for the built-in tool. Present only when kind is "builtin". Shape varies by builtin_tool_key.

builtin_tool_keystring

Registry key identifying the built-in tool implementation. Present only when kind is "builtin".

configstring

ID of the config record (cfg_...) containing this tool's full configuration. null for inline-only tools.

created_atstring date-time

When the tool was created (ISO 8601).

descriptionstring

Description of what the tool does, passed to the LLM as part of the tool definition. Resolved from the built-in registry for kind: "builtin" tools.

handler_typestring

Execution handler type. One of "http", "script", or "builtin".

idstring required

Tool ID (atl_...).

instructionstring

Optional system-level instruction appended to the agent prompt when this tool is active.

kindstring

Tool kind. One of "builtin", "custom", or "mcp".

last_applied_template_configstring

ID of the AgentToolTemplate config (cfg_...) this tool was last provisioned or updated from. null for manually created tools.

lookup_keystring

Stable, user-defined identifier for this tool within the agent. Unique per agent.

metadataobject

Arbitrary key-value metadata attached to the tool. Not interpreted by the platform.

namestring

Human-readable name of the tool as exposed to the LLM. Resolved from the built-in registry for kind: "builtin" tools.

name_prefixstring

Per-instance namespace prepended to LLM-facing tool names for built-in tools that support multiple instances per agent. null when not applicable.

parametersobject

JSON Schema object describing the tool's input parameters as presented to the LLM.

parameters_configstring

ID of the config record (cfg_...) storing the tool's parameter schema. null when parameters are defined inline.

statusstring

Current status of the tool. One of "active" or "disabled".

updated_atstring date-time

When the tool was last modified (ISO 8601).

Example response

{
  "agent": "agi_0aBcDeFgHiJkLmNoPqRsTu",
  "app": "dap_0aBcDeFgHiJkLmNoPqRsTu",
  "async": true,
  "builtin_tool_config": {},
  "builtin_tool_key": "string",
  "config": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
  "created_at": "2024-01-01T00:00:00Z",
  "description": "An example description.",
  "handler_type": "http",
  "id": "atl_0aBcDeFgHiJkLmNoPqRsTu",
  "instruction": "string",
  "kind": "builtin",
  "last_applied_template_config": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
  "lookup_key": "string",
  "metadata": {
    "key": "value"
  },
  "name": "Example Name",
  "name_prefix": "string",
  "parameters": {},
  "parameters_config": "cfg_0aBcDeFgHiJkLmNoPqRsTu",
  "status": "active",
  "updated_at": "2024-01-01T00:00:00Z"
}