API ReferenceAgent Configuration

Create Agent Builtin

Create a new builtin instance on this agent. builtin must resolve to one of the names returned by GET /v1/agents/tools/system-builtins; unknown values are rejected. name is the LLM-facing identifier the model uses to call the tool; it must match the tool-name regex and be unique within the agent’s builtin set.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Path parameters

idstringRequired

Request

This endpoint expects an object.
builtinstringRequired

Identifier of a worker-resident system builtin. New entries are added together on the server (a new tool_builtin_<name>.go file) and worker (tools/builtins/<name>.py) - the 2-file rule the server pins. Customers read the catalogue from GET /v1/agents/tools/system-builtins rather than depending on this string set staying stable across releases.

namestringRequired

LLM-facing tool name. Must match the tool-name regex and be unique within the agent’s builtin set.

descriptionstringOptional
configmap from strings to anyOptional

Per-instance configuration matching the per-builtin schema.

paramslist of maps from strings to anyOptional

Per-call parameter descriptors.

enabledbooleanOptional
Defaults to true on the server when omitted.

Response

The created builtin instance.
idstring
Opaque builtin instance ID.
tenant_idstring
The workspace owning this instance.
agent_idstring
The agent this instance is bound to.
builtinstring

Identifier of a worker-resident system builtin. New entries are added together on the server (a new tool_builtin_<name>.go file) and worker (tools/builtins/<name>.py) - the 2-file rule the server pins. Customers read the catalogue from GET /v1/agents/tools/system-builtins rather than depending on this string set staying stable across releases.

namestring

LLM-facing tool name. Unique within the agent’s builtin set.

descriptionstring

LLM-facing one-line description of when to call the tool.

enabledboolean
When false, the instance is persisted but skipped at dispatch.
created_atdatetime
updated_atdatetime
configmap from strings to any or null

Per-instance configuration shape. The schema depends on builtin — see the per-builtin contracts under /contracts/tools/system_*.schema.json. Null when the builtin takes no instance-level config.

paramslist of maps from strings to any or null

Per-call parameter schema fragment merged into the model’s tool spec. Each entry is one parameter descriptor (the per-builtin contract pins the exact shape). Null when the builtin takes no caller arguments.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error