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

# Agent Approach

> Build reusable voice personas with system prompts, variables, and structured output extraction.

## What is an Agent?

An **Agent** is a reusable voice persona you define once at the business level and trigger for any customer at notification time. Agents give you full control over:

* The AI's personality, tone, and scope
* The conversation flow via a system prompt
* Structured data extracted from the call via `output_schema`
* Dynamic content injected per-call via `{{variable}}` placeholders

Agents are shared across all your projects. You create them once, then reference them by `agent_id` in any notification request.

***

## Creating an Agent

```bash theme={null}
curl -X POST https://api.meetecho.ai/v1/agents \
  -H "x-api-key: echo_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Appointment Reminder",
    "system_prompt": "You are {{agent_name}}, a friendly appointment reminder assistant for {{business_name}}. You are calling {{recipient_first_name}} to remind them about their upcoming appointment on {{appointment_date}} at {{appointment_time}}. Confirm they can make it, or collect details to reschedule.",
    "output_schema": {
      "type": "object",
      "required": ["confirmed", "rescheduling"],
      "properties": {
        "confirmed":      { "type": "boolean", "description": "Whether the customer confirmed their appointment" },
        "rescheduling":   { "type": "boolean", "description": "Whether the customer wants to reschedule" },
        "preferred_date": { "type": "string",  "description": "Preferred new date if rescheduling" },
        "preferred_time": { "type": "string",  "description": "Preferred new time if rescheduling" }
      }
    }
  }'
```

### Fields

| Field           | Required | Description                                                                |
| --------------- | -------- | -------------------------------------------------------------------------- |
| `name`          | Yes      | A label for your own reference. Not read aloud.                            |
| `system_prompt` | Yes      | The full instruction set for the AI. Supports `{{variable}}` placeholders. |
| `output_schema` | No       | JSON Schema for structured data extraction after the call.                 |

***

## Triggering a Notification with an Agent

Once your agent is created, pass its `id` as `agent_id` along with a `customer_id` and any custom variables:

```bash theme={null}
curl -X POST https://api.meetecho.ai/v1/notifications \
  -H "x-api-key: echo_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "8cc6199f-...",
    "agent_id": "ddb8be3b-...",
    "variables": {
      "agent_name": "Echo Reminders",
      "appointment_date": "Monday, April 14",
      "appointment_time": "10:00 AM"
    }
  }'
```

<Note>
  `recipient_first_name` is a built-in variable — Echo resolves it automatically from the customer record. You don't need to pass it in `variables`.
</Note>

### What happens behind the scenes

<Steps>
  <Step title="Auth + resolution">
    Echo validates your API key and resolves your project, business, customer, and agent.
  </Step>

  <Step title="Variable map construction">
    Echo builds a variable map: built-in variables (business name, recipient name, etc.) are populated first, then your `variables` map is merged in. Caller-provided values override built-ins if they share the same key.
  </Step>

  <Step title="Prompt rendering">
    Every `{{token}}` in the agent's `system_prompt` is replaced with the resolved value.
  </Step>

  <Step title="Call initiation">
    Echo places the outbound call using the rendered prompt.
  </Step>

  <Step title="Result delivery">
    When the call ends, Echo extracts structured data using your `output_schema`, updates the notification record, and POSTs a signed `call.completed` event to your webhook URL.
  </Step>
</Steps>

***

## Structured Output with `output_schema`

`output_schema` is a [JSON Schema](https://json-schema.org/) object. Echo uses it to extract structured data from the call transcript after the conversation ends.

```json theme={null}
"output_schema": {
  "type": "object",
  "required": ["confirmed"],
  "properties": {
    "confirmed": {
      "type": "boolean",
      "description": "Whether the patient confirmed the appointment"
    },
    "reschedule_request": {
      "type": "string",
      "description": "Preferred reschedule time if they want to change it"
    }
  }
}
```

The extracted data is stored in `notification.call_result` and included in the outbound webhook payload:

```json theme={null}
{
  "event": "call.completed",
  "call_result": {
    "confirmed": true,
    "reschedule_request": null
  }
}
```

<Tip>
  Write clear, specific `description` fields on each property — Echo uses them to understand what to extract from the transcript. Vague descriptions lead to vague extractions.
</Tip>

If no `output_schema` is defined, `call_result` will be `null` in both the notification record and the webhook payload.

***

## Managing Agents

### List all active agents

```bash theme={null}
GET /v1/agents
```

### Get a specific agent

```bash theme={null}
GET /v1/agents/:agentId
```

### Update an agent (partial)

Only the fields you send are changed. Omitted fields are left unchanged.

```bash theme={null}
PATCH /v1/agents/:agentId
Content-Type: application/json

{
  "system_prompt": "Updated prompt..."
}
```

### Disable an agent

Soft delete — sets status to `"disabled"`. Disabled agents cannot be used in new notifications.

```bash theme={null}
DELETE /v1/agents/:agentId
```

***

## Agent vs LLM Path

|                   | Agent path                                 | LLM path              |
| ----------------- | ------------------------------------------ | --------------------- |
| Setup             | Define agent once, reuse                   | No setup              |
| Prompt            | You write it                               | Echo generates it     |
| Variables         | Full `{{variable}}` system                 | Built-ins only        |
| Structured output | Yes, via `output_schema`                   | No                    |
| Best for          | Consistent brand voice, templates, surveys | One-off notifications |

See the [LLM path guide](/guides/llm-approach) if you want to send a notification without defining an agent.