agent-workflow

What this skill does

# Agent Workflow Designer

## Overview

This skill guides the design and architecture of AI agent workflows using proven methodologies. 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 validated at Meta.

## 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