Agent Approach

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

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:

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"
    }
  }'

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.

What happens behind the scenes

Auth + resolution

Echo validates your API key and resolves your project, business, customer, and agent.

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.

Prompt rendering

Every {{token}} in the agent’s system_prompt is replaced with the resolved value.

Call initiation

Echo places the outbound call using the rendered prompt.

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.

Structured Output with `output_schema`

output_schema is a JSON Schema object. Echo uses it to extract structured data from the call transcript after the conversation ends.

"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:

{
  "event": "call.completed",
  "call_result": {
    "confirmed": true,
    "reschedule_request": null
  }
}

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.

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

GET /v1/agents

Get a specific agent

GET /v1/agents/:agentId

Update an agent (partial)

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

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.

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 if you want to send a notification without defining an agent.

Getting Started

Guides

Agent Approach

What is an Agent?

Creating an Agent

Fields

Triggering a Notification with an Agent

What happens behind the scenes

Structured Output with `output_schema`

Managing Agents

List all active agents

Get a specific agent

Update an agent (partial)

Disable an agent

Agent vs LLM Path

​What is an Agent?

​Creating an Agent

​Fields

​Triggering a Notification with an Agent

​What happens behind the scenes

​Structured Output with output_schema

​Managing Agents

​List all active agents

​Get a specific agent

​Update an agent (partial)

​Disable an agent

​Agent vs LLM Path

What is an Agent?

Creating an Agent

Fields

Triggering a Notification with an Agent

What happens behind the scenes

Structured Output with `output_schema`

Managing Agents

List all active agents

Get a specific agent

Update an agent (partial)

Disable an agent

Agent vs LLM Path