agentic-engagement

Agentic engagement

State: to-be-approved. Deploy-verified against a live workspace: not yet. Treat Done when below as the acceptance test and review cargo-ai cdk plan before deploying. Make no outcome claim for this skill until it is approved.

The outcome

A lead who replies to you gets an answer, on the same thread, from an agent that already knows what you sell. That is a conversation, not a sequence: one mailbox the workspace owns, one agent bound to it, a native email trigger that wakes the same chat when status becomes replied or unsubscribed, and a heartbeat that checks a thread that stayed at sent.

Three resources make the loop:

1. A sending domain. defineDomain is the inbox's home. The checked example adopts a domain already bought in the Cargo UI. Registering a new one charges workspace credits and is not refundable — a + create domain:… line in the plan is that purchase.
2. A mailbox on that domain. defineMailbox is the From address. It is a recurring monthly credit charge for as long as it exists. Domain, username and type are create-only: changing any of them destroys the inbox and puts a new one at the bottom of the send ramp.
3. An agent with agentNativeTrigger({ agentSlug: "email" }) and a heartbeat. The agent cannot call sendEmail itself, so a tool wraps it and pins the mailbox uuid. The trigger fires on replied and unsubscribed — inbound status. The heartbeat is the other half: silence has no event, so without it an unanswered first send is a dead chat. opened and interacted stay out of kinds; a tracking-pixel view is not a reason to write.

The first outbound is a separate invocation — a chat, or a play that calls the agent with a lead. This skill is the loop after that send. Without the native trigger a reply never comes back into the agent. Without the heartbeat a quiet thread never gets a status check.

Two failure modes worth knowing before you start. If the send-email tool takes the mailbox as an input, the agent can pick a different inbox and the trigger wakes the wrong chat. If the reply omits inReplyTo or passes only the parent Message-ID as references, mail clients break the thread and the next wake has no conversation to continue.

Put it in your project

This folder is a worked example: real CDK resources written for some other company. The job is to end up with the code your company would have written, in your project, and an agent does the adapting. If the cargo-cdk skill is in your session it carries the long form of this; if not, this is enough.

1. Install it — the CLI does the copy. From inside the CDK project, cargo-ai cdk add cookbook/agentic-engagement writes this example to infra/agentic-engagement/ and this procedure to .claude/skills/agentic-engagement/. No project yet? cargo-ai cdk init --cookbook agentic-engagement && cd && npm install does both; this folder never ships a shell. If you are reading this from the project's .claude/skills/, the install already happened — start at step 2. On a CLI too old to have add, copy this folder in as a sibling of what is there by hand; everything below is unchanged.
2. Reconcile it with what is already declared. For every domain, mailbox, LLM connector or folder this example carries that the project already has, rewire the imports to the existing one and drop the copy. Two resources with one slug is a collision at deploy. Append this folder's .env needs to the project's .env.example; never overwrite it.
3. Adapt. Work the sections below in order: What should not change is what you argue back about (say what breaks, then do it if they still want it); What you can change is what you offer unprompted (nobody asks for a variant they do not know exists); What you will be asked is the floor, and you derive before you ask. If you are asking more than about four questions you have skipped lookups. Record what you changed and why under a ## Decisions section in your copy of this file.
4. Plan, then stop. npm run check && cargo-ai cdk plan (check validates the resource tree offline; the blank template ships it). Show the diff. A + create mailbox:… line is a monthly charge, not a one-off — quote the live figure from cargo-ai mailboxManagement pricing get and get an explicit yes. Deploy only on that yes: cargo-ai cdk deploy. Never cdk init --force into a non-empty directory.
5. Verify. Walk Done when line by line and report each with evidence. Deployed cleanly and produced nothing is the normal failure — and the second normal failure is a first send whose reply never wakes the agent, so send one test thread to yourself before you call this done.

What you will be asked

Derive before you ask. An input with a lookup is looked up, not asked. Only the ones marked asked genuinely live in the operator's head.

Checked before moving on, not after the deploy:

