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:

•
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
•
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
•
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:

•Reason: Analyze the current state and decide next action
•Act: Call an API, use a tool, or make a decision
•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:

•Research Agent: Gathers information from sources
•Analysis Agent: Processes and synthesizes data
•Writing Agent: Creates structured outputs
•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:

•Agent discovers available tools
•Agent calls tools using standardized interface
•Tool returns structured response
•Agent processes and continues workflow

Advantage: Write once, use with any agent.

Custom API Integration

When building custom integrations:

•Define clear API contract (inputs/outputs)
•Implement error handling and retries
•Add rate limiting and caching
•Monitor usage and costs
•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:

•Problem Restatement: Confirm understanding of the user's need
•Agent Architecture Recommendation: Single vs. multi-agent, with rationale
•Step-by-Step Workflow: Apply relevant steps from the 9-step process
•Tool Integration Plan: Specific tools needed and integration approach
•Layer Analysis: Which of the 8 layers need focus and why
•Implementation Guidance: Prioritized next steps based on user's role
•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