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/api/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/api/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"
}
}
}
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.
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 a specific agent
GET /api/v1/agents/:agentId
Update an agent (partial)
Only the fields you send are changed. Omitted fields are left unchanged.
PATCH /api/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 /api/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 |
