Agents

An agent is the configuration that drives a conversation: its prompt, personality, first message, which tools it can call, which voice it speaks with. Every phone call or workflow run is driven by one agent.

The draft/publish model

Every agent has two version slots:

• Live — what actually answers calls right now.
• Draft — what you're currently editing.

Editing an agent never changes what's live mid-call. You open a draft, make changes, test them (see Preview below), and only when you publish does the draft become the new live version. This means:

• A call in progress always runs against a consistent version of the agent, even if someone edits the agent while the call is happening.
• You can always see exactly what changed between the published version and your draft before committing to it.
• Every publish is a new, numbered version — you can look back at the full history.

# Create an agent — this also opens its first draft (v1)
curl -X POST https://convostack.ai/api/agents \
  -H "Authorization: Bearer cak_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Bot",
    "firstMessage": "Hi, thanks for calling — how can I help?",
    "systemPrompt": "You are a friendly support agent for Acme Inc.",
    "tone": "warm and concise"
  }'

The response includes draftVersionNumber: 1 and liveVersion: null — the agent exists, but nothing is live yet.

# Publish the draft — it becomes v1, live
curl -X POST https://convostack.ai/api/agents/{id}/publish \
  -H "Authorization: Bearer cak_live_..."

To make further changes later:

# Open a new draft from the current live version
curl -X POST https://convostack.ai/api/agents/{id}/draft \
  -H "Authorization: Bearer cak_live_..."

# Patch just the fields you're changing — unspecified fields keep their
# current value
curl -X PATCH https://convostack.ai/api/agents/{id}/draft \
  -H "Authorization: Bearer cak_live_..." \
  -H "Content-Type: application/json" \
  -d '{"firstMessage": "Thanks for calling Acme — what can I do for you today?"}'

# Publish when ready
curl -X POST https://convostack.ai/api/agents/{id}/publish \
  -H "Authorization: Bearer cak_live_..."

If you change your mind before publishing:

curl -X POST https://convostack.ai/api/agents/{id}/draft/discard \
  -H "Authorization: Bearer cak_live_..."

Previewing changes before publishing

Two read-only endpoints let you inspect a draft before committing to it:

• POST /api/agents/{id}/runtime-config/preview — compiles the effective prompt/config for the draft as if you applied a given patch, without actually saving it. Useful for a "preview" UI.
• GET /api/agents/{id}/runtime-config/diff — shows exactly what's different between the currently-published config and the current draft.

Presets

GET /api/agents/presets returns a catalog of built-in starting points (e.g. general receptionist, medical front-desk, law-firm intake, outbound lead qualifier). Pass a preset's key as preset when creating an agent to start from a tuned prompt/config instead of an empty one — you can still override any individual field.

Key fields

Field	What it controls
systemPrompt	The core instructions the model reasons from
firstMessage	What the agent says as soon as the call connects
tone, personality, expertise	Style guidance layered into the compiled prompt
guardrails	Things the agent must never do
redirectionStrategy, redirectionTriggers	When/how to hand off or escalate
tools	Which capabilities the agent can invoke mid-call (see below)
workflowVersionId	Binds the agent to a structured workflow instead of free-form reasoning
webhookUrl	Where ConvoStack POSTs a summary after the call ends
knowledgeDocumentIds	Documents the agent can ground its answers in

GET /api/agents/tool-kinds lists every tool kind an agent can bind — the current set covers scheduling, business-knowledge lookup, receptionist-style routing, and medical-scheduling flows.

Deactivating and reactivating

curl -X DELETE https://convostack.ai/api/agents/{id} \
  -H "Authorization: Bearer cak_live_..."     # soft-delete (deactivate)

curl -X POST https://convostack.ai/api/agents/{id}/activate \
  -H "Authorization: Bearer cak_live_..."     # bring it back

Deactivating an agent doesn't delete its history — past calls and conversations remain queryable.

Duplicating an agent

curl -X POST https://convostack.ai/api/agents/{id}/duplicate \
  -H "Authorization: Bearer cak_live_..."

Copies the live (or draft, if no live version exists yet) definition into a brand-new agent with its own draft — a fast way to spin up a variant without starting from scratch.