Launch an outreach agent

Done when: the agent is live, its first run reports finished: true, and rivomi_search_prospects on its list_id returns people with scores.

Needs write. Launching spends credits, so confirm the plan with the user before step 4.

1. Read the workspaceCopy Anchor Link

rivomi_get_workspace {}
  → plan.credits_remaining, plan.spend_blocked, senders[], sending_consent.accepted

Stop here if spend_blocked is true: the run would find nobody. Note whether sending consent is accepted; it decides step 4.

2. Create the draftCopy Anchor Link

Pick one source from the user's goal. Keywords are the usual start: phrases their buyers write when they have the problem.

rivomi_create_agent {
  name: "RevOps leaders complaining about CRM data",
  source: {
    kind: "signals",
    keywords: ["CRM data is a mess", "cleaning up Salesforce"],
    competitors: ["https://www.linkedin.com/company/example-competitor/"],
    events: { hiring: true }
  },
  targeting: { titles: ["Head of RevOps", "VP Sales Operations"], company_sizes: ["51-200", "201-500"] },
  matching: "precise"
}
  → id, list_id, status: "draft", source.signals_watched

The agent is a draft: it finds nobody and sends nothing yet. Omit targeting to inherit the workspace's buyer segment. The call fails with not_configured when the workspace has no company profile. The user fills that in under Settings › Workspace.

Step complete when the response has an id and signals_watched is above zero.

3. Write the sequenceCopy Anchor Link

rivomi_update_agent_sequence {
  agent_id,
  steps: [
    { kind: "invite", note: "ai" },
    { kind: "message", delay_days: 2, text: "ai" },
    { kind: "message", delay_days: 4, text: "ai" }
  ],
  tone: "conversational",
  review_mode: true,
  daily_cap: 20
}

The rules: at most one invite, and only as the first step. Each message waits at least one day. Hand-written text may use {{firstName}}, {{company}} and {{title}}, and an invitation note must be 300 characters or less. Keep review_mode: true unless the user asks for full automation.

Step complete when the response echoes the steps you sent.

4. LaunchCopy Anchor Link

rivomi_set_agent_state { agent_id, state: "live", start_outreach: false }
  → status: "live", run_id

start_outreach: true also begins sending. It requires accepted sending consent, and with review mode on it still sends nobody until someone is approved. Launch with false, then turn outreach on once the user has seen the first finds.

5. Wait for the first runCopy Anchor Link

rivomi_get_run { run_id }   → finished, stats, cost

Poll every minute or two. A run usually takes several minutes.

Step complete when finished is true. If the run reports errors on a signal, the rest of the run still counts. Report the failed signal to the user.

6. Confirm the findsCopy Anchor Link

rivomi_search_prospects { list_id, sort: "score", limit: 10 }

Report to the user how many were found and how many qualified, and give the top few with their one-line reasons. Next: Review and send.