Agent Workflow

---
name: agent-workflow
description: Expert system for designing and architecting AI agent workflows. Use when building AI agents, designing multi-agent systems, integrating tools into agent architectures, choosing between single vs. multi-agent setups, or translating a business problem into an agentic solution. Triggers on: "build an agent", "design agent workflow", "multi-agent system", "agent architecture", "how should I structure this agent". Covers 9-step building process, 8-layer architecture framework, MCP integration, and pitfall avoidance.
---

# Agent Workflow Designer

## Overview

This skill guides the design and architecture of AI agent workflows. When a user presents a problem, this skill helps structure an agent-based solution following the 9-step building process and 8-layer architecture framework.

## Workflow Decision Tree

When a user shares a problem or requests agent design help:

1. **Assess the problem scope**
   - Is the problem clearly defined? → Proceed to Problem Analysis
   - Is the problem vague? → Ask clarifying questions about desired outcomes and constraints

2. **Determine architecture complexity**
   - Simple task (single action)? → Single agent with basic tools
   - Complex task (multiple sub-tasks)? → Consider multi-agent orchestration
   - Integration task (connecting systems)? → Focus on Layer 4 (Tooling) design

3. **Follow the appropriate workflow**
   - **New agent from scratch** → Apply 9-Step Building Process
   - **Existing agent improvement** → Focus on specific layers needing enhancement
   - **Tool integration problem** → Apply MCP and tooling patterns

## 9-Step Agent Building Process

Use this sequential workflow when designing a new agent from scratch:

### Step 1: Define Purpose and Scope

**Key principle:** Start with job-to-be-done, not technology.

Ask the user:
- What specific outcome does the end user need?
- What are the constraints (budget, time, resources)?
- What's the success metric?

**Bad scope example:**
"An AI assistant for customer service"

**Good scope example:**
"An agent that takes customer complaints, pulls order history from Shopify API, and drafts refund approvals for orders under $200"

**Decision point:** Narrow scope = better performance. Resist building Swiss Army knives.

### Step 2: Structure Inputs and Outputs

Treat the agent as a function with structured interfaces:

**Inputs:**
- Use JSON schemas or Pydantic models, not free text
- Define required vs. optional fields
- Specify data types and validation rules

**Outputs:**
- Return data objects, not prose
- Define clear error states
- Include confidence scores when relevant

**Example structure:**
```json
Input: {
  "complaint_text": "string",
  "customer_id": "string",
  "order_id": "string (optional)"
}

Output: {
  "action": "approve_refund | escalate | request_info",
  "refund_amount": "number",
  "reasoning": "string",
  "confidence": "number"
}
```

### Step 3: Write System Instructions

**Critical:** Spend 80% of design time here.

Include in system prompt:
- **Role definition:** "You are a sales qualification specialist..."
- **Behavioral guidelines:** "Always ask for budget before proposing solutions"
- **Output format requirements:** Specify JSON structure, word limits, tone
- **Edge case handling:** What to do when data is missing or ambiguous

**Testing strategy:** A great system prompt can make GPT-3.5 outperform poorly prompted GPT-4.

### Step 4: Enable Reasoning and External Actions

**ReAct Framework Pattern:**
1. **Reason:** Analyze the current state and decide next action
2. **Act:** Call an API, use a tool, or make a decision
3. **Observe:** Review the result and determine if goal is achieved

