Run your AI agent on contacts

Most agents live inside conversations: they read a message thread and reply, draft, or add a note. But some jobs aren't about a conversation at all — they're about the contact. Looking up what a new lead's company does. Qualifying whether an enquiry is a business or a consumer. Enriching a contact with firmographics before sales ever opens the thread.

For those jobs, an agent can now run on a contact instead of a conversation. Every agent has a Runs on setting: Conversations (the default — nothing changes for your existing agents) or Contacts.

What a contact agent does

A contact agent runs against the contact record itself — no conversation is opened, and nothing is ever sent to the customer. It reads the contact's details, does its work (searching the web, calling your systems, updating attributes, recording events), and saves its findings as a note on the contact, authored by the agent. You'll find these notes on the contact page under Notes.

If you set a Response Tag, the agent only saves a note when its response includes that tag — useful for conditional research like "only write up business contacts; stay silent for consumer email addresses". A silent run isn't a failure: the agent simply decided there was nothing worth noting, and any actions it took still count.

What the agent sees

A contact agent always receives the contact's name, email, and phone. Under Contact Context on the agent's Capabilities tab, you choose what else it sees:

• Contact Attributes — custom and marketing attributes stored on the contact.
• Recent Events — the contact's latest tracked events (e.g. request_quote, place_order).
• Contact Notes — the most recent notes your team (or other agents) saved on the contact.

All three are on by default. Turn one off when it isn't relevant — a pure company-lookup agent doesn't need to re-read old notes on every run.

Contact agents keep File Search and Web Search, so they can ground their research in your knowledge base or the live web.

Ways to run one

1. From the contact page — every contact page shows an agent picker (the sparkles button) when your team has contact agents. Pick the agent and its note appears in the Notes tab moments later.
2. Automatically on new contacts — turn on Auto-trigger and the agent runs whenever a new contact is created, whatever the source: an inbound email from an unknown sender, a website chat visitor, or your systems calling the API. Because each run calls the AI, keep this on only for agents you want on every new contact.
3. From a workflow — the Trigger Agent step accepts contact agents. The step needs no inbox or channel; you choose whether it saves a contact note or runs actions only (no note), and the step's instructions support variables like {{contact.name}}, {{event.PROPERTY}}, and {{response.KEY}} from earlier webhook steps. Combine it with the Contact is created or Contact is updated workflow triggers to research contacts the moment they appear — or the moment an email address lands on them (the contact_updated event's changed property tells you what changed, and agent-made updates never re-trigger the workflow).

Every run is logged

Contact runs appear in the agent's Logs page just like conversation runs: each run shows its status, duration, how it was triggered (manual or automatic), the note it produced, and a timeline of every action it took — with a View Contact link straight to the contact where conversation runs link to the conversation.

Which actions contact agents can use

Because there's no conversation in play, contact agents get the contact-scoped subset of agent actions:

• Update contact details — name, email, phone, and attributes. Attributes written by the agent land in the contact's marketing attributes, so segments and workflows react to them immediately — an agent that sets industry: legal can drive a "law firms" segment with no extra wiring.
• Record event — record events like b2b_qualified or enquiry on the contact, which can trigger workflows of their own.
• Webhooks and Zapier — call your own systems as usual. Use {{contact.*}} placeholders; conversation placeholders don't apply.

Conversation actions (status, tags, move to inbox, assign) aren't offered — there's no conversation to act on. The action picker and the AI action helper both understand this and only propose actions the agent can actually use.

A worked example

A translation agency wants to know which enquiries are businesses:

1. Create an agent, set Runs on to Contacts, give it Web Search, and instruct it: "From the contact's email domain, research the company. If it's a business, summarise what they do, their size, and likely translation needs inside <company> tags. If it's a personal email address, respond without the tag."
2. Set the Response Tag to company and add an Update contact details action (attributes) plus a Record event action allowing b2b_qualified.
3. Turn on Auto-trigger, or wire it into a contact_created workflow.

Every new business contact arrives pre-researched: a note on the contact, industry/company_size attributes for segments, and a b2b_qualified event your sales workflow can trigger on. Consumer contacts stay untouched.

For setting up actions, see Let your AI agent take action. For triggering agents from journeys, see Workflows.