Custom agent

The Custom agent block (Agents) runs a configurable AI agent inside a workflow, with optional read-only Attio data, web access, and app tools.

The Custom agent block (Agents) runs a configurable AI agent inside a workflow, with optional read-only Attio data, web access, and app tools. You give it a prompt, a model, and a tool budget. It returns one free-text answer that you wire into later blocks. The agent starts with no context. It sees only what you pass in through variables and the tools you grant.

Category	Agents
Credit cost	Variable (token-based)
Engine	New Workflows engine (June 2026+)
Plan availability	Plans that include workflow automation
Limits	No documented rate, payload, or timeout caps. Tool access is read-only and gated by the “Run as” permission model. Output is not saved unless a later block writes it.

Inputs

Input	Type	Required	Default	Notes
Prompt	Text	Yes	None	The task for the agent. Pass record context in through variables, such as {{ steps.find_records.records }}.
System prompt	Text	No	None	Advanced role, rules, and tone instructions applied before the prompt.
Model	Single select	Yes	None	An OpenAI (GPT), Google (Gemini Flash, Gemini Pro), or Anthropic (Sonnet, Opus) model.
Tool access	Multi-select	No	None	Optional read-only Attio data, web access, and Model Context Protocol (MCP)-connected app tools.
Run as	Single select	Sometimes	None	The workspace member whose credentials, visibility, and connected app tools the agent uses.

Outputs

Output	Type	Example	Notes
Response	Text	Acme is a strong fit: enterprise SaaS, 400 employees, recent Series B.	The agent’s free-text answer. There is no structured field, so parse it downstream if you need fields.

Reference the agent’s answer in a later block as {{ steps.custom_agent.response }}.

Behavior

The agent runs once per workflow run and returns a single text response. It does not remember anything between runs. By default it cannot see any record, list entry, or note. It sees that data only when you pass it in through variables or grant a read-only tool.

Tool access is read-only and gated by the “Run as” permission model. The agent reads only what the chosen member can see, and it never writes to your workspace on its own. To turn on Attio data tools, web access, or MCP-connected app tools, the member named in Run as must first approve sharing. They do this through Share access in their Ask Attio settings. For any MCP tools, that member must also connect their own apps.

The response is not saved automatically. It lives only as a run variable, so it disappears after the run unless a later block stores it. To keep the answer, follow the agent with Update record or Update list entry and write it to a field.

Cost scales with tokens, not with a flat per-run fee. A long system prompt, a large block of passed-in context, and a verbose answer all raise the token count. More tokens mean a higher credit cost for a single run.

Gotchas

• The agent answers with nothing useful. The agent starts with no context. An empty or vague answer usually means you passed in no variables and granted no tools. Fix it by adding the records you need to the prompt, or by granting a read-only Attio tool through Run as.
• The response vanishes after the run. The output is a run variable, not a saved field. It is gone once the run ends. Add an Update record or Update list entry block and map {{ steps.custom_agent.response }} into a field.
• The agent sees more of the workspace than you intended. Granting Attio data tools exposes everything the Run as member can read, which can be the whole workspace. Choose the Run as member carefully, and grant only the tools the task needs.
• The run costs more than expected. With token-based pricing, large context and long answers cost more per run. Filter and trim what you pass in. Use Filter earlier in the workflow so the agent runs only when it should.
• The answer is hard to act on. The output is free text, not structured data, so branching on it is fragile. For a fixed set of categories, use Classify text or Classify record instead. You can also instruct the agent to answer with one exact word and branch with Switch.

Examples

Writing an account brief from notes and calls

A Record command on the Companies object passes the company into a Custom agent. The agent reads its notes and call recordings, then writes the result back to a field.

Field	Value
Model	Anthropic Sonnet
Run as	[e-mail]
Tool access	Attio data (read-only)
System prompt	You are a revenue analyst. Write a five-line account brief: status, key people, last touch, risks, next step.
Prompt	Write an account brief for {{ trigger.record.name }} using its notes and recent call recordings.

The agent returns a brief such as Acme: active renewal; champion Jane Lee (VP Ops); last call 3 days ago; risk: budget freeze; next step: send ROI deck.. An Update record block then stores it in the account_brief field.

Deciding the next action from mixed context

A Manual run feeds enriched lead data into a Custom agent that recommends one next action. A Switch block then routes on that answer.

{
  "model": "OpenAI GPT",
  "run_as": "[e-mail]",
  "tool_access": ["web access"],
  "system_prompt": "Reply with exactly one word: route, nurture, or disqualify.",
  "prompt": "Lead: [e-mail] at acme.com, 400 employees, enterprise SaaS, requested a demo. Decide the next action."
}

The agent returns route, and the downstream Switch block sends the lead to the enterprise sales path.

Credit cost worked example

The Custom agent block is priced on tokens. Cost per run depends on prompt size, passed-in context, granted tools, and answer length rather than on a flat fee. A short brief over a few notes costs far less than a long synthesis over a full account history.

To estimate spend, multiply your realistic per-run token cost by your monthly volume. Then compare that against your plan’s monthly credit allowance on Credits & pricing explained. Logic and lookup blocks are free, so you can run a Filter before the agent. That way only qualifying records reach the agent, which is the single biggest lever on token spend. Per-workflow credit caps were removed in the new engine, so monitor usage on the credits page rather than relying on a cap.

Source

Attio Workflows block library.

Last reviewed against the Attio Help Center, June 2026.

See also

• Web agent
• Classify text
• Summarize record
• Permissions & workflow access
• AI agents playbook