Job pack · handoff
Support / ops agent
Router or handoff into specialists. Humans as tools. Durable state on the ticket. No group chat on prod.
When: Inbound language must become a structured action on a customer object, with approval on side effects.
Ticket is the blob. Handoff rewrites the brief. Refunds are ask_human. Do not start a crew.
GET /api/canon/jobs/support-agent?format=md
Playbooks
- Choose a topologyWalk the decision tree. Do not start from a crew because the demo looked collaborative.
- Add a human gateApproval and missing info are tools. Pause is an API. The blob survives the wait.
- Design the ACINames, schemas, errors, caps, idempotency, the permission gate. This is the real prompt.
- Ship durableThe reducer over a blob, with pause, resume, traces, and evals. This is production.
Doctrine to load
- RoutingClassify the input, then send it to a specialist prompt, model, or workflow. Separation of concerns for language.
- Handoffs and SwarmControl transfers. The current agent returns the next agent. Context is a clean brief, not a pile of speakers. OpenAI Swarm made this obvious; the Agents SDK made it shippable.
- Humans as ToolsFactor 7: contact humans with tool calls. Approval, missing information, and exceptions are tools named ask_human, not a special control-plane myth.
- Unify Execution and Business StateFactor 5: there is one serializable blob. The ticket is the agent state. A second 'agent memory' that drifts from the business object is how you lose the thread and the customer.
- Durable ExecutionAgents run longer than request timeouts. Checkpoint after every turn. Resume as a first-class API. LangGraph won production on this axis.
- Small, Focused AgentsA good agent has few tools, a narrow goal, and a short context. Generalists are orchestrators. Specialists do the work.
- Trigger from AnywhereFactor 11: the loop does not live in one text box. Mail, chat, tickets, cron, webhooks, and IDE events are all legal starts. The agent is a reducer over events, not a chatbot with extra steps.
Refuse
- HITL that cannot resume. The human answers and the run is gone. Approval as a side channel, not a tool.
- Double side effects. Non-idempotent tools, no journal. A retry refunds twice.
- Unsupervised group chat. Agents talking to each other against production tools with no turn bound and no typed messages.
- Shared mega-context. A crew sharing one bloated window. Specialists drown in each other's work.
Checklists
Ready to build
- Named termination: done schema, max turns, token/money cap.
- Sandbox / allowlist for every side effect. Secrets in the executor.
- An explicit context builder: pinned, working, recalled, compacted.
- A golden set of 20–50 real tasks, run in CI on prompt change.
- Launch / pause / resume APIs. HITL is a tool that checkpoints.
ACI quality
- One job per tool. No mega-tool JSON blob.
- Verb names the model will say: read_file, apply_patch, ask_human.
- Compact errors: the smallest string that enables the next correct action.
- Capped results. Pagination or a file write instead of 200k-token dumps.
- Idempotent or journaled. Retries do not double side effects.
- Allow / ask / deny in code, logged, resumable.
Recipes
Default corpus
openai-agentslanggraphn8ninngest