• sendingDomain: the declaration matches a domain the workspace owns, or the plan's + create domain:… line was approved as a new registration
• dnsRecords is omitted unless the operator explicitly wants this file to own the whole zone
• mailboxIdentity: first name, last name and username are a real identity, and the username is a valid local part
• mailboxCharge: the plan's + create mailbox:… line was approved against a live pricing get
• node --import tsx evals/contract.mjs passes against the adapted graph

What you can change

The code is a worked example. These reshapes are expected, and the agent offers them rather than waiting to be asked. Every one costs something; that is what makes it a variation and not the default.

What should not change

However far you adapt, these hold. Ask for one anyway and the agent tells you what breaks, then does it if you still want it, and records why under ## Decisions in your copy of this file.

• The loop is the native email trigger plus the heartbeat. (infra/agents/engager.ts) Trigger kinds are replied and unsubscribed — inbound status. The heartbeat re-wakes a chat whose thread stayed at sent so the agent can check that status. A cron trigger, or kinds that include opened / interacted, either never continues the thread or writes when nobody asked. sendEmail wakes the chats this agent has emailed; a send from a play that bypasses the agent is invisible to it. Dropping the heartbeat makes silence a dead chat.
• The send-email tool pins the mailbox uuid. It is not a form field. (infra/tools/send-email.ts) An agent cannot call sendEmail directly. A tool that lets the agent pick a mailbox sends from an inbox the trigger is not watching, and the run looks successful.
• A reply carries inReplyTo and the full references chain, oldest first. (infra/agents/engager.prompt.ts) Passing only the parent Message-ID is how mail clients split the conversation. The next wake then has no thread to continue.
• Domain, username and type on the mailbox are create-only. (infra/mailboxes/rep.ts) Editing them in place is not an update. It is destroy plus a new inbox, back at five real sends a day, with a new address the lead does not know.
• dnsRecords is omitted unless this file is meant to own the zone. (infra/domains/outreach.ts) Declaring it replaces every live record, including the ones the registrar wrote at purchase.
• The From name is a real person. (infra/mailboxes/rep.ts) A fabricated sender is a refusal, not a configuration question.
• No credentials, deploy commands, or customer data in this repository.

Done when

• cargo-ai cdk plan reports the domain, the mailbox, the send-email tool and the engager, and the operator approved the monthly mailbox line against a live pricing get
• node --import tsx evals/contract.mjs passes: the agent trigger is native email with kinds: ["replied", "unsubscribed"], a heartbeat is declared whose prompt names status, the tool contains one sendEmail node, and mailboxUuid is not a form field
• the mailbox reaches active (cargo-ai mailboxManagement mailbox refresh-status) and warm-up has been started (mailbox start-warmup) so the send ramp can climb
• a first send to yourself delivers from the declared address
• a reply to that send wakes the engager without a human prompting it
• the agent's reply lands in the same thread in the mailbox (same subject, In-Reply-To set), not as a new conversation
• a second reply continues that same thread; an unsubscribe or "not interested" produces no further send
• an unanswered first send is still a live chat: the heartbeat is declared, and the agent treats that wake as a status check, not a sequence

What it costs

A mailbox is a monthly, recurring charge for as long as it exists. Immediately before the plan, run cargo-ai mailboxManagement pricing get and read monthlyCredits for the chosen type. Say that number out loud as a per-month cost, not a one-off. destroy is the only way it stops.

If the plan also shows + create domain:…, that registration is a separate, non-refundable charge. Adopting an existing domain does not.

Each delivery is a sendEmail native action. Run cargo-ai connection native-integration get (or orchestration action list sendEmail) for the current per-send cost. The engager adds one LLM turn per wake, including heartbeats. The per-thread cap is the cost control: one send per wake, at most one unanswered follow-up, and a stop when the lead closes.

A mailbox that never starts warm-up stays at the floor of five real sends a day. Starting warm-up is what moves the ramp; it takes forty-five days to finish. Check mailbox get-send-allowance before promising volume.

Composes into

account-scoring (the engager should be talking to accounts the scorer already ranked), call-capture (a conversation that becomes a meeting is a call worth scribing), crm-enrichment (the record the thread is about should already be filled).