agent-workflow

name

agent-workflow

description

Expert system for designing and architecting AI agent workflows based on proven Meta methodologies. Use when users need to build AI agents, create agent workflows, solve problems using agentic systems, integrate multiple tools into agent architectures, or need guidance on agent design patterns. Helps translate business problems into structured agent solutions with clear scope, tool integration, and multi-layer architecture planning.

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