# Launch an outreach agent

> Create an agent from a goal, give it targeting and a sequence, launch it, and confirm its first run found people.

Source: https://rivomi.com/docs/use-cases/launch-an-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 workspace [#1-read-the-workspace]

```
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 draft [#2-create-the-draft]

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 sequence [#3-write-the-sequence]

```
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. Launch [#4-launch]

```
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 run [#5-wait-for-the-first-run]

```
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 finds [#6-confirm-the-finds]

```
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](/use-cases/review-and-send).