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:

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