---
title: "Agent Setup Playbook"
description: "Step-by-step guide for external AI agents provisioning Voicetta via the Setup API, MCP, or REST."
publishedAt: "2026-07-15"
modifiedAt: "2026-07-15"
category: "LLM"
tags: "Voicetta, setup API, MCP, agent provisioning, tools"
navOrder: "93"
canonical: "https://voicetta.com/docs/agent-setup-playbook"
---

# Agent Setup Playbook

This playbook is for **external AI agents** (Claude, ChatGPT, Cursor, custom bots) that provision Voicetta on behalf of a human Guest.

## Why it matters for your business

- **Save money:** one agent session replaces repeated manual onboarding support.
- **Work faster:** profile, assistant, knowledge, phone, and tools in one guided flow.
- **Standardize service:** every host uses the same Setup API contract.
- **Delight every Guest:** the human receives a ready handoff card with login and forwarding steps.

## Terminology bridge

When human-facing docs say **Connections** in `app.voicetta.com`, the Setup API uses **Tools**:

| Human UI | Agent API | After enable |
|----------|-----------|--------------|
| Connection | Setup Tool (`tool_id`) | Capability (voice action) |

Examples:

- UI: "Connect Guesty" → API: `tool_id: guesty` → Capability: `guesty_search_reservations`
- UI: "SMS channel" → API: `tool_id: sms` → Capability: `send_sms_confirmation`

Do **not** send `connection` or `integration` in Setup API requests. Use `tool_id` from the catalog.

## Discovery

| Resource | URL |
|----------|-----|
| LLM index | https://voicetta.com/llms.txt |
| OpenAPI | https://voicetta.com/setup-openapi.json |
| MCP package | `@voicetta/setup-mcp` |
| Host guides | [Setup Host Guides](/docs/setup-host-guides) |

Base API URL: `https://api.voicetta.com/v1/setup`

## AgentEnvelope

Every authenticated step returns an **AgentEnvelope**:

```json
{
  "session_id": "ses_...",
  "status": "awaiting_consent",
  "message_for_user_agent": "Ask the user to open the consent URL.",
  "actions_completed": ["session_created"],
  "human_required": {
    "type": "consent",
    "url": "https://app.voicetta.com/setup/consent?...",
    "instructions": "Authorize Voicetta setup in the browser."
  },
  "handoff": null
}
```

When `human_required` is present, pause automation and instruct the human. Resume after they complete the step.

## Setup flow

```mermaid
flowchart LR
    A[Create session] --> B[Human consent]
    B --> C[Profile]
    C --> D[Assistant]
    D --> E[Knowledge]
    E --> F[Phone]
    F --> G[Select tools]
    G --> H[Enable tools]
    H --> I[Test call]
    I --> J[Handoff]
```

### 1. Create session

```http
POST /v1/setup/sessions
Content-Type: application/json
X-Partner-Agent: claude

{"partner_agent": "claude"}
```

Response: `session_id`, `consent_url`, `status`.

### 2. Human consent

Send the human to `consent_url`. After login and authorization, Voicetta issues a scoped Bearer token:

```
Authorization: Bearer setup_...
```

TTL: 24 hours, bound to one `session_id`.

### 3. Profile → assistant → knowledge

```http
POST /v1/setup/sessions/{session_id}/profile
POST /v1/setup/sessions/{session_id}/assistant
POST /v1/setup/sessions/{session_id}/knowledge
```

Each step returns an updated envelope with the next `message_for_user_agent`.

### 4. Phone (optional)

```http
POST /v1/setup/sessions/{session_id}/phone
```

May return `human_required` for payment (`type: payment`) or forwarding instructions. Poll `GET /v1/setup/sessions/{session_id}` until `status` advances.

### 5. Tool catalog and selection

```http
GET /v1/setup/tools/catalog
GET /v1/setup/tools/catalog?category=PMS&industry=Hospitality
POST /v1/setup/sessions/{session_id}/tools/select
```

List only `available` tools. UI label for each item is **Connection**.

### 6. Enable or skip tools

```http
POST /v1/setup/sessions/{session_id}/tools/{tool_id}/enable
POST /v1/setup/sessions/{session_id}/tools/{tool_id}/skip
GET /v1/setup/sessions/{session_id}/tools
```

OAuth and marketplace tools often return `human_required` with a URL. Credentials-based tools may accept `payload` from the agent when `agent_can_submit_credentials` is true.

### 7. Test call and handoff

```http
POST /v1/setup/sessions/{session_id}/test-call
GET /v1/setup/sessions/{session_id}/handoff
```

Return the handoff JSON to the human: login URL, Voicetta phone, forwarding instructions, tool status, and next steps.

## MCP mirror

The `@voicetta/setup-mcp` package exposes one MCP tool per Setup API step:

- `voicetta_create_setup_session`
- `voicetta_get_session_status`
- `voicetta_list_tools_catalog`
- `voicetta_submit_business_profile`
- `voicetta_configure_assistant`
- `voicetta_upload_knowledge`
- `voicetta_request_phone_number`
- `voicetta_select_tools`
- `voicetta_enable_tool`
- `voicetta_skip_tool`
- `voicetta_get_tools_status`
- `voicetta_run_test_call`
- `voicetta_get_handoff_summary`

Set `VOICETTA_SETUP_SESSION_ID` and `VOICETTA_SETUP_ACCESS_TOKEN` after consent.

## Webhooks (optional)

Agents without push support can poll `GET /sessions/{id}`. For async steps (phone provisioning, OAuth), register:

```http
POST /v1/setup/sessions/{session_id}/webhooks/register
{"webhook_url": "https://your-agent.example/hooks/voicetta"}
```

Events: `phone.provisioned`, `tool.enabled`, `test_call.completed`.

## Rules

- Only document and call tools Voicetta can actually perform.
- Never include passwords in handoff — reference Google OAuth or the password set at consent.
- Use `X-Partner-Agent` or `partner_agent` for attribution (`claude`, `chatgpt`, `cursor`, `custom`).
- When status is `completed`, stop and deliver the handoff.

## Related pages

- [Setup Host Guides](/docs/setup-host-guides)
- [LLM and MCP Readiness](/docs/llm-and-mcp-readiness)
- [Glossary](/docs/glossary)
- [Agent Tools](/docs/agent-tools)
- [Integrations Overview](/docs/integrations-overview)