Guides

Setup assistant

Describe the agent you want, review the plan the assistant proposes, approve it, and let it build on your account.

You describe what you need in plain language. The assistant reads your account, proposes a plan of API operations, and stops. Nothing changes until you approve; then it runs the plan, checks the result and reports.

In the dashboard: the Ask page, mode Set up for me. The same flow is available through the API described here.

Note: The assistant needs an AI backend that the operator configures. Without one, available is false and the Ask page keeps only its question-and-answer mode.

Check availability

curl https://api.kshyamai.space/assistants/setup/status \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef"

{"provider": "anthropic_api", "label": "...", "available": true, "hint": ""}

provider is claude_code, anthropic_api, fake or none. When it is none, hint says what is missing.

1. Start a session

curl -X POST https://api.kshyamai.space/assistants/setup/sessions \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{}'

{"session_id": "e4d3c2b1-a09f-4e8d-9c7b-6a5f4e3d2c1b", "provider": "anthropic_api", "label": "...", "available": true, "hint": ""}

session_id is null when no backend is available.

2. Send your request

curl -N -X POST https://api.kshyamai.space/assistants/setup/sessions/e4d3c2b1-a09f-4e8d-9c7b-6a5f4e3d2c1b/messages \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{"content": "A Hindi and English payment-reminder agent for card customers of Example Bank, calling weekdays 10 to 6."}'

The response is a text/event-stream. Events:

At this stage the assistant only reads: agents, model and voice catalogs, numbers, knowledge bases, workflows, compliance settings, validation, price estimates and a test chat.

3. Review the plan

A plan is an ordered list of API operations:

{
  "id": "0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e",
  "status": "pending",
  "title": "Payment reminder agent",
  "summary": "Creates the agent and its extraction questions.",
  "operations": [
    {"id": "op1", "method": "POST", "path": "/v2/agent", "body": {"agent_config": {}, "agent_prompts": {}},
     "description": "Create the agent", "label": "Create an agent", "flags": []},
    {"id": "op2", "method": "POST", "path": "/dispositions",
     "body": {"agent_id": "{{op1.agent_id}}", "name": "Outcome", "question": "..."},
     "description": "Add an outcome question", "label": "Create a disposition", "flags": []}
  ]
}

{{op1.agent_id}} refers to the result of an earlier operation. Agent bodies are checked against the agent schema when the plan is proposed.

What a plan may contain

Every operation must be on a fixed allow-list: agents, knowledge bases from a URL, dispositions and extraction categories, inbound links, batches built from contacts you pasted, workflows and campaigns, and the do-not-call list. Placing a single call, running a workflow for a contact, API keys, sub-accounts, provider keys, team and billing cannot be planned at all.

Flagged operations

A flagged operation runs only if you confirm it by id.

4. Approve or reject

curl -N -X POST https://api.kshyamai.space/assistants/setup/sessions/e4d3c2b1-a09f-4e8d-9c7b-6a5f4e3d2c1b/plan/0b1c2d3e-4f5a-4b6c-8d7e-9f0a1b2c3d4e \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{"decision": "approve", "confirm_flagged": []}'

The answer is the same kind of event stream: one operation event per step (status ok, failed or skipped, with status_code and response), then the assistant's verification.

How execution behaves:

• Operations run in order with your own token, so the assistant can do exactly what you can, on your account only. If your role cannot perform an operation, that operation fails.
• It stops at the first failure. Later operations are skipped.
• Every operation is written to an audit record: who approved, when, the endpoint, the body with secrets masked, and the status.

Plan statuses: pending, approved, executed, failed, rejected, superseded.

Errors: 400 when a flagged operation is not confirmed, 409 This plan was already executed (or its status), 409 The assistant is still working on this session.

Templates

Instead of writing a request from scratch, start from a template. The gallery has 23 templates in 12 industries: banking and cards, insurance, utilities, healthcare, e-commerce, real estate, education, recruitment, automotive, hospitality, telecom and logistics.

1. GET /assistants/setup/templates lists them (id, industry, name, summary, direction, tags).
2. GET /assistants/setup/templates/{template_id} returns the form: fields for company, agent name, languages, voice and tone, plus template-specific ones.
3. POST /assistants/setup/templates/{template_id}/brief with {"values": {...}} returns {"brief", "title", "template_id"}.
4. Create a session with {"template_id": "...", "title": "..."} and send the brief as its first message.

