AI agents playbook

AI agent blocks make judgment calls inside a workflow. Use them only where plain logic blocks cannot decide, and watch their token cost.

AI agent blocks make judgment calls inside a workflow. Use them only where plain logic blocks cannot decide, and watch their token cost. An agent block sends your data to a large language model and gets back a written answer. Attio ships two of them. The Web agent block researches a record across the public web. The Custom agent block runs a configurable agent. It can read your Attio data (read-only), search the web, and call outside tools. Those tools connect over the Model Context Protocol (MCP), a standard way to plug tools into an agent.

Both blocks are powerful because they reason over messy input. Both are risky for the same reason. Their cost is variable, and their answer is not guaranteed to be the same every time.

This playbook gives you four things. It gives you the rule for when to reach for an agent. It gives you a prompt structure that returns answers you can actually use. It gives you the step that saves an answer so it sticks to a record. And it gives you the cost discipline that stops a busy trigger from quietly draining your credit balance.

After reading it, you can decide whether a task belongs to an agent or to a free logic block. You can write a prompt that returns clean fields you can map into attributes. And you can ship an agent workflow whose per-run cost you have already measured.

When to reach for an agent

An agent costs tokens, and that cost varies from run to run. It earns that cost only when cheaper, predictable blocks cannot produce the answer. Reach for the Web agent or Custom agent block when every one of these is true:

• The input is unstructured text or public web context. No Filter or Formula block can read it reliably.
• A fixed rule would be brittle. The signal lives in nuance, not in a single field value.
• A correct answer is worth more than the tokens it costs to produce.
• A human can live with the occasional uncertain or wrong answer downstream.

When to use a cheaper block instead

A logic, math, or lookup block is faster, free, and predictable. Prefer it whenever it can decide the answer on its own. Skip the agent and reach for one of these deterministic blocks when any of these is true:

• A Filter, Formula, or Find records block can produce the answer from data you already have.
• The workflow runs at high volume. Token cost adds up across every run.
• The result changes a customer-facing message and no human reviews it first.
• The source the agent would need is private, login-gated, or unreliable. The Web agent block cannot read it.

The Classify record, Classify text, and Summarize record blocks sit between these two extremes. They are AI blocks, so they too carry a variable token cost. But their job is narrow and their output is tightly constrained. They are often the right middle choice before you reach for a full agent.

Writing a prompt that returns usable fields

A good agent prompt does three things. It names the role the agent plays, it limits the evidence the agent may use, and it demands a fixed output shape. That fixed shape is what lets you map each part of the answer into a separate attribute downstream.

Ask for the exact fields you plan to save. Tell the agent to admit uncertainty rather than invent a value.

The prompt below qualifies an inbound account. It returns four labeled parts you can map one-to-one into text attributes. It also tells the agent to write unknown instead of guessing.

You are helping a B2B revenue team qualify an account.

Use only the provided record data and web evidence you can verify.
Return:
1. concise summary
2. qualification signal
3. uncertainty or missing evidence
4. recommended next action

If you cannot verify a claim, say "unknown".

Run this on an account such as acme.com with owner Priya Sharma. The agent returns a short summary paragraph, a qualification signal such as Strong fit, a plain note of what it could not verify, and a recommended next action. Each of those four parts becomes the value of a separate attribute in the next step.

Choosing a model

The Custom agent block lets you pick the model that runs the prompt. Attio offers OpenAI’s GPT, Anthropic’s Sonnet and Opus, and Google’s Gemini Flash and Gemini Pro. A faster, cheaper model handles classification and short summaries well. A stronger model costs more per token. Use it only on synthesis tasks, where better reasoning changes the answer.

Saving the output so it persists

An agent does not write to a record on its own. The answer it returns lives only inside the run. So an agent step by itself changes nothing in your data. To keep the answer, follow the agent with a write block and map each returned field into an attribute. Skip that step and the answer disappears when the run ends.

1. Add the agent block

   Place the Web agent or Custom agent block after your trigger and any filtering. Configure its questions or prompt to return the exact fields you intend to store.

2. Add a write block after it

   Add an Update record block for a record, or an Update list entry block for a list entry. The agent block must run before the write block so its output is available.

3. Map each answer into an attribute

   In the write block, set each target text attribute to the matching part of the agent’s response. For the qualification prompt, map the summary into a Research notes attribute and the qualification signal into an ICP fit attribute.

After this, a run on acme.com writes the agent’s summary and qualification signal onto the company record. The rest of the team can then read them. Without the write block, the same run produces an answer that no one ever sees.

Giving an agent tool access can expose a lot of workspace data. The agent reads data as someone, so it sees whatever that identity can see. Agent tool access is read-only, controlled by the “Run as” permission model. An agent running as the workflow reads workspace-visible data plus whatever the workflow can read. An agent running as a member reads everything that member can access. Default to running as the workflow with the fewest tools enabled. For the full model, see Permissions & workflow access.

Controlling token cost before you publish

Agent blocks carry a variable, token-based credit cost. A careless trigger can spend far more than a fixed-cost block ever would. Three habits keep that cost bounded. They are listed here from most effective to least.

1. Filter before the agent, never after

   Put a free Filter block ahead of the agent. Only records that pass the filter reach it. Every record that touches the agent costs tokens, and the free filter does the gatekeeping for nothing.

2. Trim the prompt surface

   Ask the Web agent block fewer, sharper questions. Give the Custom agent block tighter instructions. Fewer questions and shorter context mean fewer tokens per run.

3. Measure ten representative runs

   Run the workflow on ten representative records and read the per-run credit cost in the run viewer. Use that figure to decide whether the agent triggers on every new record or only on a filtered subset.

Per-workflow credit caps were removed in the new engine. So there is no cap to fall back on when a trigger fires more often than you expected. Measuring before you publish is the only guard. For the full cost model and plan allowances, see Credits & pricing explained. The AI ICP-fit research and routing recipe walks through a complete agent build with these guards in place.

Sources: Attio Workflows block library, Manage workspace and seat credits. Last reviewed against the Attio Help Center, June 2026.

See also

• Web agent
• Custom agent
• Permissions & workflow access
• AI ICP-fit research and routing
• Credits & pricing explained