Building an agent

• Header — the agent's name and description, the save status, and the YAML, Test, and Deploy buttons.
• Left — the Instructions editor.
• Right — four cards: Model, Input & Output, Configuration, and Tools.

Set a clear name and a short description in the header. They identify the agent everywhere it appears — in the agents list, in tool pickers, and in execution traces. The description matters more than it looks: when another agent (or Compass Chat) has this one as a tool, the description is what its model reads to decide when to call it.

Instructions are the agent's system prompt — the single most important setting. This is where you tell it what it does, how to behave, what to prioritize, and any rules to follow. The editor supports Markdown, so you can use headings, lists, and emphasis to structure longer prompts.

Good instructions are specific about the agent's job, its tone, and what a good result looks like. For example:

You are a concise support triage assistant. Given a customer message, classify its urgency, summarize the issue in one sentence, and suggest the next action. Never promise a refund.

To place the agent's input inside the instructions, write {{input}} where it should go; an object input is inserted as JSON. (Agents built on the canvas can declare more {{name}} parameters and bind each one — see Prompt parameters.)

Under Model, choose the provider connection the agent thinks with. Each option is a connection, shown with its provider and model (for example "Anthropic · claude-sonnet-4-6") — a connection runs one model, so picking the connection picks the model. Only active connections in this project whose model can generate text are listed.

If the card says No provider connected, add a provider connection first with Add →.

An agent's Input and Output each have two modes.

• Chat — free-form text. As an input, a message (plus any attached files); as an output, the agent's reply.
• Object — a structured shape whose fields you define. As an input, callers — a workflow, another agent, the API — pass named values. As an output, the agent returns a typed object whose fields downstream steps can read directly.

Click the fields button to open the field editor. Each field has a name, a type — String, Integer, Number, Boolean, Object, Array, or File (inputs only; see Files & attachments) — and a description. New input fields are required; toggle a field to Optional for anything a caller may leave out.

Use Object output whenever something downstream needs to read specific values out of the response rather than parse prose.

The Configuration card tunes how the agent runs. Its sampling controls appear once you've picked a model, because what's available depends on the model.

Sampling

• Temperature — higher is more varied and creative; lower is more focused and repeatable. The range comes from the provider: 0–1 for Anthropic, 0–2 for OpenAI and LM Studio.
• Top P (0–1) — an alternative way to control variability.
• Max tokens — a cap on how long a response can be. Leave it on Auto for the model's default.

Some models don't accept temperature or top P; for those the sliders read Not supported by this model, and the model's own defaults apply.

Reasoning

For models that can reason before answering, a Reasoning toggle appears. Turn it on and pick an effort level — the levels come from the provider (for example Low, Medium, High, Extra high for Anthropic; Minimal to High for OpenAI). More effort means more considered answers, and more tokens and time. Some models always reason and show Always on instead.

While reasoning is on, the model's reasoning summary appears above its answer in tests and chat, and in the trace. Some providers fix the sampling settings while reasoning — the sliders say so.

Harness

The Harness sets what Compass adds to the agent beyond what you configure:

• None (the default) — "Basic chat. The model runs as configured, with nothing added."
• Compass — "For working with Compass: your workflows, agents, connections, and runs."

On the Compass harness, the agent gets Compass's own tools, acting as the person who started the run: it can look up projects, executions and their traces, workflows and agents, components and integrations, connections, model providers, and datasets, and it can draft new workflows and agents or edit drafts — every change waits for approval, and it never deploys. Along with the tools, the agent is told how to use them, after your own instructions. It also keeps long runs in bounds: tools are found on demand once there are many, very large tool results are read a slice at a time, and older conversation is summarized as it grows.

These tools act as a person, so they're present when a person starts the run — in the Test panel, Compass Chat, or their own code. Runs from schedules, API keys, solutions, or a parent workflow get the harness without them, or the guidance on using them. This is the harness Compass Chat runs on.

Conversation History

Conversation History lets the agent see earlier turns of the conversation it's running in, so it can answer follow-ups in context. It applies when the agent runs on a conversation — in the Test panel, or from the API with a conversation_id. When the agent is called as a tool (including by Compass Chat) or as a workflow step, each call stands alone. Leave it off for one-shot tasks.

Batching

Run once per item of a list input fans the agent out — one call per item, in parallel, with an ordered list of results back. This has its own page:

→ Batching over a list

The Tools card is where you grant the agent the ability to act — call integrations, search datasets, run workflows, or hand off to other agents. This has its own page:

→ Giving agents tools

YAML opens the agent's definition. Copy or Download it to keep it in source control or recreate it elsewhere, or Upload a definition to replace the draft.

When you're happy with the agent, test it, then Deploy to freeze the draft into a numbered version and publish it live. The deploy dialog checks the agent first and lists anything that would stop it from running — a tool whose connection isn't set, for example. An agent with no model can still be deployed; connect one on the deployment's Connections panel before it runs. See Versioning & deployment.