Invalid values give 400 with a per-field errors object. Text fields are capped at 160 characters and text areas at 800. URLs may not carry credentials or a query string.

Your values are treated as data, not as instructions. Example names and endpoints in a template are placeholders you must replace.

Agent builder: from your documents to an agent you edit

The chat proposes a plan you can approve or tweak operation by operation. The agent builder goes further: you attach your own documents, pick a template, and get the whole agent as a structured draft you can edit field by field. In the dashboard: Ask, mode Agent builder.

1. Attach documents. PDF, DOCX, TXT, MD or CSV: an SOP, a script, FAQs, a policy. Up to 5 per builder, 10 MB and 50 pages each.
2. Pick a template. The builder ranks the 23 templates by the words they share with your documents, and the assistant suggests the best fits with a reason and the page it based it on.
3. Edit the draft. Agent name, languages, the identity and rules, the opening line in each language, every step (add, remove, rename, its prompt), every transition (its condition, its target, the values it extracts), the safety transition that applies from every step, function tools (URL, method, parameters), extraction fields, compliance rules (calling hours, AI disclosure, consent, do-not-call, PII redaction), knowledge files and test scenarios. Problems are shown next to the field, checked with the same rules as the graph editor.
4. Let the assistant fill it. "Fill from my documents" writes prompts, steps, rules and a knowledge file from your documents, and marks which part came from which document and page.
5. Rounds of suggestions. "Suggest improvements" returns a list of concrete changes, each with its reason and a before/after view: "Add a safety transition from every step", "Add a step for refunds (SOP page 3)", "Your opening line is 32 words: shorten it". Accept or reject each one, edit further, and ask again. Rejected suggestions are not offered again unless the draft changes.
6. History. Every save, fill and accepted round is a version. Restore any earlier version; restoring adds a new version, so nothing is lost.
7. Test. Run the draft's test scenarios and the safety probe before anything is created. Failures feed the next round of suggestions.
8. Create. The builder turns the draft, exactly as edited, into a plan: knowledge files, the graph agent, its extraction fields. You approve it like any plan.

Note: Before any text reaches the assistant it is masked: card, Aadhaar and account numbers, CVV, OTP, PIN, PAN, long numbers, phone numbers and e-mail addresses become tags such as [CARD XXXX1234] or [PHONE]. Names and street addresses are not masked, so do not attach documents with real customers' personal data. Your original files stay on the platform.

Tokens and cost

The builder shows the tokens each assistant request used (input, output, cache reads and writes) and the session's totals, with an estimated cost in your wallet's currency. The estimate is for your information; what is charged is the operator's price per assistant request, if any (see Billing).

Through the API

# attach a document to a setup session
curl -X POST https://api.kshyamai.space/assistants/setup/sessions/e4d3c2b1-a09f-4e8d-9c7b-6a5f4e3d2c1b/documents \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -F "file=@collections-sop.pdf"

# start the draft from a template
curl -X POST https://api.kshyamai.space/assistants/setup/sessions/e4d3c2b1-a09f-4e8d-9c7b-6a5f4e3d2c1b/builder/start \
  -H "Authorization: Bearer vk-0123456789abcdef0123456789abcdef" \
  -H "Content-Type: application/json" \
  -d '{"template_id": "card-payment-reminder", "values": {"company_name": "Example Bank"}}'

Then ask for suggestions (POST .../builder/assist with {"task": "improve"}), accept some (POST .../builder/suggestions), and create the plan (POST .../builder/plan). Every endpoint is in the Assistants reference.

Limits

GET /assistants/setup/sessions lists your sessions; GET /assistants/setup/sessions/{session_id} returns the transcript and plans. Another account's ids answer 404.

Limitations

• Read every plan before approving; a plan can be valid and still not what you meant.
• Plans keep the request bodies they proposed. Audit records mask secrets; plan records do not.
• A failed plan is not rolled back. Operations that already succeeded stay in place.
• In the chat, knowledge bases can be added from a URL only. The agent builder turns attached documents into knowledge files.
• The assistant does not place calls. Test the result yourself: see Testing without a phone.
• The operator may price assistant messages in the price book. See Billing.

Endpoint details are in Assistants reference.