Skip to main content
An agent is stored configuration: instructions, one model instance, and the tools and skills attached to it. Creating one does not start anything — an agent only runs when a task is submitted against it. Do this through the API when you are scripting or testing. The dashboard at /agents does the same thing with a form.

​
Prerequisites

  • A running platform — see Run AgentArea locally.
  • A provider configured and a model instance created — see choose a model. An agent references a model instance, never a provider or a bare model name.
  • An access token. All /v1 endpoints below require authentication.

​
Steps

1

Find a model instance

Note the id you want. This is the only hard dependency an agent has — a task against an agent whose model cannot be resolved fails at startup rather than falling back to another model.
2

Create the agent

Only name is required. Everything else has a default or is optional.
3

Attach tools

Tools reach an agent from five places — built-in toolsets, MCP servers, code tools, other agents, and OpenAPI connections. Attaching an MCP server is the common case and is covered in add a hosted MCP server.What the model is actually shown at each turn is narrower than what is attached: the resolved policy filters the list before the model sees it, and a denied tool is never offered. See tool authorization.
4

Choose a context strategy

Leave this alone unless you have a reason. The default is hybrid, resolved as agent override > model default > hybrid.Use dynamic when the attached tool set is large enough to crowd the context window. See context strategies.

​
Verify

Run a task and watch it reach a terminal event:
/sync blocks until the task finishes, which makes it the fastest way to tell a misconfigured agent from a working one. For the streaming and scheduled variants see start a task.

​
Troubleshooting

The agent’s model spec has no positive context_window . There is no default; the platform refuses to run against a guessed window.
A task needs a complete runtime policy — run budget, token ceilings, turn and tool-call limits — before it may start. New workspaces are seeded with defaults; a workspace whose rules were edited may be missing one. See policy syntax .
Check whether policy denies it. A denied tool is filtered out at disclosure, so the model never sees it and cannot report that it is missing.

What is an agent

An agent is a workspace-scoped definition

Start a task

Launch an agent run over REST, the CLI, or A2A

Attach skills

Create or import a skill and attach it to an agent so it is offered at runtime

Set a budget

Cap monthly spend, per-run spend, service spend or tokens for a workspace, agent, user or single
Last modified on September 17, 2026