> ## Documentation Index
> Fetch the complete documentation index at: https://api.lawtte.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Builder for AI agents

> How an AI agent or MCP client builds, launches and changes a law firm's email, text and call agents through Lawtte's MCP server: tool order, the recipe formats, ids, and the rules to follow.

This page is for the AI agent doing the work (Claude, Grok Bot, or your own MCP
client) and for developers wiring one up. People connecting an app should read
[Connect your AI](https://api.lawtte.ai/agent-builder/connect-your-ai.md).

Server: `https://www.lawtte.ai/api/mcp` (streamable HTTP, OAuth or
`Authorization: Bearer lawtte_sk_…`). The Agent Builder tools need the call
permissions: `list_agents` and `get_agent` need **calls:read**, the rest need
**calls:write**.

## Rules

1. **Read before you write.** Call `list_agents` first. Use only the ids, tool keys,
   mailbox ids and text-line ids it returns. Never invent them.
2. **Confirm before anything that sends.** Ask the user before `manage_agent` with
   `go_live` or `check_now` on a live agent, `update`, `remove`, and before
   `apply_agent_change`. These tools are marked destructive.
3. **Test mode first.** `launch` always starts in Test mode, which sends nothing.
   Show the user a `preview` or `practice_run` before you suggest going live.
4. **Follow the house rules.** Every firm keeps standing rules (`house_rules`, one
   per line) that every agent must follow. Read them before you design or change an
   agent; `list_agents`, `get_builder_settings` and `save_agent_draft` all return
   them. Copy the phrases and wording the user gives you exactly.
5. **Save standing instructions as house rules.** When the user says "always…" or
   "never…" about how agents behave, offer to add it with `update_builder_settings`
   (`add_house_rules`) so every future agent follows it too.
6. **Fix what Lawtte tells you.** When `launch_problems` isn't empty, or a tool
   returns an error, it says what to change in plain words. Fix that and retry, or
   ask the user.
7. **Check a call before placing it.** For a call agent, run `manage_agent` with
   `call_check` first, then `call_place` once the user confirms. Both go through the
   same checks as `place_call`: consent, calling hours, Do Not Call and daily limits.
8. **No sensitive data.** Don't put Social Security, card or bank numbers, dates of
   birth, passwords or medical details in any field.

## Build a new agent

**1. list\_agents**

Returns `agents` (each with `agent_id` like `recipe:…` or `builtin:…`, its
`request_id`, name and status), `builds` (with `built_with`), `tools` (keys for
blueprint steps, and whether each is connected), `mailboxes`, `text_lines` and
`house_rules`.

**2. save\_agent\_draft**

Send the blueprint, and a `recipe` if it's one Lawtte can run itself (see below).
Returns `request_id`, `ready_to_launch`, `open_questions`, `launch_problems` and
the dashboard `link`. Call it again with `request_id` to change the draft;
fields you leave out keep their values.

**3. manage\_agent: launch**

`{ "id": "<request_id>", "action": "launch" }`. It starts in Test mode. If the
blueprint still has `open_questions`, either answer them with
`save_agent_draft`, or pass `"accept_defaults": true` after the user agrees.

**4. manage\_agent: preview or practice\_run**

`preview` shows what it would pick up now. `practice_run` replays the last two
weeks of real threads. Both only read.

**5. manage\_agent: go\_live (after the user confirms)**

From here it sends by itself.

If no `recipe` fits what the user wants, save the blueprint without one and use
`manage_agent` with `send_to_lawtte_team`. Lawtte's team builds it, and the user sees
the status in their dashboard.

### Blueprint fields

| Field | Required for a new agent | What it is |
| - | - | - |
| `name` | yes | Short name |
| `goal` | yes | One sentence: what it gets done |
| `trigger_kind` | yes | `schedule`, `event` or `manual` |
| `trigger_detail` | yes | When exactly it runs |
| `audience` | yes | Who it contacts or works on |
| `steps` | yes | 1–10 of `{ "tool": <key from tools>, "action": "…" }` |
| `channels` | yes | Any of `email`, `sms`, `call`, `slack`, `crm_update`, `report` |
| `approval` | yes | `review_first` or `automatic` |
| `stop_when` | yes | When it stops for a case or person |
| `notify`, `example`, `open_questions` | no | Who hears about it, sample wording, what's still unanswered |
| `recipe` | to launch | What Lawtte runs (below) |

### Recipe formats

```json Email follow-up theme={null}
{
  "kind": "thread_followup",
  "config": {
    "mailbox": "<id from list_agents mailboxes>",
    "sequences": [
      {
        "key": "release",
        "name": "Signed release",
        "trigger": "please sign and return the release",
        "body": ["Hi, following up on the release we sent.", "Could you send it back signed?"],
        "waitBusinessDays": 5
      }
    ],
    "maxFollowups": 3,
    "lookbackDays": 14,
    "cc": ["karina@firm.com"]
  }
}
```

```json Text follow-up theme={null}
{
  "kind": "text_followup",
  "config": {
    "line": "<id from list_agents text_lines>",
    "sequences": [
      {
        "key": "ro",
        "name": "Repair order",
        "trigger": "please send your repair order",
        "body": ["Hi, just checking in. Could you text us a photo of your repair order?"],
        "waitBusinessDays": 2
      }
    ],
    "maxFollowups": 2,
    "lookbackDays": 7
  }
}
```

```json Call agent theme={null}
{
  "kind": "call_agent",
  "config": {
    "objective": "Confirm the adjuster received our demand and when they'll respond",
    "recipientType": "adjuster",
    "collect": ["Claim number", "Expected response date"],
    "voicemail": "leave"
  }
}
```

How a follow-up works: when the firm sends an email (or text) containing `trigger`,
and nobody outside the firm replies within the wait, Lawtte replies in that same
thread with `body`. It repeats up to `maxFollowups` times.

| Limit | Email | Text |
| - | - | - |
| Follow-ups per agent (`sequences`) | up to 4 | up to 4 |
| `trigger` | at least 6 characters, each one different | at least 3 words, each one different |
| `waitBusinessDays` | 1–30 (default 5) | 1–30 (default 2), or `waitHours` 1–72 |
| `maxFollowups` | 1–12 (default 3) | 1–6 (default 2) |
| `lookbackDays` | 1–60 (default 14) | 1–60 (default 7) |
| Wording | paragraphs | about 306 plain characters; no emoji, link shorteners or `[fill-ins]` |

Call agents: `recipientType` is `client`, `witness`, `adjuster`, `business_office` or
`other`. `collect` is up to 10 short items, and `voicemail` is `leave` or `hang_up`.

## Change an existing agent

**Turn it on or off.** Use `manage_agent` with the agent's `request_id` or
`recipe:` `agent_id`: `pause`, `resume`, `back_to_test_mode`, `go_live` or `remove`.

**Change its settings.** Pick one of two ways:

* **Propose, then apply.** `get_agent` returns its `editable` fields. Send only what
  changes to `propose_agent_change` as `desired`. You get back each change with an
  `id`, a `before` and an `after`. Show them to the user, then call
  `apply_agent_change` with the `proposal_id` (and `accept` to apply only some).
  This is the only way to change **built-in** agents (`builtin:…`).
* **Replace the config.** `manage_agent` with `action: "update"` and the full new
  `recipe` (and an optional `name`). It's for `recipe:` agents only.

To turn a built-in agent on or off, send `desired: { "status": "live" }` (or
`paused`, `resume`, `removed`) on its own to `propose_agent_change`.

## House rules and settings

`get_builder_settings` returns the house rules, the Agent Builder's name and how it
talks, the default inbox, text line and calling number, and every inbox, text line
and number the firm has.

`update_builder_settings` changes them. Fields you leave out keep their values.

| Field | What it does |
| - | - |
| `add_house_rules` | Adds rules, one per item, and keeps the existing ones. Repeats are skipped. |
| `house_rules` | Replaces all of them (up to 4,000 characters). Confirm with the user first. |
| `builder_name`, `builder_style` | What the Agent Builder is called (up to 40 characters) and how it talks. |
| `default_email`, `default_text`, `default_call` | The default inbox (mailbox id), text line (line id) or calling number (E.164). `null` clears it. |

New house rules apply to agents designed from then on. Existing agents keep their
wording until you change them, so offer to update the ones a new rule affects.

## Phone numbers

* **Studio account with no number:** `get_calling_setup_status`, then
  `set_up_calling`.
* **A new number, or the firm's name on caller ID:** `request_phone_number` with
  `kind: "new"` (optional `area_code`) or `kind: "brand"` (with `phone`), plus
  `caller_id_name`: up to 15 letters, numbers and spaces, like `OCONNOR LAW`. The
  Lawtte team sets it up by hand, usually within a business day.
* **Connecting an inbox** needs a Microsoft 365 or Google sign-in in the dashboard:
  **Agents → Settings → Channels → Connect an inbox**. Send the user there.

## `manage_agent` actions

| Action | Sends? | What it does |
| - | - | - |
| `launch` | no | Draft → running in Test mode |
| `preview` | no | What it would pick up now |
| `practice_run` | no | Replays the last two weeks of real threads |
| `test_check` | no | Runs now without sending |
| `check_now` | **yes, if live** | Runs now |
| `go_live` | **yes** | It sends by itself from now on |
| `pause` / `resume` / `back_to_test_mode` | no | Turns it off, back on, or back to Test mode |
| `update` | changes a live agent | Replaces its config with `recipe` |
| `send_to_lawtte_team` | no | Lawtte's team builds it |
| `remove` | stops it | Stops it for good |
| `call_check` | no | Whether a call agent may call this person now. Pass `call`. |
| `call_place` | **yes, dials** | A real AI call from a live call agent. Pass `call`: `name`, `phone`, `consent_confirmed`, `represented_by_counsel`, and `fields` for placeholders. |

## Errors

Errors come back as tool results with plain text, for example *"This agent is already
launched or with the Lawtte team. Change it with propose\_agent\_change."*, or a list of
`launch_problems`. They're written so you can act on them: fix the field or ask the
user. An unexpected error says nothing was changed.

Every build records the app that made it (`built_with`), from the name your client
registered at sign-in. API keys record as **Lawtte MCP**.

See [connector tools](https://api.lawtte.ai/mcp/tools.md#agent-builder-tools) for the full tool list.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.