> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Author an AI Agent from a Prompt

> Turn a plain-English brief into a draft agent, pick a model preset on cost/latency/quality tradeoffs, validate it with persona simulation and the red-team safety gate, then promote it to canary.

# 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](https://orbit.devotel.io/en/agents/from-prompt)) and
type your brief, or call the endpoint directly:

```bash theme={null}
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](https://orbit.devotel.io/en/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.

1. 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.
2. 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.
3. 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](/agents/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.

```bash theme={null}
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](/guides/ai-agent-rollout-pipeline).

## 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](https://orbit.devotel.io/en/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%:

```bash theme={null}
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](/guides/ai-agent-rollout-pipeline).

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](/concepts/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.                                  |

## See also

* [Safely Roll Out an AI Agent](/guides/ai-agent-rollout-pipeline) — the
  rollout pipeline this guide's validation and canary steps come from.
* [Build a WhatsApp and SMS AI Agent](/guides/whatsapp-sms-ai-agent) — the
  from-scratch messaging build for when the generated draft needs a channel
  deployment.
* [Model selection](/agents/model-selection) — model tiers and the voice
  routing policy fields.
* [Agent versions](/agents/agent-versions) — the saved configurations canary
  moves between.
* [Agent run lifecycle](/concepts/agent-run-lifecycle) — the states a run
  moves through once your agent is live.