Create an Agent

Agents are stored in the agents table (packages/server/src/db/schema/agents.schema.ts). Creation endpoints live in packages/server/src/routes/agents.route.ts and are protected by the same bearer-token middleware as the rest of the API.

Option A – JSON payload

• Method: POST /api/agents
• Body schema: derived from the Drizzle insert schema. name and companyId are required; other fields (instructions, description, supportedLanguages, defaultLanguage) are optional.

curl -X POST http://localhost:3001/api/agents \
  -H "Authorization: Bearer $TELLYO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Onenine Voice Guide",
    "companyId": "REPLACE_WITH_COMPANY_UUID",
    "description": "Answers AI + automation questions for OneNine prospects",
    "instructions": "Greet callers warmly and keep responses concise.",
    "supportedLanguages": ["FRENCH", "ENGLISH"],
    "defaultLanguage": "FRENCH"
  }'

The API returns the inserted row, excluding the soft-delete column (deletedAt is intentionally omitted).

Option B – YAML upload

Use this when you want to version agent configs alongside the repo. The handler accepts a YAML file (max 1 MB, enforced by Multer) plus a small JSON body.

• Method: POST /api/agents/from-yaml
• Form fields:
  • name — agent nickname (string)
  • companyId — UUID
  • yamlFile — .yaml or .yml file

The repo contains a working sample at packages/agent/samples/onenine-agent.yaml. It covers phone numbers, opening hours, language settings, instructions, FAQs, and transfer rules.

curl -X POST http://localhost:3001/api/agents/from-yaml \
  -H "Authorization: Bearer $TELLYO_API_KEY" \
  -F "name=Onenine Voice Guide" \
  -F "companyId=REPLACE_WITH_COMPANY_UUID" \
  -F "yamlFile=@packages/agent/samples/onenine-agent.yaml"

The YAML parser (js-yaml) validates that the file produces an object; its contents are serialized into the rawConfig column while specific keys hydrate description, instructions, faqs, supportedLanguages, and defaultLanguage.

Verify the agent

1. GET /api/agents – confirms your agent appears in the list.
2. GET /api/agents/{agentId} – fetches one agent.
3. GET /api/agents/by-phone/{phoneNumber} – used by the LiveKit worker (requires phone provisioning first, but safe to test if the column is null).

Next, update the agent configuration or provision a phone number before exposing it to callers.