**Start simple:**
- Begin with if/then logic before complex reasoning chains
- Add tools incrementally (don't overwhelm with 50 tools at once)
- Test each tool integration independently

**Common tools to integrate:**
- Calculators for math operations
- Web browsers for research
- Database queries for data retrieval
- API calls to external systems

### Step 5: Orchestrate Multiple Agents (When Needed)

**When to use multi-agent architecture:**
- Task has clearly separable sub-tasks
- Different sub-tasks require different expertise
- Parallel processing would improve speed

**When NOT to use multi-agent:**
- Simple linear workflows
- Tasks that require continuous context
- When handoff complexity exceeds benefit

**Common 4-agent pattern:**
1. **Research Agent:** Gathers information from sources
2. **Analysis Agent:** Processes and synthesizes data
3. **Writing Agent:** Creates structured outputs
4. **QA Agent:** Reviews quality and accuracy

**Keep handoffs simple:** Complex orchestration = complex failures.

### Step 6: Implement Memory and Context

Three types of memory to consider:

**Conversation history:**
- What happened this session
- Recent user interactions
- Current task state

**User context:**
- User preferences and settings
- Past interaction patterns
- Historical decisions

**Knowledge retrieval:**
- Relevant information from knowledge base
- Similar past cases
- Domain-specific context

**Implementation guidance:**
- Start with simple conversation buffers
- Add vector databases only when needing semantic search across large datasets
- Consider memory retrieval latency in architecture

### Step 7: Add Multimedia Capabilities

Modern agents should handle:
- Voice input/output for accessibility
- Image understanding for visual tasks
- Document processing (PDF, DOCX, spreadsheets)

**Strategic approach:** Add capabilities based on actual user needs, not "nice-to-haves."

### Step 8: Format and Deliver Results

**Output is your product's UX.** Design outputs for:

**Human consumption:**
- Clear formatting and structure
- Scannable with headers and bullets
- Professional appearance

**System consumption:**
- Valid JSON/XML
- Consistent field names
- Error codes for handling

**Quality standard:** Great agent outputs look like a human created them.

### Step 9: Build Interface or API

Delivery method options:
- Chat interface for conversational tasks
- API endpoints for system integration
- Integration with existing tools (Slack, email, CRM)

**Best practice:** The best agents feel invisible—they just make things happen.

## 8-Layer Architecture Framework

When analyzing agent architecture needs, consider which layers require attention:

### Layer 1: Infrastructure
**Foundation:** Cloud, databases, APIs, compute resources

**Key considerations:**
- GPU/TPU requirements for inference
- Data storage and retrieval speed
- Load balancing for scale
- Monitoring and observability

**Common mistake:** Underestimating compute needs—agents make more API calls than traditional apps.

### Layer 2: Agent Internet
**Operating system for agents:** Identity, state management, inter-agent communication

**Current state:** Mostly custom-built, but platforms like LangChain and CrewAI are emerging.

### Layer 3: Protocol
**Standards for interoperability:** MCP (Model Context Protocol) is becoming the standard

**Key principle:** Bet on open standards, not proprietary solutions. MCP allows any tool to work with any agent.

### Layer 4: Tooling Enrichment
**Agent superpowers:** RAG systems, function calling, external integrations

**Quality over quantity:** 5 rock-solid tools > 50 flaky integrations

**Tool categories:**
- Data retrieval (databases, APIs)
- Computation (calculators, processors)
- Communication (email, messaging)
- Content creation (documents, reports)

### Layer 5: Cognition Reasoning
**The brain:** Planning, decision-making, error handling

**Critical elements:**
- Guardrails to prevent hallucinations
- Error recovery strategies
- Confidence scoring
- Graceful degradation

**User forgiveness:** Users forgive agents that fail gracefully, not ones that spiral into nonsense.

### Layer 6: Memory Personalization
**Human touch:** Personal context, preferences, conversation history

**Start simple:** Store user preferences and conversation context before building complex personalization.

### Layer 7: Application
**User-facing products:** The actual agent functionality users interact with

**Focus strategy:** Nail one use case before expanding to others.

### Layer 8: Ops Governance
**Risk management:** Monitoring, cost control, privacy, oversight

**Build from day one:** Retrofitting governance is expensive and painful.

**Key components:**
- Cost tracking per agent action
- Privacy enforcement and data handling
- Human-in-the-loop for critical decisions
- Audit logs and compliance

## Problem-to-Solution Workflow

When a user presents a problem:

**Step 1: Clarify the problem**
- What's the current manual process?
- What's the desired outcome?
- What are the constraints (time, cost, technical)?
- What data sources are available?

**Step 2: Assess agent appropriateness**
Not every problem needs an agent. Consider:
- Is the task repetitive and rule-based?
- Does it require decision-making with context?
- Would automation provide significant value?
- Is the problem scope clear and bounded?

**Step 3: Map to architecture**
Using the 8 layers, identify which need focus:
- Simple task → Focus on Layers 4, 5, 7 (tools, reasoning, application)
- Complex integration → Add Layer 3 (protocol) emphasis
- Scalability concern → Prioritize Layers 1, 8 (infrastructure, ops)

**Step 4: Design workflow**
Apply the 9-step building process, calling out:
- Critical decision points
- Tool integration requirements
- Multi-agent needs (if any)
- Memory and context strategy

**Step 5: Identify implementation path**
Based on user's role and resources:
- **For PMs:** High-level architecture and tool selection
- **For engineers:** Detailed technical implementation with code patterns
- **For product teams:** Full stack from requirements to monitoring

## Tool Integration Patterns

### MCP (Model Context Protocol) Integration

When tools support MCP:
1. Agent discovers available tools
2. Agent calls tools using standardized interface
3. Tool returns structured response
4. Agent processes and continues workflow

**Advantage:** Write once, use with any agent.

### Custom API Integration

When building custom integrations:
1. Define clear API contract (inputs/outputs)
2. Implement error handling and retries
3. Add rate limiting and caching
4. Monitor usage and costs
5. Document for agent consumption

### Common Integration Scenarios

**CRM Integration (Salesforce, HubSpot):**
- Read customer data
- Create/update records
- Search across objects
- Trigger workflows

**Communication Tools (Slack, Email):**
- Send messages/notifications
- Read incoming requests
- Monitor channels
- Respond to mentions

**Data Sources (Databases, APIs):**
- Query structured data
- Retrieve documents
- Search knowledge bases
- Aggregate information

## Decision Framework: Single vs. Multi-Agent

### Use Single Agent When:
- Task is linear and sequential
- Context must be maintained throughout
- Decision-making is unified
- Complexity of orchestration > benefit

### Use Multi-Agent When:
- Clear task separation exists
- Sub-tasks need different expertise
- Parallel processing improves performance
- Quality benefits from specialization

**Example - Customer Support:**

**Single agent sufficient for:**
"Take customer complaint, pull order history, draft refund approval"

**Multi-agent beneficial for:**
"Monitor social media, categorize issues, research solutions, generate responses, escalate critical cases, track resolution"

## Common Pitfalls and Solutions

### Pitfall 1: Scope Creep
**Problem:** Trying to build a general-purpose assistant
**Solution:** Define narrow, specific job-to-be-done with clear success metrics

### Pitfall 2: Tool Overload
**Problem:** Giving agent 50+ tools upfront
**Solution:** Start with 5 essential tools, add incrementally based on actual needs

### Pitfall 3: Skipping System Prompt
**Problem:** Generic or minimal instructions
**Solution:** Invest 80% of time crafting detailed system prompt with examples and edge cases

### Pitfall 4: No Error Handling
**Problem:** Agent breaks on unexpected inputs
**Solution:** Design graceful degradation, clear error states, and fallback behaviors

### Pitfall 5: Ignoring Costs
**Problem:** Runaway API costs from inefficient agent design
**Solution:** Build cost monitoring from day one, implement caching, optimize prompt length

### Pitfall 6: Over-Engineering Architecture
**Problem:** Building all 8 layers simultaneously
**Solution:** Start with Layers 4, 5, 7 (tools, reasoning, application), add others as needed

## Output Format

When providing agent workflow solutions, structure the response as:

1. **Problem Restatement:** Confirm understanding of the user's need
2. **Agent Architecture Recommendation:** Single vs. multi-agent, with rationale
3. **Step-by-Step Workflow:** Apply relevant steps from the 9-step process
4. **Tool Integration Plan:** Specific tools needed and integration approach
5. **Layer Analysis:** Which of the 8 layers need focus and why
6. **Implementation Guidance:** Prioritized next steps based on user's role
7. **Success Metrics:** How to measure if the agent is working

## Agent Taxonomy Quick Reference

When users ask about existing tools:

**Category 1: Consumer Agents (Built-In)**
- Examples: ChatGPT Agent, Claude, Gemini, Grok
- Best for: Quick tasks, research, content creation
- User type: Everyone, especially PMs

**Category 2: No-Code Builders**
- Examples: Zapier Central, n8n, Make
- Best for: Workflow automation without coding
- User type: PMs, operations teams

**Category 3: Developer-First Platforms**
- Examples: LangChain, CrewAI, AutoGen, Swarm
- Best for: Custom agent features in products
- User type: Engineering teams

**Category 4: Specialized Agent Apps**
- Examples: Cursor (coding), Perplexity (research), Notion AI (writing)
- Best for: Specific job-to-be-done with deep specialization
- User type: Domain-specific professionals

## See Also

- `brainstorming` — For scoping the agent's purpose and data flows before building
- `planning` — For breaking the agent implementation into atomic tasks
- `full-stack-build` — For building agent-backed features end-to-end (API + DB + frontend)