agent-workflow

name

agent-workflow

description

Expert system for designing and architecting AI agent workflows based on proven Meta methodologies. 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 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:

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)