Agents overview
What an agent is, what it does at runtime, and when to build one instead of a workflow.
An agent is a single AI worker. You give it written instructions, choose a model, and attach the tools it's allowed to use. At runtime it reads its input, reasons about what to do, calls its tools as needed, and produces a result — either free-form text or a structured object you define.
Agents are built in the agent builder, a focused form under Studio → Agents. Behind the form, every agent is a definition you can view, copy, or upload as YAML from the builder's YAML button — so agents can also be created from the CLI or SDK.
What an agent does at runtime
When an agent runs, it:
- Takes its input — a chat message or a structured object.
- Follows its instructions (its system prompt) using its model, reasoning first if you've turned reasoning on.
- Decides whether to call any of its tools, and does so, possibly several times.
- Returns its output.
Every one of those steps is recorded in the execution's trace, so you can always see what the agent did and why.
Agents and workflows
Agents and workflows are the two ways to build in Compass, and they're peers — neither is the "advanced" version of the other. They're built differently and suited to different jobs:
| Agent | Workflow | |
|---|---|---|
| Built in | A form (the agent builder) | A visual canvas |
| Shape | One AI worker with tools | A graph of steps you wire together |
| Best for | Letting a model decide how to use its tools | Defining explicit steps and the order they run in |
They also work together: a workflow can include an agent as a step, and an agent can call a workflow as one of its tools. Reach for an agent when a single well-instructed model with the right tools can do the job; reach for a workflow when you want to lay out the steps yourself.
What you configure
An agent is defined by a handful of settings, all in the builder:
- Instructions — what it does and how it should behave.
- Model — the provider connection it thinks with.
- Input & output — free-form chat or a structured shape you define.
- Configuration — sampling settings, reasoning, the harness, conversation memory, approvals, and batching.
- Tools — the integrations, workflows, and other agents it may call.
The next page walks through each one.
Where agents run
A deployed agent can be run by a schedule, from your code, as a step in a workflow, or as a tool of another agent — including Compass Chat, which can call any agent you add to its Tools.