Components and tools

Agents are assembled from components. Each component is stored once in the registry and can be reused by many agents.

Component types

Type	Purpose	Example
`agent`	An AI agent that reasons and acts	A support assistant
`team`	Several agents that work together	A specialist team that handles escalations
`model`	The language model an agent uses	A general-purpose chat model
`tool`	A single function an agent can call	Look up the current date
`toolbox`	A collection of tools generated from an OpenAPI description of a REST API	Tools for a ticketing system
`workbench`	A connection to a remote tool server using the Model Context Protocol (MCP)	An external data service
`tokenprovider`	Authentication for toolboxes and workbenches	Sign in to an external API
`context`	Instructions and guidelines	Tone of voice, rules to follow
`chat_completion_context`	How much conversation history an agent keeps	Keep the first and the latest messages
`handoff`	A transition between agents, or back to the user	Escalate to a specialist
`termination`	A condition that ends a team conversation	Stop after a maximum number of messages

Kinds of tools

Tools let an agent do more than write text: look up data, calculate, or trigger an action in another system.

Kind	Where it runs	When to use it
Built-in tool	In the service	Common tasks such as search or calculation, see below
OpenAPI toolbox	The service calls your API	Your system already has a REST API described with OpenAPI. See OpenAPI toolboxes.
MCP workbench	The service calls your MCP server	Your system offers its tools through the Model Context Protocol. See MCP workbenches.
External tool	Your application	The action must happen in your application, for example showing a form. See External tools.

Toolboxes and workbenches can authenticate against your systems with a token provider. Store the credentials it needs as secrets.

For tools that change data, such as creating an order or posting a booking, you can require that the user approves each call. See Human-in-the-loop.

Built-in tools

The service includes general-purpose tools that agents can use. To connect your systems, use an OpenAPI toolbox or an MCP workbench.

Tool	What it does
Date and time	Returns the current date and time
Calculator	Calculates expressions, sums, counts, percentages and grouped totals
Knowledge search	Searches your datasources semantically, with optional metadata filters or hybrid search. See Knowledge and Search.

Agents built for specific customers often use additional tools that are tailored to their systems. Contact Support to find out which tools are available for your tenant.

OpenAPI toolboxes

A toolbox turns a REST API into tools. The service reads the API’s OpenAPI description and creates one tool per operation. The tool name is taken from the operation’s operationId.

{
  "id": "ticketing",
  "name": "Ticketing API",
  "component_type": "toolbox",
  "provider": "${PROVIDER}",
  "config": {
    "url_or_spec": "https://tickets.example.com/openapi.json",
    "base_url_fallback": "${TICKET_API_URL}",
    "token_provider": { "ref": "tokenprovider/ticketing-auth" },
    "allowed_operations": {
      "GET": ["list_tickets", "get_ticket"],
      "POST": ["create_ticket"]
    },
    "requires_confirmation": ["create_ticket"],
    "timeout": 30
  }
}

Field	Meaning
`url_or_spec`	URL of the OpenAPI description, or the description itself as JSON
`base_url_fallback`	Base URL of the API, used if the description has no absolute server URL or lists several servers
`token_provider`	Optional reference to a token provider for authentication
`custom_headers`	Optional headers sent with every request
`allowed_operations`	Operations the agent may call, grouped by HTTP method. Without this field, only `GET` operations are allowed.
`requires_confirmation`	Operations the user must approve before they run
`tags_filter`	Optional list of OpenAPI tags. Only operations with one of these tags become tools.
`path_filter_regex`	Optional regular expression. Only operations with a matching path become tools.
`timeout`	Request timeout in seconds

MCP workbenches

A workbench connects an agent to a remote server that uses the Model Context Protocol (MCP). The agent can use all tools that the server offers. The server must be reachable over HTTP.

{
  "id": "data-service",
  "name": "Data service",
  "component_type": "workbench",
  "provider": "${PROVIDER}",
  "config": {
    "server_params": {
      "type": "StreamableHttpServerParams",
      "url": "https://mcp.example.com/mcp",
      "timeout": 30,
      "sse_read_timeout": 300
    },
    "token_provider": { "ref": "tokenprovider/data-service-auth" }
  }
}

Field	Meaning
`server_params.url`	URL of the MCP server
`server_params.headers`	Optional headers sent with every request
`server_params.timeout`	Connection timeout in seconds
`server_params.sse_read_timeout`	How long to wait for streamed results, in seconds
`token_provider`	Optional reference to a token provider. Its token is sent in the `Authorization` header.

How components reference each other

Components refer to other components with a ref in the format {component_type}/{component_id}:

{
  "model_client": { "ref": "model/my-model" },
  "tools": [{ "ref": "tool/calculator" }, { "ref": "tool/search-manuals" }]
}

A referenced component must exist before it is used.
A component cannot be deleted while another component references it.
Circular references are rejected. Handoffs in both directions between two agents are allowed.

Create an agent

All registry requests need the headers described in Request basics and the service operator role. ${RUNTIME_BASE_URL} stands for the Agent Runtime URL of your environment.

POST ${RUNTIME_BASE_URL}/v1/components/agent
Content-Type: application/json

{
  "id": "support-agent",
  "name": "Customer Support Agent",
  "component_type": "agent",
  "description": "Handles customer inquiries",
  "provider": "${PROVIDER}",
  "config": {
    "name": "support_agent",
    "description": "Customer support assistant",
    "model_client": { "ref": "model/my-model" },
    "tools": [{ "ref": "tool/search-manuals" }],
    "system_message": "You are a helpful support agent."
  }
}

Field	Meaning
`id`	Unique ID of the component
`name`	Display name. Any characters are allowed.
`provider`	The implementation behind the component. Contact Support for the provider values available to your tenant.
`config.name`	Technical name of the agent, used as target for handoffs and in teams
`config.system_message`	The instructions for the agent, as text or as a reference to a context component. See Reusable instructions.

See Metadata and descriptions for how to write descriptions and instructions that work well.

Reusable instructions

Instead of writing the instructions into the agent, store them in a context component and reference it in system_message. Several agents can then share the same instructions.

A context can also call tools when the agent is loaded and insert their results into the instructions, for example the current date or values from one of your systems. The tools run every time, without the language model deciding to call them:

{
  "id": "support-instructions",
  "name": "Support instructions",
  "component_type": "context",
  "provider": "${PROVIDER}",
  "config": {
    "content": [
      "Current date and time: {{ get_datetime() }}",
      "You are a helpful support agent."
    ],
    "env": {
      "get_datetime": { "ref": "tool/get-local-date-time" }
    },
    "sep": "\n"
  }
}

Field	Meaning
`content`	Parts of the instructions. `{{ name() }}` calls the tool `name` from `env` and inserts its result.
`env`	Tools and values that `content` can use
`sep`	Separator between the parts of `content`

The agent then references the context:

"system_message": { "ref": "context/support-instructions" }

Teams and handoffs

A team lets several agents work on one conversation. Each agent can hand the conversation over to another agent, or back to the user, through a handoff. A team always needs a termination condition, for example a maximum number of messages, so that a conversation cannot run forever.

Handoffs are configured on the agents, not on the team. A handoff target is the technical name (config.name) of an agent, or user.

Recommended order of creation

Token providers, then toolboxes
Models, tools, contexts and workbenches
Termination conditions
Agents
Handoffs, then update the agents that use them
Teams
Environments
Deployments