--- name: agentic-workflows version: 1.0.0 description: Design and implement agentic AI workflows and patterns. Covers ReAct, planning agents, tool use, memory systems, and multi-agent orchestration. Use when building autonomous AI agents, implementing complex task automation, or designing intelligent workflow systems. --- # Agentic Workflows: AI Agent Design Patterns Design and implement effective agentic AI workflows using proven patterns for reasoning, planning, tool use, and multi-agent orchestration. ## Triggers Use this skill when: - Designing autonomous AI agent systems - Implementing complex task automation - Building multi-agent orchestration - Creating self-improving AI workflows - Implementing ReAct or planning patterns - Keywords: agentic, agent, autonomous, ReAct, planning, tool use, multi-agent, orchestration, reasoning, memory ## Core Concepts ### What Makes an Agent An AI agent is a system that: 1. **Perceives** its environment (reads context, files, APIs) 2. **Reasons** about what to do (plans, decides) 3. **Acts** on the environment (executes tools, writes files) 4. **Learns** from results (updates state, improves) ### Agent vs. Workflow | Aspect | Traditional Workflow | Agentic Workflow | |--------|---------------------|------------------| | Control | Predefined steps | Dynamic decisions | | Branching | Fixed conditions | Reasoned choices | | Error Handling | Catch/retry | Analyze/adapt | | Scope | Known tasks | Open-ended goals | --- ## Pattern 1: ReAct (Reasoning + Acting) ### Overview ReAct interleaves reasoning and acting: ``` Thought: I need to find the user's order Action: query_database("orders", {"user_id": "123"}) Observation: Found 3 orders: [...] Thought: The most recent order is from January Action: get_order_details("order-456") Observation: Order contains 2 items... Thought: I now have enough information Action: respond_to_user("Your latest order...") ``` ### Implementation Pattern ```python def react_loop(goal: str, max_iterations: int = 10): context = {"goal": goal, "history": []} for i in range(max_iterations): # Reason about current state thought = llm_reason(context) context["history"].append({"type": "thought", "content": thought}) # Decide on action action = llm_decide_action(context) if action.type == "final_answer": return action.content # Execute action observation = execute_tool(action) context["history"].append({ "type": "observation", "action": action, "result": observation }) return "Max iterations reached" ``` ### Best Practices - Keep thoughts concise but informative - Validate tool outputs before proceeding - Include error states in reasoning - Set reasonable iteration limits --- ## Pattern 2: Plan-and-Execute ### Overview Separate planning from execution: ``` PLAN: 1. Gather requirements from user 2. Research existing patterns 3. Design solution architecture 4. Implement core functionality 5. Add tests 6. Document EXECUTE: [Execute each step, revise plan if needed] ``` ### Implementation Pattern ```python def plan_and_execute(goal: str): # Phase 1: Planning plan = llm_create_plan(goal) # Phase 2: Execution with replanning results = [] for step in plan.steps: result = execute_step(step) results.append(result) # Check if replanning needed if needs_replan(result, plan): plan = llm_revise_plan(goal, results, plan) return synthesize_results(results) ``` ### When to Use - Complex multi-step tasks - Tasks requiring resource allocation - Projects with dependencies - When visibility into progress matters --- ## Pattern 3: Tool-Use Agent ### Overview Agent that selects and uses tools dynamically: ``` Available Tools: - search_code(query) - Search codebase - read_file(path) - Read file contents - write_file(path, content) - Write to file - run_tests() - Execute test suite - git_commit(message) - Commit changes Task: "Fix the failing test in user-service" Agent selects: search_code("user-service test") Agent selects: read_file("tests/user-service.test.ts") Agent selects: read_file("src/user-service.ts") Agent selects: write_file("src/user-service.ts", fixed_content) Agent selects: run_tests() Agent selects: git_commit("fix: resolve user-service test failure") ``` ### Tool Definition Pattern ```python tools = [ { "name": "search_code", "description": "Search codebase for pattern", "parameters": { "query": {"type": "string", "description": "Search pattern"} }, "returns": "List of matching files and lines" }, # ... more tools ] def tool_use_agent(task: str, tools: list): while not is_complete(task): # Select tool based on current state tool_choice = llm_select_tool(task, tools, context) # Execute tool result = execute_tool(tool_choice) # Update context context.add_observation(tool_choice, result) ``` ### Tool Design Principles 1. **Single Responsibility**: Each tool does one thing well 2. **Clear Descriptions**: Help agent select correctly 3. **Predictable Output**: Consistent return formats 4. **Error Information**: Return useful error messages 5. **Idempotency**: Safe to retry when possible --- ## Pattern 4: Memory Systems ### Types of Memory | Type | Purpose | Implementation | |------|---------|----------------| | **Working** | Current task context | In-context prompt | | **Episodic** | Past interactions | Conversation history | | **Semantic** | Knowledge/facts | RAG/vector store | | **Procedural** | How to do things | Skills/tools | ### Memory Architecture ``` ┌─────────────────┐ │ Agent Core │ │ (Reasoning) │ └────────┬────────┘ │ ┌───────────────────┼───────────────────┐ │ │ │ v v v ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Working │ │ Episodic │ │ Semantic │ │ Memory │ │ Memory │ │ Memory │ │ (context) │ │ (history) │ │ (RAG/KB) │ └─────────────┘ └─────────────┘ └─────────────┘ ``` ### Implementation with Archon ```python # Store episodic memory manage_document("create", project_id=PROJECT_ID, title="Session Memory: 2025-01-23", document_type="note", content={ "session_id": "session-001", "interactions": [...], "decisions": [...], "learnings": [...] } ) # Retrieve for new session docs = find_documents(project_id=PROJECT_ID, query="session memory") ``` --- ## Pattern 5: Multi-Agent Systems ### Architectures **Hierarchical:** ``` ┌──────────────┐ │ Orchestrator │ └──────┬───────┘ │ ┌───────────┼───────────┐ │ │ │ v v v ┌───────┐ ┌───────┐ ┌───────┐ │Agent A│ │Agent B│ │Agent C│ │(Code) │ │(Test) │ │(Review)│ └───────┘ └───────┘ └───────┘ ``` **Peer-to-Peer:** ``` ┌───────┐ ┌───────┐ │Agent A│<--->│Agent B│ └───┬───┘ └───┬───┘ │ │ └──────┬──────┘ │ v ┌───────┐ │Agent C│ └───────┘ ``` **Pipeline:** ``` ┌───────┐ ┌───────┐ ┌───────┐ ┌───────┐ │ Input │-->│Agent A│-->│Agent B│-->│Agent C│-->│Output│ └───────┘ └───────┘ └───────┘ └───────┘ ``` ### Orchestrator Pattern ```python class Orchestrator: def __init__(self, agents: dict): self.agents = agents self.state = {} def execute(self, task: str): plan = self.create_plan(task) for step in plan: agent = self.select_agent(step) result = agent.execute(step, self.state) self.state.update(result) if self.needs_replan(result): plan = self.revise_plan(plan, result) return self.synthesize(self.state) ``` ### Agent Communication ```python # Message passing message = { "from": "coder-agent", "to": "tester-agent", "type": "work_complete", "content": { "files_changed": ["src/user.py"], "commit": "abc123" } } # Shared state (via Archon) manage_task("update", task_id=TASK_ID, metadata={ "agent_state": { "last_agent": "coder", "next_agent": "tester", "handoff_data": {...} } } ) ``` --- ## Pattern 6: Self-Improvement Loop ### Overview Agent that learns from its mistakes: ``` ┌─────────────────────────────────────────────┐ │ │ │ ┌──────────┐ │ │ │ Execute │ │ │ └────┬─────┘ │ │ │ │ │ v │ │ ┌──────────┐ ┌──────────┐ │ │ │ Evaluate │────>│ Learn │ │ │ │ Result │ │ │ │ │ └──────────┘ └────┬─────┘ │ │ │ │ │ v │ │ ┌──────────┐ │ │ │ Update │ │ │ │ Strategy │ │ │ └────┬─────┘ │ │ │ │ └─────────────────────────┘ │ ``` ### Implementation ```python def self_improving_agent(task: str, max_attempts: int = 3): strategy = load_default_strategy() for attempt in range(max_attempts): result = execute_with_strategy(task, strategy) evaluation = evaluate_result(result) if evaluation.success: # Store successful strategy save_strategy(task_type, strategy) return result # Learn from failure lessons = analyze_failure(result, evaluation) strategy = update_strategy(strategy, lessons) return escalate_to_human(task, attempts) ``` --- ## Implementation Checklist ### Essential Components - [ ] Clear goal/task definition - [ ] Reasoning/planning capability - [ ] Tool/action execution - [ ] State management - [ ] Error handling - [ ] Termination conditions ### Quality Attributes - [ ] Observability (logging, tracing) - [ ] Controllability (pause, resume, cancel) - [ ] Recoverability (checkpoints, retry) - [ ] Explainability (decision logging) - [ ] Resource limits (iterations, time, cost) ### Safety Considerations - [ ] Sandboxed execution environment - [ ] Permission boundaries - [ ] Human-in-the-loop for critical actions - [ ] Rollback capabilities - [ ] Audit trail --- ## Archon Integration ### Project Structure for Agents ```python # Create agent project manage_project("create", title="Multi-Agent System", description="Orchestrated agent pipeline" ) # Create tasks for each agent role manage_task("create", project_id=PROJECT_ID, title="Coder Agent: Implement feature", feature="Agent-Coder" ) manage_task("create", project_id=PROJECT_ID, title="Tester Agent: Validate implementation", feature="Agent-Tester" ) # Store agent state in documents manage_document("create", project_id=PROJECT_ID, title="Agent Orchestration State", document_type="note", content={ "pipeline_state": "running", "current_agent": "coder", "completed_steps": [], "pending_steps": [] } ) ``` --- ## Best Practices 1. **Start Simple**: Begin with single-agent, add complexity as needed 2. **Clear Boundaries**: Define what each agent can/cannot do 3. **Explicit Handoffs**: Make agent transitions observable 4. **Fail Gracefully**: Always have fallback/escalation paths 5. **Test Incrementally**: Verify each agent independently first 6. **Monitor Everything**: Log decisions, actions, outcomes 7. **Human Oversight**: Keep humans in the loop for critical decisions 8. **Iterate**: Agent design improves through testing and refinement --- ## Related Skills - `/autonomous-agent-harness` - Full harness implementation - `/ralph-loop` - Iterative development loops - `/speckit-workflow` - Spec-driven development - `/archon-workflow` - Task and project management --- ## Notes - Agentic systems require careful design and testing - Start with well-defined tasks before attempting open-ended goals - Multi-agent systems add complexity - use only when needed - Always have escape hatches and human intervention points - Document agent decisions for debugging and improvement