> ## 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.
# Designing Agent Systems
> Combine deterministic workflows with autonomous agents for reliable operations
Complex Duckie systems work best when deterministic process logic and autonomous reasoning are separated clearly.
Use **workflows** for repeatable state transitions, routing, approvals, retries, and audit-sensitive steps. Use **autonomous agents** for judgment, research, language, tool selection, and ambiguous work. Use **internal channel agents** for human approvals and escalations in Slack or another team channel. Use **Duckie Assistant agents** for reporting, run review, feedback loops, and improvements to Duckie configuration.
## The Design Model
```mermaid theme={null}
flowchart TD
Channels["Channels and schedules"] --> Deployments["Deployments"]
Deployments --> Workflows["Deterministic workflows"]
Deployments --> Agents["Autonomous agents"]
Workflows --> Subflows["Callable workflows"]
Workflows --> AgentTasks["Agent task nodes"]
Agents --> SpecialistAgents["Callable agents"]
Agents --> Tools["Tools and knowledge"]
AgentTasks --> Tools
Workflows --> EscalationAgent["Internal escalation agent"]
Agents --> EscalationAgent
EscalationAgent --> Humans["Human reviewers"]
Humans --> EscalationAgent
EscalationAgent --> Workflows
Workflows --> Runs["Runs and analytics"]
Runs --> DuckieAssistant["Duckie Assistant reporting and feedback agents"]
```
The orchestration layer should be explicit:
* A deployment starts a workflow or agent when an event, webhook, message, or schedule fires.
* A workflow owns known process states and branches.
* A workflow can call another workflow when a step is reusable across multiple processes.
* A workflow can call an agent when a step needs judgment or natural language work.
* An autonomous agent can call specialized agents when a task should be delegated.
* An internal escalation agent keeps human approvals and questions inside the operational loop.
* A Duckie Assistant agent reviews runs, reports on behavior, and proposes improvements to Duckie objects.
## What Each Component Owns
| Component | Owns | Avoid using it for |
| -------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| **Deployment** | Trigger source, channel, mode, and schedule | Business logic that belongs in a workflow or agent |
| **Workflow** | Deterministic process state, branch logic, approvals, retries, and tool order | Open-ended reasoning or broad research |
| **Autonomous agent** | Judgment, language, investigation, and flexible tool use | Strict compliance branches that must run the same way every time |
| **Internal channel agent** | Human approvals, escalation questions, reviewer decisions, and structured handoffs | Duckie workspace maintenance or configuration updates |
| **Duckie Assistant agent** | Run inspection, workspace inspection, reporting, feedback loops, and configuration improvements | Direct customer support or real-time approval routing |
| **Callable agent** | A focused subtask with a clear contract | General orchestration of the full process |
| **Tool** | A specific read or write action | Policy decisions or process ownership |
A good design usually uses a workflow backbone with agents at the points where judgment, language, or tool choice matters.
## Design From the Business Process
Start by writing the process in normal operational language:
1. What starts the process?
2. What facts are always required?
3. Which branches are deterministic?
4. Which steps require judgment or language?
5. Which humans approve, review, or provide missing context?
6. What should be reported daily or weekly?
7. How should mistakes become improvements?
Then map each answer to a Duckie component.
## Common Patterns
### Workflow Backbone With Specialist Agents
Use this when the process has known stages but individual stages need judgment.
```mermaid theme={null}
flowchart TD
Trigger["Trigger"] --> Workflow["Main workflow"]
Workflow --> Classifier["Classification agent"]
Workflow --> Research["Research agent"]
Workflow --> Approval["Approval workflow"]
Approval --> Submit["Submission workflow"]
```
### Internal Channel Agent for Human Review
Use this when the system needs quick human input without moving people out of Slack or another internal channel.
```mermaid theme={null}
sequenceDiagram
participant Workflow as Workflow
participant Agent as Slack escalation agent
participant Reviewer as Human reviewer
participant Origin as Originating run
Workflow->>Agent: Ask for approval or missing context
Agent->>Reviewer: Post concise request
Reviewer->>Agent: Reply in thread
Agent->>Origin: Return structured decision
Origin->>Workflow: Continue next branch
```
### Scheduled Reporting Agent
Use this when stakeholders need recurring visibility into operational health.
```mermaid theme={null}
flowchart TD
Scheduler["Scheduler deployment"] --> Reporter["Duckie Assistant reporting agent"]
Reporter --> Runs["Runs and analytics"]
Reporter --> Systems["Operational systems"]
Reporter --> Slack["Stakeholder channel"]
```
## Design Checklist
* Put deterministic routing in workflows.
* Put uncertain interpretation in agents.
* Put repeated subprocesses in callable workflows.
* Put specialized judgment in callable agents.
* Put human approvals and escalations in internal channel agents.
* Put reporting, run review, and behavior improvement in Duckie Assistant agents.
* Put recurring operational review in scheduled deployments.
* Put powerful write actions behind clear scopes and approval gates.
* Track categories, attributes, and outcomes from the start.
## Related Docs
Build deterministic process logic.
Configure agents that reason and use tools flexibly.
Build agents for reporting, run review, and Duckie configuration improvements.
Run agents on recurring schedules.