> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duckie.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Choosing an Agent Architecture
> Decide how to combine agents, workflows, runbooks, tools, and deployments
An agent architecture is the shape of your Duckie system: which agent owns the work, what process it follows, what tools it can use, when it delegates, and where humans stay involved.
Start with the business process, not the Duckie object. Ask what needs to happen, what must be controlled, where judgment is useful, and what should be reviewed before customers are affected.
## Quick Recommendations
| If the work looks like this | Start with |
| --------------------------------------------------------------- | ---------------------------------------------------------------- |
| Many customer topics enter one queue | An **Autonomous** agent with clear scope and guarded tool access |
| The same exact steps must happen every time | A **Workflow** |
| There is a known procedure, but conversations vary | A **Runbook** |
| One part needs a specialist | A parent agent or workflow with a **sub-agent** |
| The source, event, tag, or schedule already identifies the task | A targeted **Deployment** |
| The action is risky or policy-sensitive | Guardrails, approvals, or human review before Live mode |
## The Core Decision
Duckie systems work best when each part has a clear job:
* **Deployments** bring work in from channels, webhooks, events, and schedules.
* **Agents** own customer-facing or internal work.
* **Workflows** control known steps, routing, approvals, and exact tool order.
* **Runbooks** give flexible procedural guidance.
* **Sub-agents** handle focused specialist tasks.
* **Tools** read information, send messages, update systems, or call your APIs.
* **Guardrails** define when Duckie should stop, avoid something, or involve a human.
* **Runs** show what happened so you can debug and improve.
A good design often uses a workflow backbone for predictable process logic, with agents at the points where judgment, language, or research matters.
## Questions to Ask
### How predictable is the process?
Use a **Workflow** when the process should follow the same path, checks, and branches each time.
Use a **Runbook** when the procedure is known but the conversation needs flexibility.
Use an **Autonomous** agent when the request may require research, choosing between resources, deciding which tool to call, or handling many possible topics.
### Who owns the overall journey?
If the process has known states, approvals, retries, or routing, let a workflow own the journey.
If the work is an open-ended customer conversation, let an autonomous agent own the journey.
If the work is one focused procedure, a runbook may be enough.
### Does the system need specialists?
Use **Callable agents** when a parent agent or workflow should keep ownership but a specialist should handle one part. Specialist agents are useful for billing, technical triage, account review, evidence drafting, or internal approvals.
### How risky are the actions?
Limit write tools to the agents that need them. Use **Testing** mode, **Internal notes only**, **No write actions**, **Restrictions**, **Escalation Rules**, and tool approvals for sensitive actions.
### How will you improve it?
Review **Analyze > Runs**, track **Categories**, **Attributes**, and **Resolution Tracking**, then test changes in **Test > Playground**, **Test > Replay Chats**, and **Test > Batch Test**.
## Common Architectures
| Pattern | Use it when | Example |
| ------------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------ |
| Single autonomous agent | One broad queue needs flexible handling | General support agent for common product and billing questions |
| Workflow-first process | The sequence must be controlled | Refund eligibility, approval, and response |
| Runbook-led agent | The task follows a procedure but needs judgment | Password reset troubleshooting |
| Workflow with specialist agents | The process is known, but steps need judgment | Intake workflow calls a classification agent and evidence drafting agent |
| Human review path | The next step affects money, access, data, or customer trust | Duckie prepares an action and a teammate approves it |
| Scheduled internal agent | Work happens on a recurring cadence | Daily run summary or escalation review |
## Example
For a refund process:
1. A deployment starts when a refund request arrives.
2. A workflow looks up the order and checks eligibility.
3. A runbook guides policy-based customer messaging.
4. A specialist agent reviews unusual edge cases.
5. A human approves high-value exceptions.
6. Analyze > Runs shows the final path, tool calls, outcome, and any escalation.
## Related Docs
Learn what agents can do and how start modes work.
Build deterministic process logic.
Write flexible procedures for agents.
See advanced system patterns.