Author an AI Agent from a Prompt

Designing an agent does not have to start with a blank system_prompt field. The from-prompt builder takes a plain-English brief, generates a working agent draft — prompt, tools, model choice — and puts it in front of you for review before anything goes live. This guide walks the full path: write the brief, pin the model preset to a cost/latency/quality tradeoff you can defend, validate the draft against simulated customers and adversarial probes, and promote it through a canary rollout. Endpoint paths below are relative; send them against https://api.orbit.devotel.io/api/v1. Every step also has a dashboard equivalent, linked where it exists.

Prerequisites

An Orbit account with an API key carrying the agents:write scope.
An owner, admin, or developer role — draft generation and activation are write actions.
A short, concrete brief. “Handle parking-permit questions for the city office and escalate billing disputes to a human” beats a paragraph of adjectives.

1. Generate the draft from a brief

Open Agents → From prompt in the dashboard (/agents/from-prompt) and type your brief, or call the endpoint directly:

curl -X POST https://api.orbit.devotel.io/api/v1/agents/from-prompt \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Answer parking-permit questions for the city office. Cite the current fee schedule from the knowledge base. Escalate billing disputes and hardship cases to a human on the support queue."
  }'

The response is a draft agent — status draft — with a generated system prompt, suggested tools, and a starter set of example inputs. Nothing is live yet; a draft never answers a customer until you activate it.

POST /agents/from-prompt — generate and persist the draft.
POST /agents/from-prompt/stream — the same generation over SSE, which is what the dashboard wizard consumes so you can watch the draft take shape.
POST /agents/from-prompt/:draftId/sandbox-test — replay the seeded example inputs against the draft and read the responses.

Generation is rate-limited per organization per hour — iterate on the brief in the sandbox-test loop rather than regenerating end to end each time. Tune the generated prompt directly once the shape is right.

2. Pin a model preset

The draft generation picks a sensible default model, but voice and chat agents behave very differently per model family. The curated Model Presets (/agents/model-presets) bundle each model with the speech-to-text and voice configuration that carries it well, and each card carries the tradeoff that matters: estimated latency, blended cost per minute, and a quality rating so you are comparing, not guessing.

GET /agents/model-presets — list the four curated presets with their latency / cost / quality estimates.
GET /agents/model-presets/:id — read one preset’s full bundle and its “recommended for” guidance.
POST /agents/model-presets/:id/instantiate — create a draft voice agent pre-wired with the preset (owner/admin only).

The four presets, as the picker presents them:

Preset	Model	Latency (est.)	Cost per min (est.)	When to pick it
Balanced	Claude Sonnet 4.6	~900 ms	~$0.09	General support, sales, scheduling — the default when unsure.
High Intelligence	Claude Opus 4.7	~1400 ms	~$0.22	Multi-step negotiation, technical troubleshooting, compliance-stakes calls.
Ultra Fast	Claude Haiku 4.5 (fast lane)	~450 ms	~$0.05	High-volume triage, sub-second barge-in, short scripted flows.
Cost Saver	Claude Haiku 4.5	~650 ms	~$0.03	Very high volume, simple conversations, margin-first lines.

The estimates are curated comparison values, not per-call SLAs — use them to choose a tier, then measure your own traffic afterward.

3. Upgrade the model later — two tiers, one switch

Preset choice is not permanent, and a common production pattern is running two tiers at once: a cost-effective tier where volume lives, and a premium tier where the stakes live.

Start on a cheap tier (Cost Saver or Ultra Fast) and let the quality scorecard tell you when reasoning is the bottleneck, not the budget.
Move up when it matters: write the premium tier’s model onto the agent (PUT /agents/:id with the new model), save it as a new version, and run the same validation sequence below against that version.
Switch mid-flight when traffic changes: the model is part of the agent’s versioned configuration, so promote the version that carries the tier you want — the canary rollout moves traffic onto it one stage at a time and you keep the previous version as the instant rollback.

If you prefer to declare the constraint instead of hand-picking, voice agents accept a routing policy — a quality floor, a first-audio latency budget, a cost ceiling per minute — and the platform resolves it to the best-fitting preset per session, degrading to a cheaper/faster bundle rather than blocking the call when the constraints cannot all be met. See Model selection for the policy fields.

