> ## 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.

# Create Agent

> Agents define a reusable voice persona with a system prompt and optional
output schema for structured data extraction.




## OpenAPI

````yaml POST /agents
openapi: 3.0.3
info:
  title: Echo API
  description: |
    Echo is a voice notification platform. Use your API key (returned on signup)
    in the `x-api-key` header for all `/v1/*` endpoints.

    The API key implicitly scopes every request to your project and business —
    no need to pass IDs in the URL.
  version: 1.0.0
servers:
  - url: https://api.meetecho.ai/v1
    description: Production
security: []
tags:
  - name: Auth
    description: Signup, login, token refresh
  - name: Customers
    description: Manage customers within your project
  - name: Agents
    description: Manage reusable voice agents
  - name: Notifications
    description: Trigger and inspect outbound calls
  - name: API Keys
    description: Create and revoke API keys for your project
  - name: Project
    description: Inspect and configure your project settings
  - name: Webhook Endpoints
    description: >-
      Create and manage webhook endpoints — each with its own URL, event
      subscriptions, and signing secret
  - name: Delivery Logs
    description: >-
      Inspect delivery history, per-attempt details, and manually retry failed
      deliveries
paths:
  /agents:
    post:
      tags:
        - Agents
      summary: Create agent
      description: |
        Agents define a reusable voice persona with a system prompt and optional
        output schema for structured data extraction.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
            example:
              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
      responses:
        '201':
          description: Agent created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
              example:
                id: ddb8be3b-a426-4122-b877-a0cba363c89d
                created_at: '2026-03-18T17:43:46.714Z'
                business_id: 97bfa642-d2cb-46d5-8de8-6d3553c83007
                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
                    rescheduling:
                      type: boolean
                    preferred_date:
                      type: string
                    preferred_time:
                      type: string
                status: active
                updated_at: '2026-03-18T17:43:46.714Z'
      security:
        - ApiKey: []
components:
  schemas:
    CreateAgentRequest:
      type: object
      required:
        - name
        - system_prompt
      properties:
        name:
          type: string
          example: Appointment Reminder
        system_prompt:
          type: string
          description: >
            Supports built-in variables: `{{business_name}}`,
            `{{business_summary}}`,

            `{{recipient_name}}`, `{{recipient_first_name}}`, `{{message}}`,
            `{{context}}`.

            Any additional `{{key}}` tokens are filled from the `variables` map
            on each notification.
          example: >-
            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
          description: >-
            JSON Schema for structured data extraction after the call. Omit for
            unstructured calls.
          example:
            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
    Agent:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: ddb8be3b-a426-4122-b877-a0cba363c89d
        business_id:
          type: string
          format: uuid
          example: 97bfa642-d2cb-46d5-8de8-6d3553c83007
        name:
          type: string
          example: Appointment Reminder
        system_prompt:
          type: string
          example: >-
            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
          nullable: true
          example:
            type: object
            required:
              - confirmed
              - rescheduling
            properties:
              confirmed:
                type: boolean
              rescheduling:
                type: boolean
              preferred_date:
                type: string
              preferred_time:
                type: string
        status:
          type: string
          enum:
            - active
            - disabled
          example: active
        created_at:
          type: string
          format: date-time
          example: '2026-03-18T17:43:46.714Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-03-18T17:43:46.714Z'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: 'Echo API key — format: `echo_<64 hex chars>`. Returned once on signup.'

````