4. Validate with persona simulation

Generated drafts pass a smoke test easily; the question that matters is how the agent holds up across a whole conversation. POST /agents/:id/persona-simulation replays a scripted customer persona against your version and grades it against a rubric — pass rate, mean score, per-scenario verdict. A scenario that fails here never reaches traffic.

curl -X POST https://api.orbit.devotel.io/api/v1/agents/agent_abc123/persona-simulation \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "version_id": "ver_draft_1",
    "scenarios": [
      { "name": "permit fee lookup", "objective": "cite current fee schedule" },
      { "name": "billing dispute", "objective": "escalate to a human without arguing" }
    ]
  }'

Keep the scenario set short and curated — the endpoint grades each scenario with persona, runtime, and judge per turn. The full technique, including shadow comparison alongside simulation, is covered in Safely Roll Out an AI Agent.

5. Run the red-team safety gate

Persona simulation certifies the agent on cooperative traffic. Before promotion you also want its adversarial posture — Orbit ships a pre-deploy red-team gate that replays a built-in probe pack (jailbreak, prompt injection, data-exfiltration attempts) against the candidate version and compares it to your pinned safety baseline. Configure the gate on the agent, and a promotion that regresses the safety score — or falls below the floor you set — is refused with the gate report attached before any live config flips. Watch what your guardrails actually fire on in practice on the Guardrail analytics page (/agents/guardrail-analytics) and via GET /agents/guardrail-analytics; red-team findings usually point at one rule to tighten, not a policy to suspend.

6. Promote to canary

With simulation passing and the safety gate green, promote through the staged rollout — never straight to 100%:

curl -X POST https://api.orbit.devotel.io/api/v1/agents/agent_abc123/canary-rollout \
  -H "X-API-Key: dv_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "candidate_version_id": "ver_draft_1",
    "baseline_version_id": "ver_current_prod",
    "stages": [5, 25, 100],
    "min_stage_sample_size": 50
  }'

GET /agents/:id/canary-rollout plus POST .../evaluate advance, hold, or roll back each stage against its gates; POST .../rollback is the manual kill-switch. The full stage mechanics — including regression gates and the fairness eval before completion — are in Safely Roll Out an AI Agent. Once the rollout reports complete, follow the agent’s health through the run lifecycle states — queued → working → completed, with failed and input_required telling you when a run stopped short and why — in Agent run lifecycle.

Troubleshooting

Symptom	Fix
`429` on generation	The per-organization hourly limit is spent. Edit the existing draft’s prompt directly instead of regenerating from a new brief.
`422` on activate	Only an agent in `draft` status activates through this path. An already-active agent updates via `PUT /agents/:id` and a new version.
Draft answers drift off brief	The generator anchors to concrete nouns — add the specific policy, escalation target, and tone you want to the brief and regenerate once, rather than nudging the prompt blind.
Preset upgrade raises cost faster than expected	Compare the shadow comparison `cost_delta` between versions before promoting; a deeper model costs more per turn by design — gate it behind the scorecard.
Red-team gate refuses the promotion	Read the gate report’s failing probes; tighten the named guardrail rule and re-run the version through the gate instead of disabling the gate.

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Author an AI Agent from a Prompt

Author an AI Agent from a Prompt

Prerequisites

1. Generate the draft from a brief

2. Pin a model preset

3. Upgrade the model later — two tiers, one switch

4. Validate with persona simulation

5. Run the red-team safety gate

6. Promote to canary

Troubleshooting

See also

​Author an AI Agent from a Prompt

​Prerequisites

​1. Generate the draft from a brief

​2. Pin a model preset

​3. Upgrade the model later — two tiers, one switch

​4. Validate with persona simulation

​5. Run the red-team safety gate

​6. Promote to canary

​Troubleshooting

​See also

Author an AI Agent from a Prompt

Prerequisites

1. Generate the draft from a brief

2. Pin a model preset

3. Upgrade the model later — two tiers, one switch

4. Validate with persona simulation

5. Run the red-team safety gate

6. Promote to canary

Troubleshooting

See also