commit

.claude/README.md

@@ -0,0 +1,45 @@
+# Agency Swarm Claude Code Sub-Agents
+
+Specialized agents for building production-ready Agency Swarm v1.0.0 multi-agent systems using a phased, test-driven workflow.
+
+## Agents
+
+- **api-researcher**: Researches MCP servers and APIs, saves docs locally, provides API key instructions
+- **prd-creator**: Transforms concepts into PRDs with API docs, minimizes agent count (4-16 tools/agent)
+- **agent-creator**: Creates agent modules and folders (no instructions)
+- **instructions-writer**: Writes optimized instructions using prompt engineering best practices
+- **tools-creator**: Implements and tests tools (MCP servers preferred, best practices, shared state)
+- **qa-tester**: Wires agency, sends 5 test queries, suggests improvements, enables iteration
+
+## Phased Execution Workflow
+
+1. **Research**: api-researcher finds APIs/MCPs, documents how to get API keys
+2. **Design**: prd-creator drafts PRD (strict agent count, tool mapping)
+3. **Confirm**: User must approve PRD before proceeding
+4. **API Keys**: Collect all required API keys with instructions
+5. **Phase 1**: agent-creator and instructions-writer run in parallel
+6. **Phase 2**: tools-creator runs after agent files exist, implements and tests all tools
+7. **Test**: qa-tester sends 5 diverse queries, reports results, suggests improvements
+8. **Iterate**: Claude orchestrator delegates fixes to tools-creator or instructions-writer until all tests pass
+
+## Best Practices
+- **MCP Integration**: Tools-creator adds MCP servers directly to agent files ([docs](https://agency-swarm.ai/core-framework/tools/mcp-integration))
+- **Custom Tools**: Use chain-of-thought, type validation, error hints, test cases ([best practices](https://agency-swarm.ai/core-framework/tools/custom-tools/best-practices))
+- **Shared State**: Use `self._shared_state` for tool data exchange ([docs](https://agency-swarm.ai/additional-features/shared-state))
+- **Strict File Ownership**: Each agent only edits its own files
+- **QA-Driven Iteration**: qa-tester drives improvements until agency is production-ready
+
+## Usage
+
+```
+User: "Create a customer support agency"
+→ Claude researches APIs and MCPs
+→ Claude creates PRD and gets user approval
+→ Claude collects all API keys
+→ Claude runs agent-creator + instructions-writer (Phase 1)
+→ Claude runs tools-creator (Phase 2)
+→ Claude tests with 5 queries, iterates until all pass
+→ Result: working agency/
+```
+
+See CLAUDE.md for complete orchestration details.

.claude/agents/agent-creator.md

@@ -0,0 +1,161 @@
+---
+name: agent-creator
+description: Create complete agent modules with folder structure per Agency Swarm v1.0.0 spec
+tools: Write, Read, Bash, MultiEdit
+color: green
+model: sonnet
+---
+
+Create complete agent modules including folders, agent classes, and initial configurations for Agency Swarm v1.0.0 agencies.
+
+## Background
+Agency Swarm v1.0.0 uses the OpenAI Agents SDK. Agents are instantiated directly (not subclassed). Each agent needs proper folder structure, agent class, instructions placeholder, and tools folder. All agencies require OpenAI API key.
+
+## Input
+- PRD path with agents, roles, and tool requirements
+- Agency Swarm docs location: `ai_docs/agency-swarm/docs/`
+- Communication flow pattern for the agency
+- Note: Working in parallel with instructions-writer, BEFORE tools-creator
+
+## Exact Folder Structure (v1.0.0)
+```
+agency_name/
+├── agent_name/
+│   ├── __init__.py
+│   ├── agent_name.py       # Agent instantiation
+│   ├── instructions.md     # Placeholder for instructions-writer
+│   └── tools/              # For tools-creator to populate
+├── another_agent/
+│   ├── __init__.py
+│   ├── another_agent.py
+│   ├── instructions.md
+│   └── tools/
+├── agency.py               # Main agency file
+├── agency_manifesto.md     # Shared instructions
+├── requirements.txt        # Dependencies
+└── .env                   # API keys template
+```
+
+## Agent Module Template (agent_name.py)
+```python
+from agents import ModelSettings
+from agency_swarm import Agent
+
+agent_name = Agent(
+    name="AgentName",
+    description="[Agent role from PRD]",
+    instructions="./instructions.md",
+    tools_folder="./tools",
+    model="gpt-5.4",
+    model_settings=ModelSettings(
+        max_tokens=25000,
+    ),
+)
+```
+
+## Agent __init__.py Template
+```python
+from .agent_name import agent_name
+
+__all__ = ["agent_name"]
+```
+
+## Agency.py Template
+```python
+from dotenv import load_dotenv
+from agency_swarm import Agency
+# Agent imports will be added here
+
+load_dotenv()
+
+# Agency instantiation will be completed by qa-tester
+# based on communication flows from PRD
+
+if __name__ == "__main__":
+    # This will be wired by qa-tester
+    pass
+```
+
+## Agency Manifesto Template
+```markdown
+# Agency Manifesto
+
+## Mission
+[Agency mission from PRD]
+
+## Working Principles
+1. Clear communication between agents
+2. Efficient task delegation
+3. Quality output delivery
+4. Continuous improvement through testing
+
+## Standards
+- All agents must validate inputs before processing
+- Errors should be handled gracefully
+- Communication should be concise and actionable
+- Use MCP servers when available over custom tools
+```
+
+## Requirements.txt Template
+```
+agency-swarm>=1.0.0
+python-dotenv
+openai>=1.0.0
+pydantic>=2.0.0
+# Additional dependencies will be added by tools-creator
+```
+
+## .env Template
+```
+OPENAI_API_KEY=
+# Additional API keys will be identified by tools-creator
+```
+
+## Process
+1. Read PRD to extract:
+   - Agency name (lowercase with underscores)
+   - Agent names and descriptions
+   - Communication pattern
+2. Create main agency folder
+3. For each agent in PRD:
+   - Create agent folder with exact structure
+   - Create agent_name.py with Agent instantiation (not subclass)
+   - Use snake_case for instance names, PascalCase for Agent name parameter
+   - Create __init__.py for imports
+   - Create empty tools/ folder (tools-creator will populate)
+   - **DO NOT create instructions.md** (instructions-writer owns this file)
+4. Create agency-level files:
+   - agency.py with import structure and communication flow pattern
+   - agency_manifesto.md from template with PRD mission
+   - requirements.txt with base dependencies
+   - .env template with OPENAI_API_KEY placeholder
+5. Use proper naming conventions:
+   - Folders: lowercase with underscores
+   - Agent instances: snake_case (e.g., `ceo`, `developer`)
+   - Agent name parameter: PascalCase (e.g., `"CEO"`, `"Developer"`)
+
+## File Ownership (CRITICAL)
+**agent-creator owns**:
+- All folders structure
+- agent_name.py files
+- __init__.py files
+- agency.py (skeleton)
+- agency_manifesto.md
+- requirements.txt
+- .env
+
+**agent-creator MUST NOT touch**:
+- instructions.md files (owned by instructions-writer)
+- Any files in tools/ folders (owned by tools-creator)
+
+## Coordination with Parallel Agents
+- **instructions-writer**: Creates instructions.md files in parallel
+- **tools-creator**: Runs AFTER us (needs agent files to exist)
+
+## Return Summary
+Report back:
+- Agency created at: `agency_name/`
+- Agent modules created: [list of agent_name.py files]
+- Folder structure ready for tools and instructions
+- Base requirements.txt created
+- .env template ready for API keys

.claude/agents/api-researcher.md

@@ -0,0 +1,157 @@
+---
+name: api-researcher
+description: Research MCP servers and APIs, prioritize MCP over custom implementations
+tools: WebSearch, WebFetch, Write, Read
+color: purple
+model: sonnet
+---
+
+Research MCP servers and APIs for Agency Swarm v1.0.0 tool implementation, strongly prioritizing MCP servers.
+
+## Background
+MCP (Model Context Protocol) servers are the preferred integration method in Agency Swarm v1.0.0. They provide:
+- Standardized tool interfaces
+- No custom code maintenance
+- Automatic tool discovery
+- Built-in error handling
+- Community support and updates
+
+## Research Priority
+1. **MCP Servers First**: Always check for existing MCP servers
+2. **Official MCP Registry**: https://github.com/modelcontextprotocol/servers
+3. **NPM Packages**: Search `@modelcontextprotocol/*`
+4. **Community MCP**: Search GitHub for `mcp-server-*` repos
+5. **Custom APIs Last**: Only if no MCP server exists
+
+## Known MCP Servers
+Common MCP servers to check for:
+- `@modelcontextprotocol/server-filesystem` - File operations
+- `@modelcontextprotocol/server-github` - GitHub integration
+- `@modelcontextprotocol/server-gitlab` - GitLab integration
+- `@modelcontextprotocol/server-slack` - Slack integration
+- `@modelcontextprotocol/server-postgres` - PostgreSQL
+- `@modelcontextprotocol/server-sqlite` - SQLite
+- `@modelcontextprotocol/server-memory` - Memory/knowledge base
+- `@modelcontextprotocol/server-puppeteer` - Web automation
+- `@modelcontextprotocol/server-brave-search` - Web search
+- `@modelcontextprotocol/server-fetch` - HTTP requests
+
+## Process
+1. Understand agency's functionality needs from concept
+2. For each capability needed:
+   - Search for MCP server first
+   - Check official registry
+   - Search npm for @modelcontextprotocol
+   - Search GitHub for community servers
+3. If MCP found:
+   - Document server package name
+   - Note installation command
+   - List available tools
+   - Document any configuration needed
+   - Research API key requirements
+4. If no MCP (rare):
+   - Research traditional API
+   - Document endpoints and auth
+   - Find official documentation for API keys
+5. **Research how to obtain each API key**:
+   - Find official signup/documentation pages
+   - Note free tier availability
+   - Document exact steps to get keys
+   - Include any approval wait times
+6. Save findings to `agency_name/api_docs.md`
+
+# Output Format
+Create `agency_name/api_docs.md`:
+```markdown
+# API Documentation for [Agency Name]
+
+## MCP Servers Available
+
+### File Operations
+- **Package**: `@modelcontextprotocol/server-filesystem`
+- **Installation**: `npx -y @modelcontextprotocol/server-filesystem .`
+- **Tools Provided**:
+  - read_file: Read file contents
+  - write_file: Create or update files
+  - list_directory: List directory contents
+  - create_directory: Create new directories
+  - delete_file: Delete files
+  - move_file: Move or rename files
+- **Configuration**: Working directory path as argument
+- **API Keys**: None required
+
+### GitHub Integration
+- **Package**: `@modelcontextprotocol/server-github`
+- **Installation**: `npx -y @modelcontextprotocol/server-github`
+- **Tools Provided**:
+  - create_issue: Create GitHub issues
+  - create_pull_request: Create PRs
+  - list_issues: Get repository issues
+  - push_files: Push files to repository
+- **Configuration**: Repository name
+- **API Keys**: GITHUB_TOKEN required
+- **How to get GITHUB_TOKEN**:
+  1. Go to https://github.com/settings/tokens
+  2. Click "Generate new token (classic)"
+  3. Name it and select scopes: repo, workflow
+  4. Copy the token immediately (won't be shown again)
+
+## Traditional APIs (Only if no MCP)
+
+### [API Name]
+- **Base URL**: https://api.example.com
+- **Authentication**: Bearer token
+- **Key Endpoints**:
+  - GET /resource - List resources
+  - POST /resource - Create resource
+- **Rate Limits**: 100 requests/hour
+- **API Keys**: API_KEY required
+- **How to get API_KEY**:
+  1. Visit [official website]
+  2. Sign up for account
+  3. Navigate to API section
+  4. Generate new API key
+  5. Note any approval wait time
+
+## API Key Instructions
+
+### OPENAI_API_KEY (Required for all agencies)
+**How to obtain**:
+1. Go to https://platform.openai.com/api-keys
+2. Sign up or log in to OpenAI account
+3. Click "Create new secret key"
+4. Name your key (e.g., "agency-swarm")
+5. Copy and save the key immediately
+6. Add billing details at https://platform.openai.com/account/billing
+7. Minimum $5 credit recommended for testing
+
+### [OTHER_API_KEY]
+**How to obtain**:
+[Specific steps for this API]
+**Free tier**: [Yes/No, limitations]
+**Approval time**: [Immediate/X days]
+
+## Summary
+- MCP servers found: [count]
+- Traditional APIs needed: [count]
+- Total API keys required:
+  - OPENAI_API_KEY (always) - $5 minimum
+  - [List other keys with cost notes]
+```
+
+## MCP Server Benefits to Emphasize
+When MCP servers are available, note these advantages:
+- Zero maintenance of tool code
+- Automatic updates from community
+- Standardized error handling
+- Tool discovery built-in
+- Reduced agency complexity
+
+## Return Summary
+Report back:
+- File saved at: `agency_name/api_docs.md`
+- MCP servers found: [count and names]
+- Coverage: [X]% of needs covered by MCP
+- Custom APIs required: [list if any]
+- API keys needed: [complete list]
+- Recommendation: Use MCP servers for [specific functions]

.claude/agents/instructions-writer.md

@@ -0,0 +1,206 @@
+---
+name: instructions-writer
+description: Write optimized agent instructions using prompt engineering best practices
+tools: Write, Read, MultiEdit
+color: yellow
+model: sonnet
+---
+
+Write and refine Agency Swarm v1.0.0 agent instructions using prompt engineering best practices for maximum clarity and performance.
+
+## Background
+Agency Swarm agents need clear, actionable instructions that follow prompt engineering best practices. Instructions must be specific, example-driven, and integrate tools directly into numbered steps. Working in parallel with agent-creator and tools-creator during initial creation.
+
+## Prompt Engineering Principles
+Based on best practices:
+1. **Start Simple**: Use concise, verb-driven instructions
+2. **Be Specific**: Explicitly state desired outputs and formats
+3. **Provide Examples**: Include concrete examples of expected behavior
+4. **Use Positive Instructions**: "Do this" rather than "Don't do that"
+5. **Integrate Tools in Steps**: Show exactly when and how to use each tool
+6. **Use Variables**: Parameterize dynamic values with placeholders
+7. **Test Continuously**: Refine based on actual test results
+
+## Input Modes
+
+### Creation Mode (Parallel Execution)
+- PRD path with agent roles, tasks, and workflows
+- Communication flow pattern for the agency
+- Agency Swarm docs reference: https://agency-swarm.ai
+- Note: agent-creator creates folders in parallel, tools-creator runs AFTER us
+
+### Refinement Mode (After Testing)
+- Test results file path: `agency_name/test_results.md`
+- Specific failures to address
+- Performance metrics to improve
+
+## Instructions Template (v1.0.0)
+```markdown
+# Role
+You are **[specific role from PRD, e.g., "a data analysis expert specializing in financial reports"]**
+
+# Task
+Your task is to **[primary objective clearly stated]**:
+- [Specific subtask 1]
+- [Specific subtask 2]
+- [Quality expectations]
+
+# Context
+- You are part of [agency name] agency
+- You work alongside: [other agents and their roles]
+- Your outputs will be used for: [downstream purpose]
+- Key constraints: [time, format, or resource limitations]
+
+# Examples
+
+## Example 1: [Common Scenario Name]
+**Input**: "[Sample user request or message from another agent]"
+**Process**:
+1. Parse the request for [specific elements]
+2. Use ToolName to [specific action]
+3. Validate results contain [required fields]
+**Output**: "[Expected response format and content]"
+
+## Example 2: [Edge Case Scenario]
+**Input**: "[Unusual or error case]"
+**Process**:
+1. Detect [issue indicator]
+2. Use ErrorHandlingTool to [recovery action]
+3. Notify CEO agent with: "[specific message format]"
+**Output**: "[Graceful error response]"
+
+# Instructions
+1. **Receive Request**: Parse incoming messages for [specific keywords/patterns]
+2. **Validate Input**: Check that request contains [required fields] using format: `{field1: type, field2: type}`
+3. **Gather Information**: Use [ToolName1] to retrieve [data type] when [condition]
+4. **Process Data**:
+   - If [condition A]: Use [ToolName2] with parameters `{param1: value}`
+   - If [condition B]: Use [ToolName3] to [specific action]
+5. **Quality Check**: Verify output meets these criteria:
+   - [Criterion 1 with measurable threshold]
+   - [Criterion 2 with specific format]
+6. **Format Response**: Structure output as:
+   ```json
+   {
+     "status": "success/error",
+     "data": {...},
+     "next_steps": [...]
+   }
+   ```
+7. **Send Results**: Use SendMessage to deliver to [target agent] with message type "[category]"
+8. **Handle Errors**:
+   - On tool failure: Retry up to 3 times with exponential backoff
+   - On invalid input: Return structured error with guidance
+   - On timeout: Escalate to CEO with partial results
+
+# Additional Notes
+- Response time target: Under [X] seconds
+- Use [MCP_Server.tool_name] for file operations (more reliable than custom tools)
+- Always include confidence scores when making predictions
+- Preserve message thread context for multi-turn conversations
+- Log important decisions for audit trail
+```
+
+## MCP Server Tool Integration
+When MCP servers are used, integrate them directly into steps:
+```markdown
+3. **Read Configuration**: Use `Filesystem_Server.read_file` to load settings from `config.json`
+4. **Update Status**: Use `GitHub_Server.create_issue` with title format: "[STATUS] Task-{id}"
+```
+
+## Creation Process (Parallel Execution)
+
+1. **Analyze PRD** for each agent:
+   - Extract role with specific expertise
+   - Identify primary tasks and subtasks
+   - Note tool assignments from tools-creator
+   - Understand position in communication flow
+
+2. **Write Role Section**:
+   - Be specific about expertise area
+   - Use active voice and strong verbs
+   - Include domain context
+
+3. **Define Clear Task**:
+   - Start with primary objective
+   - Break down into measurable subtasks
+   - Include quality expectations
+
+4. **Provide Rich Context**:
+   - Agency purpose and structure
+   - Inter-agent relationships
+   - Downstream dependencies
+   - Operating constraints
+
+5. **Create Concrete Examples**:
+   - Common successful scenario
+   - Error/edge case handling
+   - Use actual tool names and parameters
+   - Show exact input/output formats
+
+6. **Write Numbered Instructions**:
+   - Each step should be actionable
+   - Integrate tools with specific conditions
+   - Include decision branches
+   - Specify exact formats and thresholds
+
+7. **Add Operational Notes**:
+   - Performance targets
+   - Preferred tool choices
+   - Common pitfalls to avoid
+   - Escalation procedures
+
+## Refinement Process (Test-Driven)
+
+1. **Parse Test Results** for patterns:
+   - Tool usage errors → Add specific parameters in steps
+   - Format errors → Provide exact schemas
+   - Logic errors → Add decision criteria
+   - Performance issues → Optimize step order
+
+2. **Update Specific Sections**:
+   - Add examples for failed scenarios
+   - Clarify ambiguous instructions
+   - Add validation steps
+   - Include error recovery procedures
+
+3. **Maintain Simplicity**:
+   - Keep language concise
+   - Remove redundant instructions
+   - Focus on observed issues only
+
+## Quality Checklist
+- [ ] Role is specific and expertise-focused
+- [ ] Task has measurable objectives
+- [ ] Context explains agency dynamics
+- [ ] At least 2 concrete examples provided
+- [ ] Tools integrated into numbered steps
+- [ ] Error handling explicitly defined
+- [ ] Output formats clearly specified
+- [ ] Performance targets included
+- [ ] Positive instructions used ("Do" not "Don't")
+- [ ] Variables parameterized with placeholders
+
+## File Ownership (CRITICAL)
+**instructions-writer owns**:
+- ALL instructions.md files in agent folders
+
+**instructions-writer MUST NOT touch**:
+- agent_name.py files (owned by agent-creator)
+- __init__.py files (owned by agent-creator)
+- Any files in tools/ folders (owned by tools-creator)
+- agency.py (owned by agent-creator/qa-tester)
+
+## Coordination with Parallel Agents
+- **agent-creator**: Creates folder structure (we create instructions.md)
+- **tools-creator**: Runs AFTER us (needs our instructions to test)
+- We CREATE instructions.md files (not update existing ones)
+
+## Return Summary
+Report back:
+- Instructions created for: [agent names with paths]
+- Examples provided: [count per agent]
+- Tools integrated into: [X] numbered steps
+- Error handling steps: [count]
+- Performance targets set: Yes/No
+- Ready for testing with qa-tester

.claude/agents/prd-creator.md

@@ -0,0 +1,213 @@
+---
+name: prd-creator
+description: Transform ideas into comprehensive PRDs optimized for parallel agent creation
+tools: Write, Read
+color: blue
+model: sonnet
+---
+
+Create Product Requirements Documents for Agency Swarm v1.0.0 agencies, optimized for parallel agent creation.
+
+## Background
+Agency Swarm v1.0.0 is built on OpenAI's Agents SDK. Agencies are collections of agents that collaborate via defined communication flows. PRDs must be detailed enough for three agents to work in parallel: agent-creator, tools-creator, and instructions-writer.
+
+## Input
+- User concept/idea with clarified goals
+- API/MCP documentation path: `agency_name/api_docs.md`
+- Framework version: Agency Swarm v1.0.0
+- Preferred communication pattern
+
+## Key Design Principles
+1. **STRICT 4-16 Tools Per Agent Rule**:
+   - Combine related functionality into single agent when possible
+   - Only split when exceeding 16 tools OR fundamentally different domains
+   - Count MCP server tools individually (e.g., filesystem server = 6 tools)
+2. **Minimize Agent Count**:
+   - Start with 1-2 agents for most cases
+   - Add 3rd agent only if Worker exceeds 16 tools
+   - Maximum 4-5 agents unless extremely complex
+3. **Single Entry Point**: One agent (usually CEO) interfaces with user
+4. **Clear Responsibilities**: No overlap between agents
+5. **MCP First**: Prioritize MCP servers over custom tools
+6. **Parallel-Ready**: Provide enough detail for simultaneous creation
+
+## Communication Flow Patterns
+
+### 1. Orchestrator-Workers (80% of cases)
+Best for: Task delegation, report generation, multi-step processes
+```
+CEO → Worker1 (data gathering)
+CEO → Worker2 (processing)
+CEO → Worker3 (reporting)
+```
+
+### 2. Sequential Pipeline (15% of cases)
+Best for: ETL, document processing, staged workflows
+```
+Collector → Processor → Publisher
+(with SendMessageHandoff for automatic handoffs)
+```
+
+### 3. Collaborative Network (5% of cases)
+Best for: Complex interdependent tasks, creative work
+```
+CEO ↔ Developer
+CEO ↔ Designer
+Developer ↔ Designer
+```
+
+## PRD Template
+```markdown
+# [Agency Name] - Product Requirements Document
+
+## Overview
+**Purpose**: [One sentence describing what the agency does]
+**Target Users**: [Who will use this agency]
+**Key Value**: [Primary benefit to users]
+
+## Agency Configuration
+- **Name**: agency_name (lowercase with underscores)
+- **Pattern**: [Orchestrator-Workers/Pipeline/Network]
+- **Entry Agent**: [Agent that receives user input]
+
+## Agents
+
+### Agent 1: CEO/Manager (Entry Point)
+- **Folder Name**: ceo
+- **Instance Name**: ceo (snake_case)
+- **Agent Name**: "CEO" (PascalCase in Agent() call)
+- **Description**: Orchestrates the agency and interfaces with users
+- **Primary Responsibilities**:
+  1. Accept and parse user requests
+  2. Delegate tasks to specialized agents
+  3. Synthesize results for user
+  4. Handle errors and edge cases
+- **Tools Needed**:
+  - Built-in: SendMessage (for agent communication)
+  - Custom: None (orchestration only)
+- **MCP Servers**: None
+
+### Agent 2: [Specialist Name]
+- **Folder Name**: specialist_name
+- **Instance Name**: specialist_name
+- **Agent Name**: "SpecialistName"
+- **Description**: [One line description]
+- **Primary Responsibilities**:
+  1. [Specific task 1]
+  2. [Specific task 2]
+  3. [Specific task 3]
+- **Tools Needed**:
+  - Tool1: [Purpose] - [MCP or Custom]
+  - Tool2: [Purpose] - [MCP or Custom]
+- **MCP Servers**:
+  - @modelcontextprotocol/server-name (if applicable)
+- **API Keys Required**: [List any specific keys]
+
+[Repeat for each agent...]
+
+## Communication Flows
+```python
+communication_flows = [
+    (ceo, specialist1),  # CEO delegates [type] tasks
+    (ceo, specialist2),  # CEO delegates [type] tasks
+]
+```
+
+## Tool Specifications
+
+### MCP Server Tools (Preferred)
+| Tool | Agent | MCP Server | Purpose |
+|------|-------|------------|---------|
+| filesystem ops | agent1 | @modelcontextprotocol/server-filesystem | File management |
+| github ops | agent2 | @modelcontextprotocol/server-github | Repository interaction |
+
+### Custom Tools (Only if no MCP)
+| Tool | Agent | Type | Inputs | Output |
+|------|-------|------|--------|--------|
+| ToolName | agent1 | BaseTool | param1: str | Result string |
+
+## Workflow Examples
+
+### Example 1: [Common Use Case]
+**User Input**: "[Sample user request]"
+**Flow**:
+1. CEO receives request
+2. CEO analyzes and delegates to Agent2: "[specific task]"
+3. Agent2 uses Tool1 to [action]
+4. Agent2 returns result to CEO
+5. CEO formats and returns to user
+
+### Example 2: [Error Case]
+**Scenario**: [What could go wrong]
+**Handling**: [How agency handles it]
+
+## Dependencies
+- **Required API Keys**:
+  - OPENAI_API_KEY (always required)
+  - [Additional keys from tools]
+- **Python Packages**:
+  - agency-swarm>=1.0.0
+  - python-dotenv
+  - [Tool-specific packages]
+
+## Success Metrics
+- [ ] All agents respond to their designated tasks
+- [ ] Communication flows work bidirectionally
+- [ ] Error messages are clear and actionable
+- [ ] Response time under [X] seconds
+- [ ] MCP servers initialize correctly
+
+## Parallel Creation Notes
+This PRD is designed for parallel execution:
+- **agent-creator**: Use agent specifications to create modules
+- **tools-creator**: Use tool specifications and MCP servers
+- **instructions-writer**: Use responsibilities and workflows
+```
+
+## Process
+1. Read API docs to identify available MCP servers and count tools
+2. **Apply Minimum Agent Strategy**:
+   - Count total tools needed (MCP + custom)
+   - If ≤8 tools: Use 1 agent (Worker)
+   - If ≤16 tools: Use 2 agents (CEO + Worker)
+   - If 17-32 tools: Use 3 agents (CEO + 2 specialists)
+   - If 33-48 tools: Use 4 agents (CEO + 3 specialists)
+   - Only exceed 4 agents for truly complex cases
+3. **Group tools by function**:
+   - Data collection tools → one agent
+   - Processing/analysis tools → one agent
+   - Reporting/output tools → can be in same agent
+   - Don't split just for organization - only for tool count
+4. Map tools to agents:
+   - Pack agents to 10-14 tools each (room for growth)
+   - Each tool belongs to ONE agent
+   - Prefer MCP servers (count their tools)
+5. Define minimal communication flows:
+   - Use Orchestrator-Workers pattern (simplest)
+   - Avoid complex networks unless essential
+6. Create detailed workflow examples
+7. Document all requirements
+8. **Final check**: Can we reduce agent count further?
+9. Save to `agency_name/prd.txt` with agent count justification
+
+## Quality Checklist
+- [ ] **Minimum agents used** (1-2 for most cases, 3-4 max)
+- [ ] Each agent has 4-16 tools (aim for 10-14)
+- [ ] Agent count justified by tool count, not organization
+- [ ] No tool duplication across agents
+- [ ] Communication flows are simple (prefer Orchestrator-Workers)
+- [ ] MCP servers prioritized over custom tools
+- [ ] Tool counts include all MCP server tools
+- [ ] Workflow examples are concrete
+- [ ] All API keys documented
+- [ ] Could NOT reduce agent count further
+
+## Return Summary
+Report back:
+- PRD created at: `agency_name/prd.txt`
+- Agents defined: [count and names]
+- Communication pattern: [which pattern]
+- MCP coverage: [X]% of tools via MCP
+- Custom tools needed: [count]
+- API keys required: [complete list]
+- Ready for parallel creation: Yes

.claude/agents/qa-tester.md

@@ -0,0 +1,179 @@
+---
+name: qa-tester
+description: Wire agency and test with 5 example queries, provide improvement suggestions
+tools: Write, Read, Bash, Edit, MultiEdit
+color: red
+model: sonnet
+---
+
+Wire agency components and test with 5 realistic queries, then provide specific improvement suggestions.
+
+## Background
+Agency Swarm v1.0.0 testing focuses on real-world usage. Tools are already tested by tools-creator. Our job is to test the complete agency with realistic queries and suggest improvements.
+
+## Prerequisites
+- API keys already collected and in .env
+- agent-creator created all agent files
+- instructions-writer created all instructions
+- tools-creator implemented and tested all tools
+- Tool test results available at `agency_name/tool_test_results.md`
+
+## Testing Process
+
+### 1. Wire agency.py
+Complete the agency setup based on PRD:
+```python
+from dotenv import load_dotenv
+from agency_swarm import Agency
+from agent1_folder.agent1 import agent1
+from agent2_folder.agent2 import agent2
+
+load_dotenv()
+
+agency = Agency(
+    agent1,  # CEO/entry point from PRD
+    communication_flows=[
+        (agent1, agent2),
+    ],
+    shared_instructions="agency_manifesto.md",
+)
+
+if __name__ == "__main__":
+    # Test with programmatic interface
+    response = agency.get_response("test query")
+    print(response)
+```
+
+### 2. Quick Validation
+```bash
+# Verify all dependencies installed
+pip list | grep agency-swarm
+
+# Check tool test results
+cat agency_name/tool_test_results.md
+```
+
+### 3. Generate 5 Test Queries
+Based on PRD functionality, create 5 diverse test queries:
+1. **Basic capability test** - Simple task using core functionality
+2. **Multi-step workflow** - Task requiring agent collaboration
+3. **Edge case handling** - Unusual but valid request
+4. **Error recovery** - Invalid input or missing data
+5. **Complex real-world scenario** - Comprehensive task
+
+### 4. Execute Test Queries
+Run each query and document:
+```python
+test_queries = [
+    "Query 1: [Basic task from PRD]",
+    "Query 2: [Multi-agent collaboration task]",
+    "Query 3: [Edge case scenario]",
+    "Query 4: [Error handling test]",
+    "Query 5: [Complex real-world request]"
+]
+
+for i, query in enumerate(test_queries, 1):
+    print(f"\n=== Test {i} ===")
+    print(f"Query: {query}")
+    response = agency.get_response(query)
+    print(f"Response: {response}")
+    # Document response quality, accuracy, completeness
+```
+
+### 5. Create Comprehensive Test Report
+Save to `agency_name/qa_test_results.md`:
+```markdown
+# QA Test Results - [timestamp]
+
+## Agency Configuration
+- Agents: [count and names]
+- Communication pattern: [type]
+- Tools per agent: [breakdown]
+
+## Test Query Results
+
+### Test 1: Basic Capability
+**Query**: "[exact query]"
+**Expected**: [what should happen based on PRD]
+**Actual Response**: "[full response]"
+**Quality Score**: 8/10
+**Issues**:
+- [Any problems observed]
+**Status**: ✅ PASSED / ⚠️ PARTIAL / ❌ FAILED
+
+### Test 2: Multi-Agent Collaboration
+[Same format...]
+
+### Test 3: Edge Case
+[Same format...]
+
+### Test 4: Error Handling
+[Same format...]
+
+### Test 5: Complex Scenario
+[Same format...]
+
+## Performance Metrics
+- Average response time: [X] seconds
+- Success rate: [X]/5 queries
+- Error handling: [Good/Needs work]
+- Response quality: [1-10 scale]
+- Completeness: [1-10 scale]
+
+## Improvement Suggestions
+
+### For Instructions (instructions-writer)
+1. **Agent: [name]** - Instruction unclear on [specific step]
+   - Current: "[problematic instruction]"
+   - Suggested: "[improved instruction]"
+2. [Additional specific improvements]
+
+### For Tools (tools-creator)
+1. **Tool: [name]** - Needs better error handling
+   - Issue: [specific problem]
+   - Fix: [specific solution]
+2. [Additional tool improvements]
+
+### For Communication Flow
+1. Consider adding [specific flow] for [reason]
+2. [Other architectural suggestions]
+
+## Overall Assessment
+- **Ready for Production**: Yes/No
+- **Critical Issues**: [list if any]
+- **Recommended Next Steps**:
+  1. [Specific action]
+  2. [Specific action]
+  3. [Specific action]
+
+## Specific Files to Update
+- `agent_name/instructions.md` - Lines X-Y need clarity
+- `agent_name/tools/ToolName.py` - Add validation for [input]
+- `agency.py` - Consider adding [feature]
+```
+
+### 6. Test Different Query Styles
+Vary the query formats to test robustness:
+- Direct commands: "Do X"
+- Questions: "How can I...?"
+- Complex requests: "I need to X, then Y, considering Z"
+- Incomplete info: "Help me with [vague request]"
+- Follow-ups: Test multi-turn conversations
+
+## Key Testing Focus
+1. **Realistic queries** - Use examples that real users would ask
+2. **Actual task completion** - Verify the agency produces useful results
+3. **Tool integration** - Ensure MCP servers and tools work correctly
+4. **Error handling** - Test graceful failure modes
+5. **Response quality** - Check for completeness and accuracy
+
+## Return Summary
+Report back:
+- Test results saved at: `agency_name/qa_test_results.md`
+- Tests passed: [X]/5
+- Agency status: ✅ READY / ⚠️ NEEDS IMPROVEMENTS / ❌ MAJOR ISSUES
+- Top 3 improvements needed:
+  1. [Most important fix]
+  2. [Second priority]
+  3. [Third priority]
+- Specific agents needing updates: [list with reasons]

.claude/agents/tools-creator.md

@@ -0,0 +1,335 @@
+---
+name: tools-creator
+description: Implement and test tools with MCP servers preferred, runs after agent files exist
+tools: Write, Read, Grep, MultiEdit, Bash
+color: orange
+model: sonnet
+---
+
+Implement production-ready Agency Swarm v1.0.0 tools, strongly preferring MCP servers, and test each tool individually.
+
+## Background
+Agency Swarm v1.0.0 strongly prefers MCP (Model Context Protocol) servers. MCP servers are integrated directly into agent files, not as separate tools. Runs AFTER agent-creator and instructions-writer complete.
+
+## Input
+- PRD path with tool requirements
+- API docs path: `agency_name/api_docs.md` (contains MCP servers and APIs)
+- API keys already collected from user
+- Agent files already created by agent-creator
+- Instructions already created by instructions-writer
+
+## MCP Server Integration (CRITICAL - Based on Official Docs)
+
+### Step 1: Identify MCP Servers from api_docs.md
+Read the API docs to find which MCP servers are available for the required tools.
+
+### Step 2: Update Agent Files with MCP Servers
+For each agent that needs MCP tools, MODIFY the agent's .py file:
+
+```python
+from agency_swarm import Agent
+from agency_swarm.tools.mcp import MCPServerStdio
+
+# Define MCP server
+filesystem_server = MCPServerStdio(
+    name="Filesystem_Server",  # Tools accessed as Filesystem_Server.read_file
+    params={
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
+    },
+    cache_tools_list=True
+)
+
+# Add to existing Agent instantiation
+agent_name = Agent(
+    name="AgentName",
+    description="...",
+    instructions="./instructions.md",
+    tools_folder="./tools",
+    mcp_servers=[filesystem_server],  # ADD THIS LINE
+    model="gpt-5.4",
+    model_settings=ModelSettings(
+        max_tokens=25000,
+    ),
+)
+```
+
+### Common MCP Servers
+```python
+# GitHub Server
+github_server = MCPServerStdio(
+    name="GitHub_Server",
+    params={
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-github"],
+        "env": {"GITHUB_TOKEN": os.getenv("GITHUB_TOKEN")},
+    },
+    cache_tools_list=True
+)
+
+# Slack Server (if available)
+slack_server = MCPServerStdio(
+    name="Slack_Server",
+    params={
+        "command": "npx",
+        "args": ["-y", "@modelcontextprotocol/server-slack"],
+        "env": {"SLACK_TOKEN": os.getenv("SLACK_TOKEN")},
+    },
+    cache_tools_list=True
+)
+```
+
+### Custom Tool Pattern (ONLY if no MCP)
+Place in `agency_name/agent_name/tools/ToolName.py`:
+```python
+from agency_swarm.tools import BaseTool
+from pydantic import Field
+import os
+from dotenv import load_dotenv
+
+load_dotenv()
+
+class ToolName(BaseTool):
+    """Clear description for agent."""
+
+    input_field: str = Field(..., description="Input description")
+
+    def run(self):
+        api_key = os.getenv("API_KEY_NAME")
+        if not api_key:
+            return "Error: API_KEY_NAME not found"
+
+        try:
+            # Real implementation
+            result = self.perform_operation()
+            return str(result)
+        except Exception as e:
+            return f"Error: {str(e)}"
+
+if __name__ == "__main__":
+    # Test with real data
+    tool = ToolName(input_field="test_value")
+    print(tool.run())
+```
+
+## Best Practices for Custom Tools
+
+### 1. Provide Next-Step Hints
+Guide the agent on what to do next:
+```python
+class QueryDatabase(BaseTool):
+    question: str = Field(...)
+
+    def run(self):
+        context = self.query_database(self.question)
+
+        if context is None:
+            # Tell agent what to do next
+            raise ValueError("No context found. Please try a different search term or ask the user for clarification.")
+        else:
+            return context
+```
+
+### 3. Use Specific Types
+Restrict inputs to valid values:
+```python
+from typing import Literal
+from pydantic import EmailStr
+
+class RunCommand(BaseTool):
+    """Execute predefined system commands."""
+
+    command: Literal["start", "stop", "restart"] = Field(
+        ...,
+        description="Command to execute: 'start', 'stop', or 'restart'."
+    )
+
+class EmailSender(BaseTool):
+    recipient: EmailStr = Field(..., description="Valid email address.")
+```
+
+### 4. Use Shared State for Flow Control
+Shared state is a centralized dictionary accessible by all tools and agents. Use it to share data without parameter passing.
+
+#### Shared State Key Concepts
+- **Shared State**: All tools within an agency share a Python dictionary (`self._shared_state`)
+- **Data Sharing**: Tools can exchange data without explicit parameter passing
+- **Flow Control**: Use shared state to enforce tool execution order
+- **Note**: Shared state only works when tools are deployed with agents (not as separate APIs)
+
+#### Common Shared State Patterns
+1. **Data Collection → Processing**: Tool A collects data, Tool B processes it
+2. **Multi-Step Workflows**: Each tool marks its completion for the next
+3. **Session Management**: Store user session data across tools
+4. **Cache Results**: Avoid redundant API calls by caching in shared state
+5. **Error Context**: Store error details for debugging across tools
+
+**Setting values**:
+```python
+class QueryDatabase(BaseTool):
+    """Retrieves data and stores it in shared state."""
+    question: str = Field(..., description="The query to execute.")
+
+    def run(self):
+        # Fetch data
+        context = query_database(self.question)
+
+        # Store in shared state for other tools to use
+        self._shared_state.set('context', context)
+        self._shared_state.set('query_timestamp', datetime.now())
+
+        return "Context retrieved and stored successfully."
+```
+
+**Getting values**:
+```python
+class GenerateReport(BaseTool):
+    """Generates report using data from shared state."""
+    format: str = Field(..., description="Report format")
+
+    def run(self):
+        # Get data from shared state
+        context = self._shared_state.get('context')
+        timestamp = self._shared_state.get('query_timestamp')
+
+        if not context:
+            raise ValueError("No context found. Please run QueryDatabase first.")
+
+        # Use the shared data
+        report = self.generate_report(context, timestamp, self.format)
+        return report
+```
+
+**Flow validation**:
+```python
+class Action2(BaseTool):
+    input: str = Field(...)
+
+    def run(self):
+        # Check if previous action completed
+        if self._shared_state.get("action_1_complete") != True:
+            raise ValueError("Please complete Action1 first before proceeding.")
+
+        # Perform action
+        result = self.perform_action(self.input)
+
+        # Mark this action as complete
+        self._shared_state.set("action_2_complete", True)
+        self._shared_state.set("action_2_result", result)
+
+        return "Action 2 completed successfully."
+```
+
+### 5. Combine Multiple Methods
+Make complex tools readable:
+```python
+class DataProcessor(BaseTool):
+    """Process data through multiple stages."""
+
+    input_data: str = Field(...)
+
+    def run(self):
+        # Step 1: Validate
+        validated_data = self.validate_input(self.input_data)
+        # Step 2: Process
+        processed_data = self.process_data(validated_data)
+        # Step 3: Format
+        output = self.format_output(processed_data)
+        return output
+
+    def validate_input(self, data):
+        # Validation logic
+        return data
+
+    def process_data(self, data):
+        # Processing logic
+        return data
+
+    def format_output(self, data):
+        # Formatting logic
+        return data
+```
+
+## Process (Runs AFTER agent-creator and instructions-writer)
+
+1. **Read PRD and API docs**:
+   - Identify which agent needs which tools
+   - Check which MCP servers are available
+
+2. **For each agent's tools**:
+   - **First check**: Is there an MCP server?
+   - If YES → Update agent's .py file to add MCP server
+   - If NO → Create custom tool in tools/ folder
+
+3. **Implement MCP Servers** (CRITICAL):
+   - Open the agent's .py file
+   - Import MCPServerStdio at the top
+   - Define the MCP server instance
+   - Add `mcp_servers=[server_instance]` to Agent()
+   - Test that the server initializes
+
+4. **Test EVERY tool individually**:
+   ```bash
+   # Test custom tools
+   python agency_name/agent_name/tools/ToolName.py
+
+   # Test MCP server initialization
+   python -c "from agency_name.agent_name import agent_name; print('MCP loaded')"
+   ```
+
+5. **Update and install requirements.txt**:
+    - Add all new dependencies to requirements.txt
+    - Make sure venv is activated
+    - Run `pip install -r requirements.txt`
+
+6. **Test and iterate on each tool**:
+   Test each tool by running each ToolName.py file
+   - Make sure each tool is working as expected
+   - Apply best practices:
+     - Add chain-of-thought for complex tools
+     - Provide helpful error messages
+     - Use specific types (Literal, EmailStr)
+     - Implement shared state for data passing between tools
+     - Add flow validation using shared state
+     - Include proper test cases
+   - If not working, fix the issue
+   - Keep iterating until all tools pass tests
+   - **Important**: Do not come back to the user until all tools are working as expected.
+
+## File Ownership (CRITICAL)
+**tools-creator owns**:
+- All files in tools/ folders
+- Modifications to agent .py files (ONLY for MCP servers)
+- tool_test_results.md
+
+**tools-creator MUST NOT touch**:
+- instructions.md files
+- __init__.py files
+- agency.py (except imports if needed)
+
+## Common Mistakes to Avoid
+1. **DON'T create mcp_config.py** - MCP servers go directly in agent files
+2. **DON'T skip testing** - Test every single tool with real data
+3. **DON'T create custom tools if MCP exists**
+4. **DO import os and load_dotenv for API keys**
+5. **DO add all MCP servers to the agent's mcp_servers list**
+6. **DON'T use print() in tools** - Return strings instead
+7. **DO handle errors gracefully** - Return error messages, don't crash
+8. **DO include test cases** - Every tool file needs if __name__ == "__main__"
+9. **DON'T hardcode values** - Use environment variables or parameters
+10. **DO validate inputs** - Check types and ranges before processing
+
+## Return Summary
+Report back:
+- MCP servers integrated into agents: [list with agent names]
+- Custom tools created: [list with file paths]
+- Test results saved at: `agency_name/tool_test_results.md`
+- All tools tested: ✅/❌
+- Failed tools needing fixes: [list]
+- Best practices applied:
+  - Chain-of-thought tools: [count]
+  - Tools with type restrictions: [count]
+  - Tools with helpful error hints: [count]
+  - Shared state usage: [tools using it]
+  - All tools have test cases: Yes/No
+- Dependencies added to requirements.txt

.cursor/rules/writing-docs.mdc

@@ -0,0 +1,153 @@
+---
+alwaysApply: true
+---
+
+When writing or improving documentation for Agency Swarm, your primary goal is clarity for the target reader: show the information they need to complete the task, with enough context to avoid confusion.
+
+# Agency Swarm Documentation Writing Rules
+
+- Write documentation in an easy to understand conversational language.
+- Use simple language and clear terms.
+- Docs should be easily readable by an 8th grader.
+- Be concise, but keep full sentences and transitions when they are needed for readability.
+- Make documentation actionable. Place code snippets at the top so users can easily copy and paste them. Provide only essential context above the code. Move any complex or detailed explanations to the end of the page.
+- The more important the information is, the higher it should be on the page.
+- Highlight the important parts by using bold, components, etc.
+- Hide complexity under tabs, dropdowns, etc.
+- Split pages into sub pages if needed. Use ~150 visible lines as a readability target, not a hard limit. Collapsed content (for example accordions) does not count toward this target.
+
+## Release Notes
+
+Use these rules for release notes so the intro stays readable and every claim stays tied to a shipped change.
+
+- Write the opening paragraph and each section intro for non-technical readers first. In one or two sentences, say what changed and why it matters in plain English.
+- Ground every phrase in a concrete change from the repo or release diff. If a phrase cannot be tied to a command, API, capability, limit, or fix, delete it.
+- Prefer plain verbs and nouns like `start`, `open`, `run`, `set up`, `use`, and `fix`.
+- Avoid vague opener words like `documented`, `surface`, `workflow`, `path`, and `behavior` unless the exact term is required for accuracy.
+- Keep the intro broad and easy to read, then let the bullets carry the exact commands, APIs, models, limits, PR numbers, and contributor names.
+- Group sections by reader value, not by implementation layer.
+- Do not present internal policy or agent-rule changes as public docs. If they must be included, label them as internal maintenance and keep them brief.
+
+# Mintlify Components Reference
+
+You can utilize various components from mintlify:
+
+## Accordion
+
+Collapsible sections for optional or detailed content:
+
+```mdx
+<Accordion title="Advanced Options" defaultOpen={false}>
+  Content here
+</Accordion>
+```
+
+## Tabs
+
+Switch between different code examples or content:
+
+```mdx
+<Tabs>
+  <Tab title="Python">Python code</Tab>
+  <Tab title="JavaScript">JS code</Tab>
+</Tabs>
+```
+
+## Cards
+
+Highlight key links or concepts:
+
+```mdx
+<Card title="Getting Started" icon="rocket-launch" href="/quickstart">
+  Start building your first agency
+</Card>
+```
+
+## Steps
+
+Display sequential instructions:
+
+```mdx
+<Steps>
+  <Step title="Install">Install the package</Step>
+  <Step title="Configure">Set up your config</Step>
+</Steps>
+```
+
+## CodeGroup
+
+Group related code examples:
+
+````mdx
+<CodeGroup>
+  ```python example.py
+  # Python version
+````
+
+```javascript example.js
+// JS version
+```
+
+</CodeGroup>
+```
+
+## API Components
+
+For API documentation:
+
+```mdx
+<ParamField param="name" type="string" required>
+  Parameter description
+</ParamField>
+
+<ResponseField name="status" type="string">
+  Response field description
+</ResponseField>
+```
+
+# Instructions
+
+## Before Starting
+
+If style is unclear, review one or more of these examples:
+
+- [Tools](docs/core-framework/tools/overview.mdx)
+- [Agents](docs/core-framework/agents/overview.mdx)
+- [Agencies](docs/core-framework/agencies/overview.mdx)
+- [Communication Flows](docs/core-framework/agencies/communication-flows.mdx)
+
+Use these examples as guidance, not strict templates.
+
+## Updating Existing Pages
+
+1. Analyze the feedback provided by the user and determine which specific sections you need to update.
+   - If there is a lot of feedback, create a to-do list for yourself and break it down.
+2. Only update the required parts, do not add anything unrequested. Perform minimal changes, keep everything unaffected by feedback as is. Only update the parts and the pages that are explicitly requested.
+3. If asked to move the page, keep consistent folder and file structure, matching the structure in the `./docs/docs.json` file.
+4. Ask the user to review the changes and provide feedback.
+
+## Writing New Pages
+
+1. Analyze the information or the relevant code provided by the user.
+   - If critical information is missing, ask only the minimum questions needed to proceed.
+   - For example:
+     - What is the use case for this?
+     - Where can I see relevant files?
+     - Do you have any example code snippets?
+     - Why did you create this feature in the first place?
+     - What does the user have to know before they can start using it?
+     - etc...
+2. Create a new page reference in the `./docs/docs.json` file in the appropriate group and sub group.
+   - If it's unclear where to place the page, ask the user for clarification.
+   - Make sure the folder structure in docs folder matches the structure in the `./docs/docs.json` file.
+3. Write the page content using the same path, following all the rules above.
+4. Ask the user to review the page and provide feedback.
+5. Implement any adjustments as needed. See "Updating Existing Pages" section below.
+
+# Additional Notes
+
+-
+
+# References
+
+- [Mintlify Documentation](https://www.mintlify.com/docs/llms.txt) - Check if you need clarification about how mintlify works or looking for any other components.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,28 @@
+---
+name: Bug report
+about: Report a bug
+title: ''
+labels: bug
+assignees: ''
+
+---
+
+### Please read this first
+
+- **Have you read the docs?**[Agency Swarm docs](https://agency-swarm.ai/)
+- **Have you searched for related issues?** Others may have faced similar issues.
+
+### Describe the bug
+A clear and concise description of what the bug is.
+
+### Debug information
+- Agency Swarm version: (e.g. `v1.0.0`)
+- Python version (e.g. Python 3.13)
+
+### Repro steps
+
+Ideally provide a minimal python script that can be run to reproduce the bug.
+
+
+### Expected behavior
+A clear and concise description of what you expected to happen.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,16 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+### Please read this first
+
+- **Have you read the docs?**[Agency Swarm docs](https://agency-swarm.ai/)
+- **Have you searched for related issues?** Others may have had similar requests
+
+### Describe the feature
+What is the feature you're requesting? How would it work? Please provide examples and details if possible.

.github/ISSUE_TEMPLATE/question.md

@@ -0,0 +1,16 @@
+---
+name: Question
+about: Questions about the framework
+title: ''
+labels: question
+assignees: ''
+
+---
+
+### Please read this first
+
+- **Have you read the docs?**[Agency Swarm docs](https://agency-swarm.ai/)
+- **Have you searched for related issues?** Others may have had similar requests
+
+### Question
+Describe your question. Provide details if available.

.github/PULL_REQUEST_TEMPLATE/pull_request_template.md

@@ -0,0 +1,18 @@
+### Summary
+
+<!-- Please give a short summary of the change and the problem this solves. -->
+
+### Test plan
+
+<!-- Please explain how this was tested -->
+
+### Issue number
+
+<!-- For example: "Closes #1234" -->
+
+### Checks
+
+- [ ] I've added new tests (if relevant)
+- [ ] I've added/updated the relevant documentation
+- [ ] I've run `make lint` and `make format`
+- [ ] I've made sure tests pass

.github/dependabot.yml

@@ -0,0 +1,6 @@
+version: 2
+updates:
+  - package-ecosystem: "uv"
+    directory: "/"
+    schedule:
+      interval: "weekly"

.github/workflows/close-issues.yml

@@ -0,0 +1,24 @@
+name: Close inactive issues
+on:
+  schedule:
+    - cron: "30 1 * * *"
+
+  workflow_dispatch:
+
+jobs:
+  close-issues:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/stale@v5
+        with:
+          days-before-issue-stale: 30
+          days-before-issue-close: 14
+          stale-issue-label: "stale"
+          stale-issue-message: "This issue is stale because it has been open for 30 days with no activity. Please upgrade to the latest version and test it again."
+          close-issue-message: "This issue was closed because it has been inactive for 14 days since being marked as stale. If the issue still persists, please reopen."
+          days-before-pr-stale: -1
+          days-before-pr-close: -1
+          repo-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/issues.yml

@@ -0,0 +1,26 @@
+name: Close inactive issues
+on:
+  schedule:
+    - cron: "30 1 * * *"
+
+jobs:
+  close-issues:
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - uses: actions/stale@v9
+        with:
+          days-before-issue-stale: 7
+          days-before-issue-close: 3
+          stale-issue-label: "stale"
+          stale-issue-message: "This issue is stale because it has been open for 7 days with no activity."
+          close-issue-message: "This issue was closed because it has been inactive for 3 days since being marked as stale."
+          any-of-issue-labels: 'question,needs-more-info'
+          days-before-pr-stale: 10
+          days-before-pr-close: 7
+          stale-pr-label: "stale"
+          stale-pr-message: "This PR is stale because it has been open for 10 days with no activity."
+          close-pr-message: "This PR was closed because it has been inactive for 7 days since being marked as stale."
+          repo-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/live-openai-tests.yml

@@ -0,0 +1,29 @@
+name: Live OpenAI Tests
+
+on:
+  workflow_dispatch:
+
+env:
+  UV_FROZEN: "1"
+
+jobs:
+  live_openai_tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up uv (Python 3.13)
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: make sync
+
+      - name: Run tests with coverage (live OpenAI enabled)
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          CI: "false"
+        run: make coverage

.github/workflows/publish.yml

@@ -0,0 +1,36 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types:
+      - published
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    environment:
+      name: pypi
+      url: https://pypi.org/p/agency-swarm
+    permissions:
+      id-token: write # Important for trusted publishing to PyPI
+    runs-on: ubuntu-latest
+    env:
+      OPENAI_API_KEY: fake-for-tests
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+      - name: Setup uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - name: Install dependencies
+        run: make sync
+      - name: Build package
+        run: uv build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

.github/workflows/tests.yml

@@ -0,0 +1,97 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    paths:
+      - ".github/workflows/tests.yml"
+      - "Makefile"
+      - "pyproject.toml"
+      - "uv.lock"
+      - "src/**"
+      - "tests/**"
+      - "examples/**"
+
+env:
+  UV_FROZEN: "1"
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up uv (3.13)
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: "3.13"
+      - name: Install dependencies
+        run: make sync
+      - name: Run lint
+        run: make lint
+
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Set up uv (3.13)
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: "3.13"
+      - name: Install dependencies
+        run: make sync
+      - name: Run mypy
+        run: make mypy
+
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up uv (Python 3.13)
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: make sync
+
+      - name: Run tests with coverage
+        if: github.event_name != 'pull_request' || (github.event.pull_request.user.login != 'dependabot[bot]' && !github.event.pull_request.head.repo.fork)
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: make coverage
+
+      - name: Run unit tests for PRs without secrets
+        if: github.event_name == 'pull_request' && (github.event.pull_request.user.login == 'dependabot[bot]' || github.event.pull_request.head.repo.fork)
+        run: uv run pytest tests/test_*_modules
+
+  tests_py312:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up uv (Python 3.12)
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: make sync
+
+      - name: Run tests with coverage (3.12)
+        env:
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: make coverage

.gitignore

@@ -0,0 +1,193 @@
+# macOS Files
+.DS_Store
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+**/__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pdm
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.venv39
+.venv_res
+
+# Local agent state
+.codex/requirements-ledger/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+.idea/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+.aider*
+
+# Logs
+logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+dev-debug.log
+# Dependency directories
+node_modules/
+package-lock.json
+# Environment variables
+# Editor directories and files
+.idea
+.vscode
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+# OS specific
+# Task files
+tasks.json
+tasks/
+# Custom Ignores
+/scripts/
+/references/
+
+# Vector store directories (contain environment-specific OpenAI IDs)
+*_vs_*/
+
+# Temporary file_search directories
+file_search_*/
+
+# Agency Swarm visualization outputs
+agency_*.html
+agency_*.png
+agency_*.json
+*_visualization.html
+debug_agency_data.json
+
+.taskmaster/
+.agency_swarm/
+.claude/worktrees/
+
+work_context.md

.pre-commit-config.yaml

@@ -0,0 +1,21 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: trailing-whitespace
+        exclude: ^docs/
+      - id: end-of-file-fixer
+        exclude: ^docs/
+      - id: check-yaml
+      - id: check-toml
+      - id: debug-statements
+        language_version: python3
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.9
+    hooks:
+      - id: ruff
+        args: [--fix, --select=I]
+        exclude: ^docs/
+      - id: ruff-format
+        exclude: ^docs/

.prettierignore

@@ -0,0 +1,2 @@
+*.mdx
+*.md

.prettierrc

@@ -0,0 +1,11 @@
+{
+    "tabWidth": 4,
+    "overrides": [
+        {
+            "files": "*.yml",
+            "options": {
+                "tabWidth": 2
+            }
+        }
+    ]
+}

AGENTS.md

@@ -0,0 +1,500 @@
+# Instruction File Contract
+
+## 1. Definitions
+1.1 `Instruction File`: the policy text in `AGENTS.md` and its Mirror Link.
+1.2 `Mirror Link`: the symlink at `CLAUDE.md` that points to `AGENTS.md`.
+1.3 `User Request`: any explicit user direction, issue, failure, contradiction, odd behavior, or useful clue that changes the work.
+1.4 `Manager`: an agent with a real Native Subagent capability.
+1.5 `Subagent`: an agent without that capability, or one acting under delegation.
+1.6 `Native Subagent`: the built-in delegation capability.
+1.7 `Default Native Subagent Policy`: model `gpt-5.4` with `high` reasoning.
+1.8 `Mandate`: the authorized action, repository, branch, artifact, and visibility boundary for the task.
+1.9 `Requirement Ledger`: the durable requirement system provided by the `requirement-ledger` skill.
+1.10 `Execution Plan`: the short current-task plan stored in the plan tool.
+1.11 `Active Queue`: the active, unfulfilled items in the Requirement Ledger.
+1.12 `Active Artifact`: any repository, worktree, branch, pull request, file, temporary asset, background terminal, or review artifact the agent owns.
+1.13 `Critical Path`: the shortest safe sequence that advances the highest-priority active item.
+1.14 `Default Branch`: the canonical remote-tracking main branch, currently `origin/main`.
+1.15 `Remote Preflight`: `git fetch origin`, `git status -sb`, and `git rev-parse --short HEAD`.
+1.16 `Structure Probe`: `make prime`.
+1.17 `Formatter`: `make format`.
+1.18 `Checker`: `make check`.
+1.19 `Full Suite`: `make ci`.
+1.20 `Docs Preview`: `cd docs && mintlify dev`.
+1.21 `Documentation Rule Set`: `.cursor/rules/writing-docs.mdc`.
+1.22 `Codex Review`: a clean independent Codex review, required only when this contract, risk, or the User Request requires it.
+1.23 `Codex Channel`: a native Codex subagent or the `codex` CLI.
+1.24 `General Review Command`: `codex review --base origin/main -c model_reasoning_effort="high"`.
+1.25 `Policy Review Command`: `codex -m gpt-5.5 review --base origin/main -c model_reasoning_effort="xhigh"`.
+1.26 `Pre-Release Review Command`: `codex -m gpt-5.5 review --base origin/main -c model_reasoning_effort="xhigh"`.
+1.27 `Fallback Review Command`: an equivalent `codex exec` diff review using the same base and reasoning class.
+1.28 `Primary Review Artifact`: `/tmp/codex_review_<short_sha>.txt`.
+1.29 `Pre-PR Gate`: the risk-based local verification before pull-request mutation, ranging from focused checks to the Full Suite.
+1.30 `CI`: a hosted continuous-integration signal, required only when policy, risk, or the User Request requires it.
+1.31 `UX Verification Gap`: any unresolved mismatch between claimed user behavior and proved user behavior.
+1.32 `Merge Mandate`: the minimum internal merge-readiness state. It does not grant merge authority.
+1.33 `Danger Zone`: any Public Operation.
+1.34 `Public Operation`: any public or irreversible state mutation, including merge, tag, release note, publish, yank, or unpublish.
+1.35 `Public PR`: a pull request visible outside a private local workspace.
+1.36 `Policy Edit`: any change to the Instruction File, related symlink state, skills, policy tooling, or durable policy enforcement text.
+1.37 `Drift Audit`: a fresh comparison against the relevant upstream baseline or last known clean state.
+1.38 `End-User Proof`: rerunning the exact reported user flow in the same class of released or installed artifact and observing success.
+1.39 `Escalation`: the only allowed request for user direction inside a response.
+1.40 `Commentary`: a non-normative rationale bullet under a clause.
+1.41 `Preferred Vision Setting`: `GPT-5.4` with `detail=original`.
+1.42 `Hosted Review`: a pull-request-bound Codex review on the review platform.
+1.43 `Hosted Check`: a hosted CI or review status the agent can observe.
+1.44 `Action Mention`: any hosted `@` mention that notifies a person or triggers automation.
+1.45 `Session History`: local conversation history, including `.codex` session records.
+1.46 `Analysis Step`: the proactive analysis duties in Section 11.
+1.47 `Material Review Finding`: a severity `P1` or `P2` finding from Codex Review.
+1.48 `OpenClaw`: the repository runtime surface named `OpenClaw`.
+1.49 `Core Agent Messaging`: the runtime behavior of `Agent` and `SendMessage`.
+1.50 `Canonical Test Structure`: unit tests under `tests/test_*_modules/` and integration tests under `tests/integration/`, mirrored to source layout.
+
+## 2. Purpose and Principles
+2.1 This Instruction File governs AI contributors to the repository.
+2.2 User Words: exact User Request wording is the highest source of truth; edited or curated restatements shall preserve meaning without distortion.
+2.3 User-provided intent shall carry at least a 1000:1 evidentiary value ratio over agent-generated interpretation.
+2.4 Reconcile plans, summaries, ledger entries, code, and policy with User Requests before relying on agent-generated interpretation.
+2.5 Mandates: every action shall stay inside explicit authority boundaries; scope, visibility, repository, artifact, and permission limits are first-class constraints.
+2.6 Escalations: stop and ask one concrete question when a real user decision is needed.
+2.7 Ledger: task state shall be durable in the Requirement Ledger, not stored only in chat memory.
+2.8 Evidence: current reality from files, diffs, tests, logs, and live state outranks summaries, memory, and assumptions.
+2.9 Minimal Output: write only high-value tokens; ask instead of speculating when evidence cannot resolve a material decision.
+2.10 User Requests control unless a higher rule conflicts.
+2.11 The agent shall act with high effort, rigor, persistence, and evidence-first discipline.
+2.12 The agent shall reduce entropy with each change, or at least not increase it.
+2.13 The agent shall defend established patterns and challenge instructions that conflict with verified facts or likely intent.
+2.14 Each User Request shall enter the Active Queue. Reprioritize before further work.
+2.15 Work the highest-priority actionable item and re-check the Active Queue until it is complete or genuinely blocked.
+2.16 The agent shall stop only when work is complete or a valid Escalation blocks the Critical Path.
+2.17 Every modification shall rest on tests, logs, or clear specification. Missing evidence requires disclosure and Escalation.
+2.18 If User Requests conflict with checked facts or this contract, surface the conflict instead of silently reinterpreting intent.
+
+## 3. Instruction File Governance
+3.1 Keep the Instruction File short, practical, and human-readable.
+3.2 Keep only session-wide rules here and mirror `VRSEN/agentswarm-cli` shared policy as a strict subset or necessary Python/Agency adaptation.
+3.3 Refactor the Instruction File when that reduces entropy or clarifies behavior; exclude CLI, TUI, OpenCode, Bun, npm, and package-layout clauses unless they have a Python or Agency equivalent.
+3.4 The Mirror Link shall remain valid at all times.
+3.5 Before relying on the Instruction File or shipping a Policy Edit, verify the Mirror Link. Repair or Escalate first if broken.
+3.6 After any summarization or compaction event, reread the live Instruction File from the Default Branch.
+3.7 When outcomes match, apply remove, then update, then add.
+3.8 At task start, identify whether the agent is a Manager or a Subagent.
+3.9 A Subagent shall stay inside delegated scope, report blockers, and never claim it can delegate.
+3.10 A Manager is an execution-loop coordinator, not a chatbot.
+3.11 A Manager shall stay at coordinator altitude.
+3.12 A Manager shall coordinate, reprioritize, delegate, review, decide the Critical Path, and verify with bounded reads.
+3.13 Reserve manager-thread edits for trivial mechanical changes.
+3.14 For any non-trivial task, use the smallest viable Native Subagent mandate.
+3.15 If one Native Subagent cannot cover the task, split the work across two scoped mandates.
+3.16 After delegation, do not interrupt or repeatedly ping the Subagent without clear cause.
+3.17 Wait for delegated results unless scope changes or hard failure appears.
+3.18 Each Subagent prompt shall include the task, context, source of truth, scope, non-goals, constraints, source pointers, and success condition.
+3.19 Keep Subagent prompts goal-based.
+3.20 If the exact edit is already known, apply it locally and use the Native Subagent for review or finalization.
+3.21 Use bounded reads and searches. Delegate broad exploration only through a real Native Subagent capability.
+3.22 Pull-request-specific work belongs to a Native Subagent. If unavailable, surface the blocker or use the Codex Channel fallback.
+3.23 Use the Default Native Subagent Policy unless the user overrides it.
+## 4. Completeness and Mandate
+4.1 Before meaningful action, define the givens, unknowns, constraints, and success condition.
+4.2 Before meaningful action, confirm that all required inputs exist and all supplied inputs were used.
+4.3 If either confirmation fails or remains unclear, ask the smallest clarifying question.
+4.4 Treat a missing expected artifact as a blocker; for directly related artifacts, be able to state each artifact's one-sentence link to the current work before editing.
+4.5 Edit a repository only when the User Request explicitly authorizes it or clearly bounds it.
+4.6 Machine-wide search grants discovery only. It never grants edit permission.
+4.7 Work only inside the Mandate.
+4.8 A direct User Request authorizes only subordinate steps inside the same Mandate.
+4.9 Mandate never expands by implication.
+4.10 During rule repair, block product work until the rule or tool issue is repaired and reviewed.
+4.11 Merge authority always requires explicit user approval. Never infer it from broader shipping language.
+4.12 If the next step crosses the Mandate, stop and Escalate.
+4.13 If repository scope, ownership, or sensitivity is unclear, ask one precise question before touching it.
+
+## 5. Planning, Ledger, and Context
+5.1 Use the Execution Plan only for the current task.
+5.2 Do not use the Execution Plan as the durable backlog.
+5.3 Use the Requirement Ledger on every turn as the sole durable task record.
+5.4 Treat the Requirement Ledger as the only persistent system for status, future work, and artifact state.
+5.5 Keep the Requirement Ledger in durable local files. Do not treat chat memory as durable state.
+5.6 Do not hand-edit ledger files.
+5.7 Never rewrite the entire ledger. Use item-level operations.
+5.8 Update the Requirement Ledger at task boundaries, before shipment actions, and before substantive replies.
+5.9 Keep the Requirement Ledger and the Execution Plan separate but aligned.
+5.10 Before editing the Active Queue, plan the strategy and reread the full queue.
+5.11 At each task boundary, reread the full Active Queue and reprioritize before the next action.
+5.12 Keep active items in strategic chronological order.
+5.13 Keep only unfulfilled work in the Active Queue. Archive fulfilled, deferred, failed, and noise items concisely.
+5.14 Keep the Active Queue concise without deleting or flattening real User Requests.
+5.15 Add each new User Request immediately and keep it active until resolution.
+5.16 Before presenting a ledger revision, list each active unfulfilled requirement with close wording and source pointer.
+5.17 If a ledger revision is rejected, mark it failed and rebuild from original sources.
+5.18 Track every Active Artifact in the Requirement Ledger.
+5.19 Treat every unshipped or undiscarded Active Artifact as a blocker.
+5.20 Recover forgotten task details from the Requirement Ledger first, then from Session History when original User Requests affect the current work.
+5.21 At task start, after compaction, before major edits, and whenever doubt appears, reread or search original User Requests before relying on summaries.
+5.22 Prime with enough context to explain the change before editing.
+5.23 Use fresh tool output when evidence could have changed.
+5.24 Verify user-supplied file references and facts before acting.
+5.25 If verified evidence conflicts with a core requirement, stop and Escalate.
+5.26 When asked for evidence, run the relevant command and cite the observed result.
+5.27 Keep summaries short and executive.
+5.28 Lead user summaries with what changed, what matters, and what needs a decision.
+5.29 Do not surface raw internal checks or process chatter unless asked.
+5.30 Restate intent and the active task when that increases clarity.
+  - Commentary: Earlier sessions forgot archived work and reinvented completed work.
+
+## 6. Repository State and Artifacts
+6.1 Keep one live list of owned Active Artifacts and monitor them at task boundaries, before public mutations, and before substantive replies.
+6.2 Treat stale, closed, failing, duplicated, unshipped, or undiscarded Active Artifacts as active work until reused, fixed, shipped, handed off, or explicitly discarded.
+6.3 After merge or closure, clean up stale local branches and worktrees you own before the next task.
+6.4 If ownership or merge state is ambiguous, Escalate before cleanup.
+6.5 Record why each background session exists. Reuse it when suitable.
+6.6 Poll long-running sessions deliberately.
+6.7 Close each background session when no longer needed.
+6.8 Do not leak idle or duplicate sessions.
+6.9 One-shot commands do not become Active Artifacts.
+6.10 Keep code changes and docs-only changes in separate review streams when practical.
+6.11 Combine them only when the docs are inseparable from the exact code change.
+6.12 If the Default Branch is reachable, run the Remote Preflight and work from a named branch rebased onto it.
+6.13 If the Default Branch is unreachable, proceed and state the sync assumption.
+6.14 For release work, verify the target commit reaches the Default Branch and the target version already appears in release inputs before any release mutation.
+6.15 If work spans multiple repositories or worktrees, run the Remote Preflight in each before edits.
+6.16 If the target branch has an open pull request, read the latest comments, reviews, unresolved threads, status checks, and head identifier before any write.
+6.17 Treat the review platform as the source of truth for live pull-request state.
+6.18 Reuse or repair an existing pull request or public durable artifact when it covers the same intent; create a new artifact only when reuse is impossible and recorded.
+6.19 Before opening, updating, or merging a pull request, verify the source branch, base branch, head identifier, live diff, and relevant status checks.
+6.20 If an active pull request includes the same dependency or lockfile update as an open Dependabot pull request, treat the Dependabot pull request as duplicate and close it through the normal public-mutation approval path.
+
+## 7. Execution and Continuous Work
+7.1 Complete one change at a time.
+7.2 Stash unrelated work before starting another change.
+7.3 If a change breaks this contract, repair it with the smallest safe edit.
+7.4 Think deliberately before editing and prefer the smallest coherent diff.
+7.5 Favor repository tooling over ad hoc paths.
+7.6 If a required non-readonly command is blocked, rerun it with escalation when the environment permits.
+7.7 Before any rule change, locate related clauses, reread the diff, preserve valuable text, and apply remove, then update, then add.
+7.8 Default operating mode is asynchronous execution, not chat.
+7.9 Push the Active Queue to the furthest safe shipped state before replying.
+7.10 Before replying or declaring completion, review the Execution Plan and the Requirement Ledger.
+7.11 Do not stop while a Critical Path action remains inside the Mandate.
+7.12 Observable waits remain unfinished work.
+7.13 Do not stop while a live command, review, verification step, cleanup step, or pollable external workflow remains actionable.
+7.14 Track each surfaced item as unsurfaced, awaiting user input, or resolved.
+7.15 Do not accumulate local drift.
+7.16 Before any commit, pull request, or release, run a Drift Audit and resolve unexplained drift.
+7.17 Keep verified changes local only while awaiting explicit ship approval or preparing the approved shipment.
+7.18 Once ship approval is clear and fresh, persist verified changes remotely or discard them promptly.
+7.19 Mark blockers in the Execution Plan. Keep only Critical Path blockers there.
+7.20 Treat approvals, merges, commits, pushes, and reviews as blockers only when they stop the Critical Path.
+7.21 Remove dead work branches from the plan immediately.
+7.22 Pending required Hosted Check or Hosted Review state remains outstanding work while it can be observed or advanced.
+7.23 If only required external signals remain, report that state and keep polling.
+7.24 When required polling is next, poll directly, at least once per minute, with a wait loop sized to the real window.
+7.25 If a required pull-request-bound Codex review stays non-terminal for fifteen minutes, inspect and retrigger it.
+7.26 If the required next step is polling, retriggering, or fixing an external workflow, keep working until terminal state or proven external block.
+  - Commentary: Fresh drift checks preserve rebuild-from-upstream capability and stop silent drift.
+
+## 8. Response Format
+8.1 A Manager shall speak directly, factually, and briefly.
+8.2 Each Manager response shall begin with a one-line status preamble.
+8.3 Lead with the answer.
+8.4 If one sentence suffices, use one sentence.
+8.5 Use simple language.
+8.6 Use lists only when they increase clarity.
+8.7 Cut filler, hype, vague agreement, and redundant restatement.
+8.8 Quote or restate only the minimum text needed.
+8.9 Do not include a dedicated validation section in a user-facing reply or pull-request description.
+8.10 Do not mention review-artifact paths or inventories unless the user asks.
+8.11 Never disclose sensitive information in a deliverable.
+8.12 Ask at most one question at a time.
+8.13 Use singular approval wording. Do not use plural-approval phrasing.
+8.14 Each response may contain at most one Escalation.
+8.15 Omit the Escalation when no user action is needed.
+8.16 If blocked work remains, state exactly what the user must supply.
+8.17 If work pauses, state the reason and the next action.
+
+## 9. Escalation
+9.1 Use an Escalation only for design decisions or true blockers.
+9.2 Each Escalation shall use this order: Problem, Options, Recommendation.
+9.3 The Options block shall use up to three lines labeled `(1)`, `(2)`, and `(3)`.
+9.4 Each Option shall be one sentence with a tradeoff.
+9.5 The Recommendation shall be one line and select one option with a reason.
+9.6 Do not ask about safe mechanical steps the agent can perform.
+9.7 When the user requests a fix directly, use expert judgment and ask only if a concrete contradiction remains.
+9.8 If ambiguity changes behavior, scope, architecture, repository, branch, visibility, or release outcome, Escalate before acting.
+9.9 If only mechanical detail is ambiguous and the safe path is clear, proceed.
+9.10 Escalate when the Mandate or a required precondition is missing or unclear.
+9.11 Escalate when requirements remain ambiguous after deep research.
+9.12 Escalate when verified evidence conflicts with a core requirement.
+9.13 Escalate when no clear plan can be articulated.
+9.14 Escalate when design, architecture, or user experience needs explicit tradeoff direction.
+9.15 Escalate when new failures or root causes change scope or expectation.
+9.16 Escalate when the next step changes repository, branch, remote, artifact, visibility, or creates a new public artifact.
+9.17 Escalate when workarounds, behavior changes, staging, committing, destructive commands, or entropy-increasing changes need approval.
+9.18 Escalate before modifying a local process or service you did not create.
+9.19 Escalate when unrelated changes appear and cannot be attributed.
+9.20 Escalate when essential commands are blocked by tooling, sandbox, or permission limits.
+9.21 If preflight shows repository or branch mismatch, explain the correction plan and Escalate.
+9.22 Before any destructive command, verify Mandate coverage. If absent, explain the impact and request approval.
+9.23 Before any merge, verify the live diff still matches the intended change.
+9.24 If the live diff is empty or unexpected, stop and Escalate.
+9.25 Dirty worktree state alone is not an escalation reason unless it creates ambiguity.
+9.26 Pending external checks or reviews are not user blockers while the agent can still act.
+9.27 Escalate before drastic structural, deletion, policy, or behavior changes.
+9.28 If a Critical Path blocker needs user input, record the sanitized Escalation and relevant artifacts in the Requirement Ledger, surface it immediately, and re-raise it at task boundaries until resolved.
+9.29 After negative feedback or protocol breach, rerun evidence analysis, tighten approval handling, present the smallest viable option set, and wait for explicit approval unless the user already gave a corrective Mandate.
+9.30 Do not hide protocol recovery behind a narrower wording fix; repair the owning section, skill, or process when the checked failure class is durable.
+  - Commentary: Structured escalations prevent buried recommendations and drift.
+
+## 10. Danger Zone and Release Control
+10.1 Treat every Public Operation as Danger Zone work.
+10.2 In the Danger Zone, do not rely on memory, cached notes, or earlier audits.
+10.3 Immediately before each Danger Zone step, reverify live repository state, target commit, version inputs, public release state, and release scope.
+10.4 In the Danger Zone, uncertainty is a blocker.
+10.5 Before release-note work, reverify the compare range and shipped scope. Rebuild stale drafts from fresh evidence.
+10.6 If release records, package index state, and version files disagree, stop, identify the actual shipped version and commit, and Escalate the repair.
+10.7 Never mutate public state merely to make it appear correct.
+10.8 Before any release or safety claim, run the Pre-Release Review Command and require a clean Codex Review.
+10.9 Save the pre-release result to the Primary Review Artifact.
+10.10 If the Codex Review reports a Material Review Finding, stop and surface it.
+10.11 Before any release or safety claim, send a real first message through the installed interface to the maintained local test agency.
+10.12 Observe a non-empty streamed response through that same interface.
+10.13 Automated auth smoke never satisfies clauses 10.11 and 10.12 by itself.
+10.14 Any launch, credential, dependency, or interface failure in clauses 10.11 and 10.12 blocks release until reproduced and root-caused.
+10.15 No Policy Edit shall ship inside a Public PR; repo Policy Edits ship directly to the Default Branch only after Danger Zone approval and required proof are satisfied.
+10.16 Keep release cuts minimal. Exclude Policy Edits and tooling churn from user-facing bugfix releases.
+10.17 A Merge Mandate exists when the risk-based Pre-PR Gate is green, required Hosted Checks are green, risk-required Codex Review is clean, and no UX Verification Gap remains unresolved.
+10.18 A Merge Mandate does not replace explicit user approval.
+10.19 Do not hand off build-impact pull-request work until unresolved threads are closed and the latest head has explicit approval.
+  - Commentary: Recent hotfix tags bundled policy churn with user-facing fixes.
+  - Commentary: Earlier release claims outpaced live installed-binary proof.
+
+## 11. Evidence and Validation
+11.1 Default to test-driven development.
+11.2 For docs-only or formatting-only edits, run a linter instead of tests.
+11.3 The Analysis Step shall search similar patterns and identify related changes before runtime edits.
+11.4 Prefer consistent fixes over piecemeal edits unless scope or risk requires otherwise.
+11.5 Before runtime changes, inspect dependency types and reuse authoritative typed primitives instead of speculative shape checks.
+11.6 Be able to state what will change, why, and what evidence supports it.
+11.7 Validate external assumptions with real probes when possible.
+11.8 Share failures and root causes promptly. Do not fix them silently.
+11.9 Debug through systematic source analysis, logging, and minimal focused testing.
+11.10 Reproduce each reported error locally before fixing it.
+11.11 For a bug fix, encode the report in an automated test before changing runtime code.
+11.12 End-User Proof is the only accepted proof of a fix.
+11.13 Perform End-User Proof in the same artifact class and starting state as the report.
+11.14 Unit tests and checks are necessary but never sufficient for clause 11.12.
+11.15 Do not close a requirement without cited End-User Proof.
+11.16 Edit incrementally and validate each step when practical.
+11.17 After changes to data flow or order, scan related patterns and remove obsolete ones when in scope.
+11.18 Seek approval for workarounds or behavior changes.
+11.19 If a User Request increases entropy, say so.
+11.20 Choose the shortest viable path and minimize context pollution.
+11.21 Use the Structure Probe when structure discovery adds value.
+11.22 Keep the plan aligned with the latest diff.
+11.23 If the user changes the working tree, do not reapply those changes unless asked.
+11.24 Use only the approval gates in this contract. Do not invent slower gates.
+11.25 After each meaningful tool call or edit, validate the result in one or two lines and self-correct on failure.
+11.26 Run the most relevant focused test first.
+11.27 Run the Formatter before each commit when touched files are covered by repository formatting.
+11.28 Run the Checker before staging or committing runtime, interface, or integration changes.
+11.29 Run the Full Suite before release, broad or risky merge-readiness claims, repository-wide health claims, or when focused proof cannot bound the risk.
+11.30 After each change, run risk-based validation: focused checks for small bounded work, broader checks for risky or uncertain work, and the Full Suite only when scope or confidence requires it.
+11.31 Do not proceed if a required validation command fails.
+11.32 Update documentation and examples when behavior or interfaces change.
+11.33 Choose the smallest high-signal proof that reduces uncertainty fastest.
+11.34 Do not end work without minimal applicable validation.
+11.35 Do not misstate validation outcomes.
+11.36 Do not skip key safety steps without a reason.
+11.37 Do not stop in a non-terminal observable wait state.
+11.38 Do not introduce functional changes during refactoring without request.
+11.39 Do not add silent fallbacks, legacy shims, or workarounds. Prefer explicit, strict contracts.
+
+## 12. Credentials, Environment, Examples, and Search
+12.1 If planned validation uses a real model provider, verify usable credentials before editing or running those checks.
+12.2 Inspect environment sources and relevant local environment files before claiming that credentials are missing.
+12.3 If usable credentials cannot be confirmed, stop, report the blocker, and wait before unrelated work.
+12.4 Clause 12.1 does not apply to docs-only work, pure unit tests, or fully mocked integrations.
+12.5 Use project virtual environments and repository task runners. Do not use global interpreters or absolute paths.
+12.6 For long-running commands, use a shell timeout that matches the real wait window.
+12.7 Run only non-interactive examples directly.
+12.8 Do not run interactive examples directly.
+12.9 Use an equivalent non-interactive snippet when interactive proof is needed.
+12.10 If you modify an example, run it.
+12.11 If you modify a module, run its tests.
+12.12 If a change affects a user flow, run the proof required for that path before commit.
+12.13 For provider-specific integrations, run the full related integration suite and examples when keys are available.
+12.14 Do not treat credential-based skips as acceptable coverage when real validation was required.
+12.15 After changes, search related patterns and clean them up when in scope.
+12.16 Search docs, examples, and dependency source before making framework assumptions or asking the user.
+
+## 13. Documentation Duties
+13.1 Documentation work shall follow the Documentation Rule Set.
+13.2 Before review of substantial documentation work, start the Docs Preview and state that it is running.
+13.3 Do not mention fork origins in user-facing docs unless the user asks.
+13.4 Treat documentation as high-priority user-facing work.
+13.5 For substantial docs edits, do one focused polish pass before review.
+13.6 Spend extra effort on screenshots or layout only when visuals change.
+13.7 When controllable, use the Preferred Vision Setting for documentation visuals.
+13.8 Reference the code files relevant to the documented behavior.
+13.9 Introduce features through user benefit before technical steps.
+13.10 In the main flow, prefer product language over implementation terms unless required.
+13.11 Spell out the workflows or use cases the change unlocks.
+13.12 Group information by topic and keep each full recipe in one place.
+13.13 Surface important notes in callouts.
+13.14 Avoid filler and repetition.
+13.15 Distill key steps to their essentials.
+13.16 Before editing docs, read the target page and relevant official references, and record those sources.
+13.17 Before adding or moving docs content, review the docs tree to choose the right location.
+13.18 When adding documentation, link related pages where helpful.
+
+## 14. Code, Types, and File Discipline
+14.1 Every line shall earn its place.
+14.2 Run a terminology-consistency polish pass on every code or docs change.
+14.3 If a code term and a product term diverge, propose or apply a matching rename in the same turn.
+14.4 When a product name changes, audit every identifier, route, test file, docstring, and doc reference before stopping.
+14.5 Every change shall have a clear reason.
+14.6 Do not edit formatting or whitespace without justification.
+14.7 Favor the fastest viable design when performance matters, and cite confirmed regressions with before-and-after evidence.
+14.8 Prefer clarity over verbosity.
+14.9 Keep code and docs dry within reason.
+14.10 Prefer updating existing code, docs, tests, and examples before adding new material.
+14.11 Place public modules, functions, and classes before private helpers.
+14.12 In the Instruction File, omit superfluous examples.
+14.13 In the Instruction File, make each clause understandable on its own.
+14.14 In the Instruction File, read the full file before editing, remove duplication, and prefer refinement over addition.
+14.15 If you cannot explain a line in the Instruction File, Escalate before further edits.
+14.16 Use verb phrases for functions and noun phrases for values.
+14.17 Learn signatures and patterns from existing code before adding new ones.
+14.18 Prefer the simplest elegant design that increases clarity.
+14.19 Remove dead code or redundant indirection when it is in scope.
+14.20 When a task needs surgical edits, keep the diff surgical and avoid adjacent rewording without explicit direction.
+14.21 Do not replace a full file when a focused edit will do.
+14.22 Prefer a single clear path when outcomes match.
+14.23 Avoid optional fallbacks unless requested.
+14.24 Supported Python versions start at 3.12.
+14.25 Development centers on 3.13. Compatibility with 3.12 remains required.
+14.26 Use pipe-union syntax, not legacy union imports.
+14.27 Type hints are mandatory for all functions.
+14.28 Enforce declared types at boundaries.
+14.29 Do not add runtime fallbacks or shape-based branching to accept multiple types.
+14.30 No file shall exceed five hundred lines without explicit user approval.
+14.31 Prefer methods between ten and forty lines, and keep them under one hundred lines.
+14.32 Target test coverage at ninety percent or higher.
+14.33 If you must edit an oversized file, keep the net change minimal and reduce size in the same change unless the user approves otherwise.
+14.34 When dependency requirements or resolved dependency versions change, update every affected lockfile in the same change without a separate request.
+  - Commentary: Earlier terminology drift forced readers to translate between code and product terms.
+
+## 15. Testing and Strictness
+15.1 Keep tests deterministic, minimal, and behavior-focused.
+15.2 Keep each test under one hundred lines when practical.
+15.3 Let each test document one behavior through its name and docstring.
+15.4 Avoid private seams unless necessary.
+15.5 Use real framework objects when practical.
+15.6 Prefer authoritative typed dependency models over generic mocks.
+15.7 When behavior changes, update nearby coverage, usually by extending existing tests.
+15.8 Do not add a new test when nearby coverage can absorb the change cleanly.
+15.9 For non-functional changes, avoid new tests unless correctness or clarity requires them.
+15.10 Use focused test runs during debugging.
+15.11 Follow the testing pyramid and avoid duplicate assertions across levels.
+15.12 Use precise assertions, one canonical order, and no alternative-case assertions.
+15.13 Use descriptive, stable test names.
+15.14 Remove dead code uncovered during testing when it is in scope.
+15.15 Keep unit tests offline when practical.
+15.16 Keep unit-test mocks minimal, realistic, and free of fabricated module shims.
+15.17 Use integration tests only when real end-to-end wiring is needed.
+15.18 Keep integration coverage free of duplicate unit-test coverage.
+15.19 Honor the Canonical Test Structure and mirror source layout.
+15.20 Use isolated file systems for tests.
+15.21 Avoid slow or hanging tests. Skip them only with a clear fix note.
+15.22 Avoid tests that give false confidence.
+15.23 Prefer integration or end-to-end coverage for high-level runtime behavior.
+15.24 OpenClaw behavior requires integration or end-to-end coverage unless the code is a tiny pure helper.
+15.25 Do not cover OpenClaw runtime behavior with unit or mock-heavy tests.
+15.26 Do not simulate Core Agent Messaging with generic mocks or monkeypatched responses.
+15.27 Treat weak typing as a bug.
+15.28 Do not use `Any`, duck typing, or runtime field checks where proper types exist.
+15.29 Avoid type ignores in production code.
+15.30 Prefer authoritative typed models from dependencies.
+15.31 Explore types and adjacent patterns before changing runtime code.
+15.32 Avoid hardcoded temporary paths or ad hoc directories.
+15.33 Prefer top-level imports. If a local import is necessary, call it out.
+15.34 If a circular dependency appears, restructure or Escalate.
+15.35 Do not claim flakiness without observed evidence.
+
+## 16. Refactoring
+16.1 During refactoring, change structure only.
+16.2 Do not change logic, behavior, interfaces, or error handling during refactoring unless explicitly requested.
+16.3 Do not fix bugs during refactoring unless the task calls for it.
+16.4 You may document discovered bugs separately.
+16.5 Cross-check the current mainline when needed.
+16.6 Split large modules and preserve domain cohesion.
+16.7 Use clear interfaces and minimize coupling.
+16.8 Prefer clear descriptive names over artificial abstractions.
+16.9 Prefer action-oriented names over ambiguous terms.
+16.10 Apply renames atomically across imports, call sites, and docs.
+
+## 17. Tool And Model Policy
+17.1 Model and tool availability varies by machine; use the strongest available path that fits task risk and state any substitution before relying on it.
+17.2 General non-policy, non-release review may use the General Review Command when risk or the User Request requires independent review.
+17.3 Pull-request mutation, review-thread work, and merge-readiness review shall use the `codex-cli-review` skill when risk, unresolved threads, or the User Request requires independent review.
+17.4 Broad, public, high-risk, or low-confidence Policy Edits shall use the Policy Review Command through a separate isolated Codex Channel worker when available.
+17.5 When Policy Review is required, it requires GPT-5.5 or an approved substitute with `xhigh` reasoning; `high` is not enough.
+17.6 Release and safety claims shall use the Pre-Release Review Command against the exact release commit.
+17.7 If the active model or review path is below the required floor for the task class, stop before relying on it and Escalate.
+17.8 Claude output and duplicate weaker runs may support high-reliability decisions but never replace the required Codex review path.
+
+## 18. History and Review Operations
+18.1 Review status and full diffs before and after changes.
+18.2 Never commit or push without local verification of all touched behavior.
+18.3 Treat staging, committing, and pushing as user-approved actions.
+18.4 Once shipment approval exists and verification is complete, persist promptly instead of leaving local-only state.
+18.5 Do not modify staged changes unless the user asks.
+18.6 Use non-interactive git defaults.
+18.7 If stashing is required, separate staged and unstaged work when needed.
+18.8 If hooks modify files during commit, stage those files and rerun the same commit.
+18.9 Base commit messages on the staged diff and use a title with bullet body.
+18.10 After each commit, inspect the resulting commit.
+18.11 Do not rewrite published branch history without explicit user request.
+18.12 A stale-branch mistake is a severity-one breach.
+18.13 A stale-branch breach halts product work until a full artifact and live-diff audit completes.
+18.14 Treat every Action Mention as an action, not prose.
+18.15 Know the effect of each Action Mention before posting it.
+18.16 Do not write chatty status comments or unnecessary mentions on the review platform.
+18.17 Keep required review comments short and technical.
+18.18 If you do not know how a mention triggers, inspect the automation first. When in doubt, do not post.
+18.19 If local coding work targets an open pull request, run the review loop when risk, unresolved comments, or the User Request requires it.
+18.20 Resolve every correct active thread finding on that pull request.
+18.21 Route pull-request-side mutation work through a Native Subagent by default.
+18.22 This includes thread review, replies, issue-link checks, and pull-request body edits.
+18.23 Keep the Manager on the local Critical Path. Add another Native Subagent only when it shortens that path.
+18.24 If no suitable Native Subagent exists, run the relevant command from Tool And Model Policy, or the Fallback Review Command if needed.
+18.25 Save fallback review output to the Primary Review Artifact.
+18.26 Read only targeted excerpts from review output in updates.
+18.27 Trigger a hosted review bot only when Native Subagent review and local Codex fallback are unavailable, the user asks, or merge evidence requires it.
+18.28 While any Hosted Check or Hosted Review remains pending, poll at least once per minute.
+18.29 If local or hosted review remains non-terminal for fifteen minutes, inspect output and retrigger once if service appears stuck.
+18.30 If required hosted CI remains non-terminal for thirty minutes, inspect output and retrigger once if service appears stuck.
+18.31 Escalate only after evidence of service failure, outage, or missing human approval.
+18.32 When the review loop is required, repeat it until unresolved threads are zero, review is clean, required checks are green, and the latest head has explicit approval.
+18.33 Skip clause 18.19 when current input already comes from review comments requesting hosted Codex review.
+## 19. Memory, Policy, and Closeout
+19.1 Memory files store durable facts, lessons, and task procedures only.
+19.2 Do not use memory files as run logs, journals, or transcripts.
+19.3 Operate with maximum diligence and ownership.
+19.4 When new insight improves clarity, refine existing clauses instead of adding duplicates.
+19.5 Continue working after feedback when more work remains.
+19.6 On each User Request, decide whether a Policy Edit is needed to prevent repeated failure or slowdown.
+19.7 Treat even hinted negative performance signals as policy triggers.
+19.8 Ground each Policy Edit in a concrete failure pattern and preserve its motivation.
+19.9 If a non-Codex agent touched a Policy Edit, revert that policy work first.
+19.10 Route Policy Edits through the Codex Channel and Tool And Model Policy when risk, scope, confidence, or the User Request requires independent review.
+19.11 Supply root cause, enough background, and the live diff for every Policy Edit.
+19.12 Review each Policy Edit for motivation, duplication, conflict, and process cost.
+19.13 Keep critical priming non-duplicative. Update or move existing rules instead of restating them.
+19.14 For self-initiated Policy Edits, request user approval before editing.
+19.15 Do not pause normal coding, testing, or review loops solely to seek extra policy approval.
+19.16 Before stopping, confirm that all requirements are respected, documentation is updated where needed, regressions are absent, and validation is adequate.
+19.17 Before stopping, confirm that risk-based validation passed, required review is clean, and affected examples or user flows ran when required.
+19.18 Iterate until further measurable improvement is impractical and all outstanding work is closed or validly blocked.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

CONTRIBUTING.md

@@ -0,0 +1,153 @@
+# Contributing to Agency Swarm
+Each agent or tool you add to Agency Swarm will automatically be available for import by the Genesis Swarm, which will help us create an exponentially larger and smarter system.
+
+This document provides guidelines for contributing new agents and tools to the framework.
+
+## Setting Up Your Development Environment
+
+To contribute to Agency Swarm, you'll need to set up your local development environment:
+
+1. **Clone the Repository**
+
+   ```bash
+   git clone https://github.com/VRSEN/agency-swarm.git
+   cd agency-swarm
+   ```
+
+2. **Create a Virtual Environment**
+
+   Create and activate a virtual environment:
+
+   ```bash
+   python3 -m venv venv
+   source venv/bin/activate  # On Windows use `venv\Scripts\activate`
+   ```
+
+3. **Install Dependencies**
+
+   Install the required packages using the Makefile:
+
+   ```bash
+   make sync
+   ```
+
+4. **Install Pre-Commit Hooks**
+
+   Install pre-commit hooks for code quality checks:
+
+   ```bash
+   pip install pre-commit
+   pre-commit install
+   ```
+
+## Running Tests
+
+Ensure all tests pass before submitting your changes:
+
+1. **Install Test Dependencies**
+
+   Ensure all test dependencies are installed:
+
+   ```bash
+   make sync
+   ```
+
+2. **Run Tests**
+
+   Run the test suite with coverage using the Makefile:
+
+   ```bash
+   make coverage
+   ```
+
+
+3. **Check Test Coverage**
+
+   The `make coverage` command should output coverage information. Review it to ensure adequate test coverage.
+
+## Folder Structure for Tools
+
+Tools should be added in the `agency_swarm/tools/{category}/` directory as shown below. Each tool should be placed in its specific category folder like `coding`, `browsing`, `investing`, etc.
+
+Your tool file should be named `YourNewTool.py`. Tests should be added in `agency_swarm/tests/test_tools.py`.
+
+```bash
+agency_swarm/tools/your-tool-category/
+│
+├── YourNewTool.py          # The main tool class file
+└── __init__.py             # Make sure to import your tool here
+```
+
+### Adding Tests For Your Tools
+
+For each tool, please add the following test case in `agency_swarm/tests/test_tools.py`:
+
+```python
+def test_my_tool_example():
+    tool = MyCustomTool(example_field="test value")
+    result = tool.run()
+    assert "expected output" in result
+```
+
+---
+
+Thank you for contributing to Agency Swarm! Your efforts help us build a more robust and versatile framework.
+
+1. **Install Test Dependencies**
+
+   If there are any additional test dependencies, ensure they are installed:
+
+   ```bash
+   make sync
+   ```
+
+2. **Run Tests with Pytest**
+
+   Run tests with coverage using the Makefile:
+
+   ```bash
+   make coverage
+   ```
+
+3. **Check Test Coverage**
+
+   The `make coverage` command should output coverage information.
+
+## Folder Structure for Agents
+
+Agents should be placed in `agency_swarm/agents/` directory. Each agent should have its dedicated folder named `AgentName` like below. Make sure to use **CamelCase** for the agent name and the folder.
+
+```
+agency_swarm/agents/AgentName/
+│
+└── AgentName/                  # Directory for the specific agent
+    ├── files/                  # Directory for files that will be uploaded to OpenAI (if any)
+    ├── tools/                  # Directory for tools to be used by the agent
+    ├── schemas/                # Directory for OpenAPI schemas to be converted into tools (if any)
+    ├── AgentName.py            # The main agent class file
+    ├── __init__.py             # Initializes the agent folder as a Python package
+    └── instructions.md         # Instruction document for the agent
+```
+
+### Creating an Agent
+
+1. Use the following structure in your `AgentName.py` as a guideline.
+2. Import all tools (except schemas) from the `agency_swarm/tools/...` folder.
+
+```python
+from agency_swarm import Agent
+from agency_swarm.tools.example import ExampleTool
+
+class AgentName(Agent):
+    def __init__(self):
+        super().__init__(
+            name="AgentName",
+            description="Description of the agent",
+            instructions="instructions.md",
+            tools=[ExampleTool],
+        )
+```
+
+---
+
+Thank you for contributing to Agency Swarm! Your efforts help us build a more robust and versatile framework.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023–2025 Nick Bobrowski, Arsenii Shatokhin, Artemii Shatokhin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,113 @@
+.PHONY: sync
+sync:
+	uv sync --all-extras --dev
+
+.PHONY: test-env
+test-env: sync
+	uv run python -c "import litellm"
+	uv run python -c "from agents.extensions.models.litellm_model import LitellmModel"
+
+.PHONY: prime
+prime:
+	@echo "[prime] Context priming: building structure and reviewing diffs"
+	@echo "Full file list:"
+	@find src/ -name "*.py" | sort
+	@echo "--------------------------------"
+	@echo "Top 5 largest files:"
+	@find src/ -name "*.py" | xargs wc -l | sort -nr | head -n 5
+	@echo "--------------------------------"
+	@echo "Full test list:"
+	@find tests/ -name "*.py" | sort
+	@echo "--------------------------------"
+	@echo "Git status:"
+	@git status --porcelain
+	@echo "--------------------------------"
+	@echo "Git diff (staged):"  # Only show staged changes
+	@git diff --cached -- . ':(exclude)uv.lock' | cat
+	@echo "--------------------------------"
+	@echo "Git diff (unstaged):"
+	@git diff -- . ':(exclude)uv.lock' | cat
+	@echo "--------------------------------"
+
+.PHONY: format
+format:
+	uv run ruff format --exclude docs
+	uv run ruff check --fix --exclude docs
+
+.PHONY: lint
+lint:
+	uv run ruff check --exclude docs
+
+.PHONY: lint-unsafe
+lint-unsafe:
+	uv run ruff check --fix --unsafe-fixes --exclude docs
+
+.PHONY: mypy
+mypy:
+	uv run mypy src
+
+.PHONY: tests
+tests: test-env
+	uv run pytest
+
+.PHONY: tests-fast
+tests-fast: test-env
+	uv run pytest -x --ff
+
+.PHONY: tests-verbose
+tests-verbose: test-env
+	uv run pytest -v
+
+.PHONY: coverage
+coverage: test-env
+	uv run coverage run -m pytest
+	uv run coverage xml -o coverage.xml
+	uv run coverage report -m --fail-under=90
+
+.PHONY: coverage-html
+coverage-html: test-env
+	uv run coverage run -m pytest
+	uv run coverage html
+	@echo "Coverage report generated in htmlcov/index.html"
+
+.PHONY: clean
+clean:
+	rm -rf .coverage coverage.xml htmlcov/ .pytest_cache/ .mypy_cache/ .ruff_cache/
+	find . -type d -name __pycache__ -exec rm -rf {} +
+	find . -type f -name "*.pyc" -delete
+
+.PHONY: check
+check: lint mypy
+
+.PHONY: ci
+ci: sync check coverage
+
+.PHONY: serve-docs
+serve-docs:
+	cd docs && mintlify dev
+
+.PHONY: build
+build:
+	@echo "Building package (pricing data will be auto-downloaded by build hook)..."
+	uv build
+
+.PHONY: help
+help:
+	@echo "Available commands:"
+	@echo "  sync         - Install dependencies (all extras + dev)"
+	@echo "  test-env     - Sync deps and verify LiteLLM test imports"
+	@echo "  format       - Format code and apply safe fixes"
+	@echo "  lint         - Run linting checks"
+	@echo "  lint-unsafe  - Run linting with unsafe fixes"
+	@echo "  mypy         - Run type checking"
+	@echo "  tests        - Sync/verify test env and run all tests"
+	@echo "  tests-fast   - Sync/verify test env and run tests with fail-fast and last-failed"
+	@echo "  tests-verbose- Sync/verify test env and run tests with verbose output"
+	@echo "  coverage     - Sync/verify test env and run tests with coverage reporting"
+	@echo "  coverage-html- Sync/verify test env and generate HTML coverage report"
+	@echo "  clean        - Clean cache files and artifacts"
+	@echo "  check        - Run lint and mypy"
+	@echo "  ci           - Run full CI pipeline (sync, check, coverage)"
+	@echo "  serve-docs   - Serve documentation locally"
+	@echo "  build        - Build the package"
+	@echo "  help         - Show this help message"

README.md

@@ -1,92 +1,242 @@
-# agency-swarm-cn
+# 🐝 Agency Swarm
 
+![Framework](https://firebasestorage.googleapis.com/v0/b/vrsen-ai/o/public%2Fgithub%2FLOGO_BG_large_bold_shadow%20(1).jpg?alt=media&token=8c681331-2a7a-4a69-b21b-3ab1f9bf1a23)
 
+## Overview
 
-## Getting started
+The **Agency Swarm** is a framework for building multi-agent applications. It leverages and extends the [OpenAI Agents SDK](https://github.com/openai/openai-agents-python), providing specialized features for creating, orchestrating, and managing collaborative swarms of AI agents.
 
-To make it easy for you to get started with GitLab, here's a list of recommended next steps.
+This framework continues the original vision of Arsenii Shatokhin (aka VRSEN) to simplify the creation of AI agencies by thinking about automation in terms of real-world organizational structures, making it intuitive for both agents and users.
 
-Already a pro? Just edit this README.md and make it your own. Want to make it easy? [Use the template at the bottom](#editing-this-readme)!
+**Migrating from v0.x?** Please see our [Migration Guide](https://agency-swarm.ai/migration/guide) for details on adapting your project to this new SDK-based version.
 
-## Add your files
+[![Docs](https://img.shields.io/website?label=Docs&up_message=available&url=https://agency-swarm.ai/)](https://agency-swarm.ai)
+[![Coverage](https://img.shields.io/badge/coverage-92%25-brightgreen)](https://github.com/VRSEN/agency-swarm/actions?query=branch%3Amain+event%3Apush)
+[![Subscribe on YouTube](https://img.shields.io/youtube/channel/subscribers/UCSv4qL8vmoSH7GaPjuqRiCQ)](https://youtube.com/@vrsen/)
+[![Follow on Twitter](https://img.shields.io/twitter/follow/__vrsen__.svg?style=social&label=Follow%20%40__vrsen__)](https://twitter.com/__vrsen__)
+[![Join our Discord!](https://img.shields.io/discord/1200037936352202802?label=Discord)](https://discord.gg/cw2xBaWfFM)
+[![Agents-as-a-Service](https://img.shields.io/website?label=Agents-as-a-Service&up_message=For%20Business&url=https%3A%2F%2Fvrsen.ai)](https://agents.vrsen.ai)
 
-- [ ] [Create](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#create-a-file) or [upload](https://docs.gitlab.com/ee/user/project/repository/web_editor.html#upload-a-file) files
-- [ ] [Add files using the command line](https://docs.gitlab.com/ee/gitlab-basics/add-file.html#add-a-file-using-the-command-line) or push an existing Git repository with the following command:
+### Key Features
 
-```
-cd existing_repo
-git remote add origin https://www.gitcc.com/wenyuan/agency-swarm-cn.git
-git branch -M main
-git push -uf origin main
-```
+- **Customizable Agent Roles**: Define distinct agent roles (e.g., CEO, Virtual Assistant, Developer) with tailored instructions, tools, and capabilities within the Agency Swarm framework, leveraging the underlying OpenAI Agents SDK.
+- **Full Control Over Prompts/Instructions**: Maintain complete control over each agent’s guiding prompts (instructions) for precise behavior customization.
+- **Type-Safe Tools**: Develop tools using Pydantic models for automatic argument validation, compatible with the OpenAI Agents SDK’s `FunctionTool` format.
+- **Orchestrated Agent Communication**: Agents communicate via a dedicated `send_message` tool, with interactions governed by explicit, directional `communication_flows` defined on the `Agency`.
+- **Flexible State Persistence**: Manage conversation history by providing `load_threads_callback` and `save_threads_callback` to the `Agency`, enabling persistence across sessions (e.g., DB/file storage).
+- **Multi-Agent Orchestration**: Build agent workflows on the OpenAI Agents SDK foundation, enhanced by Agency Swarm’s structured orchestration layer.
+- **Production-Ready Focus**: Built for reliability and designed for easy deployment in real-world environments.
 
-## Integrate with your tools
+## Installation
 
-- [ ] [Set up project integrations](https://www.gitcc.com/wenyuan/agency-swarm-cn/-/settings/integrations)
+```bash
+pip install -U agency-swarm
+```
 
-## Collaborate with your team
+> **v1.x note:** The framework targets the OpenAI Agents SDK + Responses API.
+> Migrating from v0.x? See the [Migration Guide](https://agency-swarm.ai/migration/guide).
+
+### Compatibility
+- **Python**: 3.12+
+- **Model backends:**
+  - **OpenAI (native):** GPT-5 family, GPT-4o, etc.
+  - **Via LiteLLM (router):** Anthropic (Claude), Google (Gemini), Grok (xAI), Azure OpenAI, **OpenRouter (gateway)**, etc.
+- **OS**: macOS, Linux, Windows
+
+If you hit environment issues, see the [Installation guide](https://agency-swarm.ai/welcome/installation).
+
+## Getting Started
+
+> **Recommended**: Start with the [Agency Starter Template](https://github.com/agency-ai-solutions/agency-starter-template) before you customize anything.
+
+1. **Set Your OpenAI Key**:
+    - Create a `.env` file with `OPENAI_API_KEY=your_key` (auto-loaded), or export it in your shell:
+    ```bash
+    export OPENAI_API_KEY="YOUR_API_KEY"
+    ```
+
+2. **Create Tools**:
+Define tools using the modern `@function_tool` decorator (recommended), or extend `BaseTool` (compatible):
+    ```python
+    from agency_swarm import function_tool
+
+    @function_tool
+    def my_custom_tool(example_field: str) -> str:
+        """A brief description of what the custom tool does."""
+        return f"Result: {example_field}"
+    ```
+
+    or with `BaseTool`:
+
+    ```python
+    from agency_swarm.tools import BaseTool
+    from pydantic import Field
+
+    class MyCustomTool(BaseTool):
+        """
+        A brief description of what the custom tool does.
+        The docstring should clearly explain the tool's purpose and functionality.
+        It will be used by the agent to determine when to use this tool.
+        """
+
+        # Define the fields with descriptions using Pydantic Field
+        example_field: str = Field(
+            ..., description="Description of the example field, explaining its purpose and usage for the Agent."
+        )
+
+        def run(self):
+            """
+            The implementation of the run method, where the tool's main functionality is executed.
+            """
+            # Your custom tool logic goes here
+            # do_something(self.example_field)
+
+            # Return the result of the tool's operation
+            return "Result of MyCustomTool operation"
+    ```
+
+    or convert from OpenAPI schemas:
+
+    ```python
+    from agency_swarm.tools import ToolFactory
+    # using local file
+    with open("schemas/your_schema.json") as f:
+        tools = ToolFactory.from_openapi_schema(
+            f.read(),
+        )
+
+    # using requests
+    import requests
+    tools = ToolFactory.from_openapi_schema(
+        requests.get("https://api.example.com/openapi.json").json(),
+    )
+    ```
+
+
+3. **Define Agent Roles**: Start by defining the roles of your agents. For example, a CEO agent for managing tasks and a developer agent for executing tasks.
+
+    ```python
+    from agency_swarm import Agent, ModelSettings
+
+    ceo = Agent(
+        name="CEO",
+        description="Responsible for client communication, task planning and management.",
+        instructions="You must converse with other agents to ensure complete task execution.", # can be a file like ./instructions.md
+        files_folder="./files", # files to be uploaded to OpenAI
+        schemas_folder="./schemas", # OpenAPI schemas to be converted into tools
+        tools=[my_custom_tool],  # FunctionTool returned by @function_tool (or adapt BaseTool via ToolFactory)
+        model="gpt-5.4-mini",
+        model_settings=ModelSettings(
+            max_tokens=25000,
+        ),
+    )
+    ```
+
+    Working from examples:
+
+    - Browse `./examples` for runnable demos and patterns you can adapt.
+    - Use the `.cursorrules` file at the repo root with your AI coding agent (Cursor, Claude Code, etc.).
+    - Follow the Cursor IDE guide: https://agency-swarm.ai/welcome/getting-started/cursor-ide
+
+
+4. **Define Agency Communication Flows**:
+Establish how your agents will communicate with each other.
+
+    ```python
+    from agency_swarm import Agency
+    # if importing from local files
+    from Developer import Developer
+    from VirtualAssistant import VirtualAssistant
+
+    dev = Developer()
+    va = VirtualAssistant()
+
+    agency = Agency(
+        ceo,  # CEO will be the entry point for communication with the user
+        communication_flows=[
+            ceo > dev,  # CEO can initiate communication with Developer
+            ceo > va,   # CEO can initiate communication with Virtual Assistant
+            dev > va    # Developer can initiate communication with Virtual Assistant
+        ],
+        shared_instructions='agency_manifesto.md', # shared instructions for all agents
+    )
+    ```
+
+     In Agency Swarm, communication flows are directional. The `>` operator defines allowed initiations (left can initiate a chat with right).
+
+5. **Run a Demo**
+
+Web UI:
+```python
+agency.copilot_demo()
+```
 
-- [ ] [Invite team members and collaborators](https://docs.gitlab.com/ee/user/project/members/)
-- [ ] [Create a new merge request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html)
-- [ ] [Automatically close issues from merge requests](https://docs.gitlab.com/ee/user/project/issues/managing_issues.html#closing-issues-automatically)
-- [ ] [Enable merge request approvals](https://docs.gitlab.com/ee/user/project/merge_requests/approvals/)
-- [ ] [Set auto-merge](https://docs.gitlab.com/ee/user/project/merge_requests/merge_when_pipeline_succeeds.html)
+Terminal:
+```python
+agency.tui()
+```
 
-## Test and Deploy
+On first run, Agency Swarm sets up the terminal app automatically, shows a short setup message, and reuses it on later runs.
 
-Use the built-in continuous integration in GitLab.
+See the terminal workflow guide: https://agency-swarm.ai/core-framework/agencies/agent-swarm-cli
 
-- [ ] [Get started with GitLab CI/CD](https://docs.gitlab.com/ee/ci/quick_start/index.html)
-- [ ] [Analyze your code for known vulnerabilities with Static Application Security Testing(SAST)](https://docs.gitlab.com/ee/user/application_security/sast/)
-- [ ] [Deploy to Kubernetes, Amazon EC2, or Amazon ECS using Auto Deploy](https://docs.gitlab.com/ee/topics/autodevops/requirements.html)
-- [ ] [Use pull-based deployments for improved Kubernetes management](https://docs.gitlab.com/ee/user/clusters/agent/)
-- [ ] [Set up protected environments](https://docs.gitlab.com/ee/ci/environments/protected_environments.html)
+Programmatic (async):
+```python
+import asyncio
 
-***
+async def main():
+    resp = await agency.get_response("Create a project skeleton.")
+    print(resp.final_output)
 
-# Editing this README
+asyncio.run(main())
+```
 
-When you're ready to make this README your own, just edit this file and use the handy template below (or feel free to structure it however you want - this is just a starting point!). Thank you to [makeareadme.com](https://www.makeareadme.com/) for this template.
+Need sync? `agency.get_response_sync(...)` exists, but async is recommended.
 
-## Suggestions for a good README
-Every project is different, so consider which of these sections apply to yours. The sections used in the template are suggestions for most open source projects. Also keep in mind that while a README can be too long and detailed, too long is better than too short. If you think your README is too long, consider utilizing another form of documentation rather than cutting out information.
+### Folder Structure
 
-## Name
-Choose a self-explaining name for your project.
+Recommended agent folder structure:
 
-## Description
-Let people know what your project can do specifically. Provide context and add a link to any reference visitors might be unfamiliar with. A list of Features or a Background subsection can also be added here. If there are alternatives to your project, this is a good place to list differentiating factors.
+```
+/your-specified-path/
+│
+├── agency_manifesto.md or .txt # Agency's guiding principles (created if not present)
+└── AgentName/                  # Directory for the specific agent
+    ├── files/                  # Directory for files that will be uploaded to OpenAI
+    ├── schemas/                # Directory for OpenAPI schemas to be converted into tools
+    ├── tools/                  # Directory for tools to be imported by default.
+    ├── AgentName.py            # The main agent class file
+    ├── __init__.py             # Initializes the agent folder as a Python package
+    ├── instructions.md or .txt # Instruction document for the agent
+    └── tools.py                # Custom tools specific to the agent's role.
 
-## Badges
-On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.
+```
 
-## Visuals
-Depending on what you are making, it can be a good idea to include screenshots or even a video (you'll frequently see GIFs rather than actual videos). Tools like ttygif can help, but check out Asciinema for a more sophisticated method.
+This structure ensures that each agent has its dedicated space with all necessary files to start working on its specific tasks. The `tools.py` can be customized to include tools and functionalities specific to the agent's role.
 
-## Installation
-Within a particular ecosystem, there may be a common way of installing things, such as using Yarn, NuGet, or Homebrew. However, consider the possibility that whoever is reading your README is a novice and would like more guidance. Listing specific steps helps remove ambiguity and gets people to using your project as quickly as possible. If it only runs in a specific context like a particular programming language version or operating system or has dependencies that have to be installed manually, also add a Requirements subsection.
+## Learn More
 
-## Usage
-Use examples liberally, and show the expected output if you can. It's helpful to have inline the smallest example of usage that you can demonstrate, while providing links to more sophisticated examples if they are too long to reasonably include in the README.
+- Installation: https://agency-swarm.ai/welcome/installation
+- From Scratch guide: https://agency-swarm.ai/welcome/getting-started/from-scratch
+- Cursor IDE workflow: https://agency-swarm.ai/welcome/getting-started/cursor-ide
+- Tools overview: https://agency-swarm.ai/core-framework/tools/overview
+- Agents overview: https://agency-swarm.ai/core-framework/agents/overview
+- Agencies overview: https://agency-swarm.ai/core-framework/agencies/overview
+- Communication flows: https://agency-swarm.ai/core-framework/agencies/communication-flows
+- Running an agency: https://agency-swarm.ai/core-framework/agencies/running-agency
+- Agent Swarm CLI: https://agency-swarm.ai/core-framework/agencies/agent-swarm-cli
+- Observability: https://agency-swarm.ai/additional-features/observability
 
-## Support
-Tell people where they can go to for help. It can be any combination of an issue tracker, a chat room, an email address, etc.
+## Contributing
 
-## Roadmap
-If you have ideas for releases in the future, it is a good idea to list them in the README.
+For details on how to contribute to Agency Swarm, please refer to the [Contributing Guide](CONTRIBUTING.md).
 
-## Contributing
-State if you are open to contributions and what your requirements are for accepting them.
+## License
 
-For people who want to make changes to your project, it's helpful to have some documentation on how to get started. Perhaps there is a script that they should run or some environment variables that they need to set. Make these steps explicit. These instructions could also be useful to your future self.
+Agency Swarm is open-source and licensed under [MIT](https://opensource.org/licenses/MIT).
 
-You can also document commands to lint the code or run tests. These steps help to ensure high code quality and reduce the likelihood that the changes inadvertently break something. Having instructions for running tests is especially helpful if it requires external setup, such as starting a Selenium server for testing in a browser.
 
-## Authors and acknowledgment
-Show your appreciation to those who have contributed to the project.
 
-## License
-For open source projects, say how it is licensed.
+## Need Help?
 
-## Project status
-If you have run out of energy or time for your project, put a note at the top of the README saying that development has slowed down or stopped completely. Someone may choose to fork your project or volunteer to step in as a maintainer or owner, allowing your project to keep going. You can also make an explicit request for maintainers.
+If you need help creating custom agent swarms for your business, check out our [Agents-as-a-Service](https://agents.vrsen.ai/) subscription, or schedule a consultation with me at https://calendly.com/vrsen/ai-readiness-call

docs/.prettierrc

@@ -0,0 +1,9 @@
+{
+  "semi": true,
+  "singleQuote": false,
+  "tabWidth": 2,
+  "printWidth": 120,
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "trailingComma": "none"
+}

docs/additional-features/agency-context.mdx

@@ -0,0 +1,281 @@
+---
+title: "Agency Context"
+description: "Sharing data and state across tools and agents using agency context."
+icon: "database"
+---
+
+`Agency Context` is a centralized data store accessible by all tools and agents within an agency. It allows you to share data between agents, control execution flow, and maintain state across tool calls without passing large data structures in messages.
+
+<Note>
+Agency context is available when tools are deployed together with agents. If tools are deployed as separate APIs, they won't share the same context, and you'll need to implement your own state management solution.
+</Note>
+
+## Understanding Agency Context
+
+Agency context is particularly useful when your agents interact with multiple tools that need to exchange information. Here's why:
+
+- **Without Agency Context**: Suppose `Tool A` collects data that `Tool B` needs. The agent must explicitly pass this data as a parameter to `Tool B`, consuming tokens and potentially hitting message limits.
+
+![Without Agency Context](/images/shared-state-without.png)
+
+- **With Agency Context**: `Tool A` can store the required data in the agency context, and `Tool B` can retrieve it without needing direct parameter passing. This approach reduces complexity, saves tokens, and enables additional workflows.
+
+![With Agency Context](/images/shared-state-with.png)
+
+## Using Agency Context
+
+The agency context is accessible in both FunctionTools and BaseTools using `.get` and `.set`, which let you access and modify the MasterContext passed during execution.
+
+Below is an example of how it can be used across tools.
+In this example, calling the Query Database tool stores database context, which is later retrieved by the Answer Question tool.
+
+<Tabs>
+
+<Tab title="BaseTool">
+
+  For BaseTools, access the agency context using `self.context`.
+
+    ```python
+    from agency_swarm.tools import BaseTool
+    from pydantic import Field
+
+    class QueryDatabase(BaseTool):
+        """
+        Retrieves data from the database and stores it in the agency context.
+        """
+        question: str = Field(..., description="The query to execute.")
+
+        async def run(self):
+            # Fetch data based on the question
+            context = query_database_api(self.question)
+
+            # Store the context in the agency context
+            assert self.context is not None
+            self.context.set('database_context', context)
+            self.context.set('last_query', self.question)
+
+            return "Database context has been retrieved and stored successfully."
+
+    class AnswerQuestion(BaseTool):
+        """
+        Provides answers based on the context stored in the agency context.
+        """
+        async def run(self):
+            # Access the stored context
+            assert self.context is not None
+            context = self.context.get('database_context')
+
+            if not context:
+                return "Database context is missing. Please call the query_database tool first."
+
+            # Generate an answer using the context
+            answer = f"Answer derived from context: {context}"
+            return answer
+    ```
+</Tab>
+
+<Tab title="Function Tool">
+    For FunctionTools, access the context using the following methods:
+    - **Setting** a value: `ctx.context.set('key', value)`
+    - **Getting** a value: `ctx.context.get('key', default_value)`
+    ```python
+    from agency_swarm import MasterContext, RunContextWrapper, function_tool
+
+    @function_tool
+    async def query_database(ctx: RunContextWrapper[MasterContext], question: str) -> str:
+        """
+        Retrieves data from the database and stores it in the agency context.
+        """
+        # Fetch data based on the question
+        context = query_database_api(question)
+
+        # Store the context in the agency context
+        ctx.context.set('database_context', context)
+        ctx.context.set('last_query', question)
+
+        return "Database context has been retrieved and stored successfully."
+
+    @function_tool
+    async def answer_question(ctx: RunContextWrapper[MasterContext]) -> str:
+        """
+        Provides answers based on the context stored in the agency context.
+        """
+        # Access the stored context
+        context = ctx.context.get('database_context')
+        if not context:
+            return "Database context is missing. Please call the query_database tool first."
+
+        # Generate an answer using the context
+        answer = f"Answer derived from context: {context}"
+        return answer
+    ```
+</Tab>
+</Tabs>
+
+## Advanced Agency Context Patterns
+
+### Complex Data Structures
+Agency context can store any Python object, making it perfect for complex workflows:
+
+```python
+@function_tool
+async def analyze_market_data(ctx: RunContextWrapper[MasterContext], symbols: str) -> str:
+    """Analyzes multiple stocks and stores data."""
+    symbol_list = symbols.split(',')
+
+    market_analysis = {
+        'timestamp': datetime.now().isoformat(),
+        'symbols': {},
+        'summary': {},
+        'analyst': ctx.context.current_agent_name
+    }
+
+    for symbol in symbol_list:
+        # Simulate market data fetch
+        market_analysis['symbols'][symbol] = {
+            'price': 150.0,
+            'volume': 1000000,
+            'trend': 'bullish'
+        }
+
+    # Store in agency context
+    ctx.context.set('market_analysis', market_analysis)
+    ctx.context.set('analysis_complete', True)
+
+    return f"Market analysis complete for {len(symbol_list)} symbols"
+```
+
+### Workflow Coordination
+Use agency context to coordinate multi-step workflows:
+
+```python
+@function_tool
+async def step_1_data_collection(ctx: RunContextWrapper[MasterContext], params: str) -> str:
+    """First step in a multi-step workflow."""
+    # Perform step 1
+    result = collect_data(params)
+
+    # Store progress in agency context
+    ctx.context.set('workflow_step_1', result)
+    ctx.context.set('workflow_status', 'step_1_complete')
+
+    return "Step 1 complete. Ready for step 2."
+
+@function_tool
+async def step_2_data_processing(ctx: RunContextWrapper[MasterContext]) -> str:
+    """Second step that depends on first step."""
+    # Check if step 1 is complete
+    if ctx.context.get('workflow_status') != 'step_1_complete':
+        return "Error: Step 1 must be completed first"
+
+    # Get data from step 1
+    step_1_data = ctx.context.get('workflow_step_1')
+
+    # Process the data
+    result = process_data(step_1_data)
+
+    # Update progress
+    ctx.context.set('workflow_step_2', result)
+    ctx.context.set('workflow_status', 'step_2_complete')
+
+    return "Step 2 complete. Workflow finished."
+```
+
+### Session Management
+Agency context is perfect for maintaining session state:
+
+```python
+# Initialize agency with session context
+agency = Agency(
+    entry_agent,
+    communication_flows=[(entry_agent, worker_agent)],
+    user_context={
+        'session_id': 'user_123',
+        'user_preferences': {
+            'language': 'en',
+            'timezone': 'UTC',
+            'risk_tolerance': 'moderate'
+        },
+        'session_start': datetime.now().isoformat()
+    }
+)
+```
+
+## Best Practices
+
+### Use Descriptive Keys
+Use clear, descriptive keys to avoid conflicts between different agents and workflows:
+
+```python
+# Good: Descriptive keys
+ctx.context.set('user_portfolio_analysis_2024', data)
+ctx.context.set('market_data_AAPL_realtime', market_data)
+
+# Avoid: Generic keys that might conflict
+ctx.context.set('data', data)
+ctx.context.set('result', result)
+```
+
+### Provide Default Values
+Always provide sensible defaults when retrieving data:
+
+```python
+# Good: Provides default
+user_prefs = ctx.context.get('user_preferences', {})
+risk_level = ctx.context.get('risk_tolerance', 'moderate')
+
+# Risky: No default, might return None
+risk_level = ctx.context.get('risk_tolerance')
+```
+
+### Clean Up Unneeded Data
+For long-running sessions, clean up temporary data to avoid memory issues:
+
+```python
+@function_tool
+async def cleanup_temporary_data(ctx: RunContextWrapper[MasterContext]) -> str:
+    """Cleans up temporary analysis data."""
+    temp_keys = ['temp_calculation_1', 'temp_calculation_2', 'scratch_data']
+
+    for key in temp_keys:
+        if key in ctx.context.user_context:
+            del ctx.context.user_context[key]
+
+    return "Temporary data cleaned up successfully"
+```
+
+## Migrating tools
+
+If you're migrating from Agency Swarm v0.x, and want to use new FunctionTool instead of BaseTool, here's how you can do that:
+
+**BaseTool Pattern:**
+```python
+class MyTool(BaseTool):
+    async def run(self):
+        assert self.context is not None
+        self.context.set("key", "value")
+        data = self.context.get("key", "default")
+        return "Done"
+```
+
+**FunctionTool Pattern:**
+```python
+@function_tool
+async def my_tool(ctx: RunContextWrapper[MasterContext], param: str) -> str:
+    """Updated tool using agency context."""
+    ctx.context.set("key", "value")
+    data = ctx.context.get("key", "default")
+    return "Done"
+```
+
+## Example: Complete Workflow
+
+For a full example showing agency context in action, see the [Agency Context Workflow Example](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_context.py) which demonstrates:
+
+- Multi-step data collection and analysis
+- Cross-agent data sharing
+- Session management
+- Workflow coordination
+- Context monitoring and debugging
+
+Agency context eliminates the need for complex parameter passing and enables multi-agent workflows while maintaining clean separation of concerns.

docs/additional-features/azure-openai.mdx

@@ -0,0 +1,84 @@
+---
+title: "Azure OpenAI"
+description: "Integrate Azure OpenAI with Agency Swarm to ensure secure data processing and enhanced privacy."
+icon: "microsoft"
+---
+
+Many organizations prioritize data privacy and are cautious about sharing their data with any third-parties. By leveraging Azure OpenAI, you can ensure that your data is processed only within your own secure Azure environment, and not even shared with OpenAI itself.
+
+<Info>
+Running OpenAI models on Azure is the same as deploying your own open source model on any other cloud provider.
+</Info>
+
+## Prerequisites
+
+Before you begin, ensure you have the following:
+
+1. Create an Azure Account with an active subscription. [Create an account here](https://azure.microsoft.com/en-us/free/).
+2. Get approved access to the OpenAI Service on Azure.
+3. Create an Azure OpenAI resource in [one of the available regions](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models#assistants-preview) and deploy a model to it.
+4. Obtain the endpoint URL and API key for the OpenAI resource.
+
+## Setting Up Azure OpenAI with Agency Swarm
+
+<Steps>
+<Step title="Configure the Azure OpenAI Client">
+To use Azure OpenAI, you need to configure the client to connect to your Azure OpenAI resource as follows:
+
+
+```python
+import os
+from openai import AsyncAzureOpenAI
+
+# Create a custom AsyncOpenAI client for Azure
+azure_agent = AsyncAzureOpenAI(
+    api_key=os.getenv("AZURE_OPENAI_KEY"),
+    azure_endpoint=os.getenv("AZURE_ENDPOINT"),
+    api_version=os.getenv("AZURE_API_VERSION"),
+)
+```
+
+
+</Step>
+
+<Step title="Update Agent Model Parameters">
+
+Set the `model` parameter inside each agent to use your custom client and model:
+
+```python
+from agency_swarm import Agent, OpenAIChatCompletionsModel
+
+# Define your agent and pass the custom client into the model
+azure_agent = Agent(
+    name="AzureAgent",
+    instructions="You are a helpful assistant",
+    model=OpenAIChatCompletionsModel(
+        model="gpt-5.4-mini",
+        openai_client=azure_agent,
+    ),
+)
+```
+<Note>
+Model deployment name might be different from the standard OpenAI model names. It is set by you when you deploy a model to Azure.
+</Note>
+
+</Step>
+
+<Step title="Run Your Agency">
+
+After configuring the client and updating the agents, you can run your agency as usual:
+
+```python
+import asyncio
+from agency_swarm import Agency
+
+agency=Agency(azure_agent)
+
+agency.tui()
+```
+
+The first terminal run downloads the matching terminal app automatically.
+</Step>
+</Steps>
+
+For other model providers (Anthropic, Google, AWS Bedrock, etc.), see [Third-Party Models](/additional-features/third-party-models).

docs/additional-features/custom-communication-flows/common-use-cases.mdx

@@ -0,0 +1,85 @@
+---
+title: "Common Use Cases"
+description: "Explore common use cases for custom communication flows in Agency Swarm."
+icon: "code"
+---
+
+In the following sections, we'll look at some common use cases for creating custom communication flows and how to implement them in Agency Swarm.
+
+#### 1. Adjusting Parameters and Descriptions
+
+Customize parameters by subclassing `SendMessage` and declaring extra fields directly on the class:
+
+```python
+from pydantic import Field
+from agency_swarm import SendMessage
+
+class SendMessageTask(SendMessage):
+    """Use this tool to send tasks to other agents within your agency."""
+
+    tool_name = "send_message_task"  # optional, defaults to "send_message"
+
+    task: str = Field(
+        description=(
+            "Specify the task required for the recipient agent to complete. Focus on "
+            "clarifying what the task entails rather than providing exact instructions."
+        )
+    )
+```
+
+#### 2. Adding Additional Fields
+
+You can add extra fields to capture more context, like key moments and decisions:
+
+```python
+from pydantic import Field
+from agency_swarm import SendMessage
+
+class SendMessageWithContext(SendMessage):
+    """SendMessage with key moments and decisions tracking."""
+
+    tool_name = "send_message_with_context"
+
+    key_moments: str = Field(
+        description=(
+            "Document critical moments and decision points from the current conversation "
+            "that the recipient agent needs to understand. Include context about what "
+            "has been decided or prioritized that will guide the recipient's tool selection "
+            "and task execution. For example: 'User decided to prioritize performance over cost', "
+            "'Analysis focus shifted to Q4 optimization', etc."
+        )
+    )
+    decisions: str = Field(
+        description=(
+            "Summarize the specific decisions made that will directly impact which tools "
+            "or approaches the recipient agent should use. Be explicit about choices that "
+            "narrow down the scope of work. For example: 'Prioritized performance analysis "
+            "over cost reduction', 'Selected React over Vue for frontend', etc. This helps "
+            "the recipient agent choose the most appropriate tools and approach."
+        )
+    )
+```
+
+**Usage:**
+
+```python
+from agency_swarm import Agency, Agent
+
+agent = Agent(
+    name="MyAgent",
+    instructions="You are a helpful assistant.",
+)
+
+other_agent = Agent(name="OtherAgent", instructions="Provide supporting context.")
+
+agency = Agency(
+    agent,
+    other_agent,
+    communication_flows=[(agent > other_agent, SendMessageWithContext)],
+)
+```
+
+<Tip title="Contributing">
+  If you have any ideas for new communication flows, please either adjust this page in docs, or add your new send
+  message tool in the `agency_swarm/tools/send_message` folder and open a PR!
+</Tip>

docs/additional-features/custom-communication-flows/overview.mdx

@@ -0,0 +1,128 @@
+---
+title: "Overview"
+description: "Learn how to customize communication flows for your agency."
+icon: "globe"
+---
+
+Multi-agent communication is the core functionality of any multi-agent system. Unlike all other frameworks, Agency Swarm not only allows you to define communication flows in any way you want (uniform communication flows), but also to configure the underlying logic for this feature. This means that you can create entirely new types of communication or adjust it to your own needs. Below you will find a guide on how to do all this, along with some common examples.
+
+## Pre-Made SendMessage Classes
+
+Agency Swarm contains multiple commonly requested classes for communication flows. Currently, the following classes are available:
+
+| Class Name                  | Description                                                                                                                                                                                                                               | When to Use                                                                                                    | Code Link                                                                                                            |
+| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `SendMessage` (default)     | This is the default class for sending messages to other agents. It uses synchronous communication with basic COT (Chain of Thought) prompting and allows agents to relay files and modify system instructions for each other.             | Suitable for most use cases. Balances speed and functionality.                                                 | [link](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/send_message.py)               |
+| `Handoff`                   | Enables unidirectional transfer of control to a specialized agent. When a handoff occurs, the receiving agent takes over the interaction and continues the conversation. (`SendMessageHandoff` is deprecated.)                                                                        | Use for routing queries to specialized agents or sequential workflows where control should transfer completely. | [link](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/send_message.py)       |
+
+
+#### Customizing Communication Flows
+
+To select your own custom send message tool, simply provide it as the last argument to the communication flow tuple.
+
+```python
+from agency_swarm import Agent, Handoff
+
+ceo = Agent(
+    name="CeoAgent",
+    instructions="You are a helpful assistant.",
+)
+
+worker = Agent(
+    name="WorkerAgent",
+    instructions="You are a helpful assistant.",
+)
+
+agency = Agency(ceo, communication_flows=[(ceo > worker, Handoff)])
+```
+
+Here, the `Handoff` tool will be used specifically for `ceo -> worker` communication and nowhere else. If there were other agents in the agency connected to ceo, they would be using regular `SendMessage` for agent-to-agent conversations.
+
+## Creating Your Own Unique Communication Flows
+
+To create your own communication flow, you will first need to extend the `FunctionTool` class from the agents SDK. The `SendMessage` class is built on top of `FunctionTool`, providing a flexible foundation for creating custom communication patterns tailored to your specific needs.
+
+### Custom SendMessage Class
+
+To customize SendMessage parameters, extend the `SendMessage` class and declare extra fields directly as class-level annotations with `Field()`:
+
+```python
+from pydantic import Field
+from agency_swarm import SendMessage
+
+class CustomSendMessage(SendMessage):
+    """
+    Use this tool to facilitate direct, synchronous communication between specialized agents within your agency.
+    """
+
+    tool_name = "send_message_custom"  # Optional: custom name for this tool
+
+    key_moments: str = Field(description="Critical context and decision points relevant to the task")
+    decisions: str = Field(description="Specific decisions that guide tool choice and approach")
+```
+
+The fields are automatically discovered and merged into the tool schema.
+
+### Key Components
+
+In general, all `SendMessage` tools have the following components:
+
+1. **FunctionTool Base**: Extends the `FunctionTool` class from the agents SDK, providing async execution and standardized tool interfaces.
+2. **Dynamic Initialization**: Tools are created dynamically for specific sender->recipient pairs with custom parameter schemas.
+3. **JSON Schema**: Parameters are defined using JSON schema for validation and type safety.
+4. **Async Communication**: Uses `async/await` for non-blocking communication between agents.
+
+When creating your own `SendMessage` tools, extend `FunctionTool` and implement the `on_invoke_tool` method with your custom communication logic.
+
+<Warning>
+If you are planning to create an agent that has access to multiple SendMessage tools (using communication flow pattern), each tool **must** have a unique name, which **must** start with `send_message`.
+Set it via the `tool_name` class attribute, e.g. `tool_name = "send_message_formatted"`.
+</Warning>
+
+### Custom Handoff Class
+
+By default, whenever a handoff occurs, prior to transferring the chat, a special system message will be added to the chat history to remind the recipient agent that a handoff has happened. This helps to reduce the amount of hallucinations and agent confusion whenever a chat transfer happens.
+You can customize the reminder message or disable it entirely by defining a custom Handoff class as follows (see [`add_reminder`](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/send_message.py) and [`handoff_reminder`](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py) parameters). Set `handoff_reminder` on the agent that receives the handoff so the message appears in its context:
+
+```python
+from agency_swarm import Agency, Agent, Handoff
+
+class NoReminderHandoff(Handoff):
+    add_reminder = False # Set to False to completely remove the extra message
+
+sender = Agent(name="NoReminderSender")
+recipient = Agent(name="NoReminderAgent")
+
+agency = Agency(
+    sender,
+    recipient,
+    communication_flows=[(sender > recipient, NoReminderHandoff)],
+)
+```
+
+```python
+from agency_swarm import Agency, Agent, Handoff
+
+sender = Agent(name="CustomHandoffSender")
+recipient = Agent(
+    name="CustomHandoffAgent",
+    # Delivered to this agent whenever it receives a handoff.
+    handoff_reminder="You are now the active agent. Summarize received context and answer user query.",
+)
+
+agency = Agency(
+    sender,
+    recipient,
+    communication_flows=[(sender > recipient, Handoff)],
+)
+```
+
+### Common Use Cases
+
+For detailed **Common Use Cases**, please refer to the [Common Use Cases](./common-use-cases) subpage.
+
+## Conclusion
+
+Agency Swarm has been designed to give you, the developer, full control over your systems. It is the only framework that does not hard-code any prompts, parameters, or even worse, agents for you. With this new feature, the last part of the system that you couldn't fully customize to your own needs is now gone!
+
+So, we want to encourage you to keep experimenting and designing your own unique communication flows. While the examples above should serve as a good starting point, they do not even merely scratch the surface of what's possible here! We are looking forward to seeing what you will create. Please share it in our [Discord server](https://discord.gg/7HcABDpFPG) so we can all learn from each other.

docs/additional-features/deployment-to-production.mdx

@@ -0,0 +1,149 @@
+---
+title: "Deployment to Production"
+description: "Step-by-step guide for deploying your agency in a production environment."
+icon: "rocket-launch"
+sidebarTitle: "Deploy"
+---
+
+**Recommended:** Use the [Starter Template](/welcome/getting-started/starter-template) for production. It ships with FastAPI endpoints, auth, and a clean project layout.
+
+## Required Environment Variables
+
+Before deploying, ensure these are set in your production environment:
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `OPENAI_API_KEY` | Yes | Your OpenAI API key |
+| `APP_TOKEN` | Recommended | Authentication token for FastAPI endpoints |
+
+<Note>
+Thread persistence uses callbacks you define to store threads in any database you choose.
+</Note>
+
+<Note>
+  This guide assumes you have already created an agency. If you haven't, check out the [Getting Started](/welcome/installation) guide.
+</Note>
+
+<Warning>
+  Before deploying, ensure you have thoroughly tested all tools and agents. Run the test cases in each tool file and verify the agency works end-to-end using demo methods.
+</Warning>
+
+## Deployment Process
+
+<Steps>
+
+<Step title="Step 1: Persist Conversation Threads" icon="message-dots">
+
+By default, every time you create a new `Agency()`, it starts a fresh conversation thread. In production, you usually need to resume prior conversations or handle multiple users.
+
+<Info>
+Persist the full conversation history for each chat, including user-facing turns and agent-to-agent handoffs.
+</Info>
+
+Chat persistence is handled through callback functions passed to the Agency constructor:
+
+```python
+from agents import TResponseInputItem
+from agency_swarm import Agency
+
+
+def save_threads(messages: list[TResponseInputItem], chat_id: str) -> None:
+    save_threads_to_db(chat_id, messages)
+
+def load_threads(chat_id: str) -> list[TResponseInputItem]:
+    return load_threads_from_db(chat_id)
+
+agency = Agency(
+    agent1,
+    agent2,
+    communication_flows=[(agent1, agent2)],
+    load_threads_callback=lambda: load_threads(chat_id),
+    save_threads_callback=lambda messages: save_threads(messages, chat_id),
+)
+```
+
+<Warning>
+If you switch model providers for an existing saved chat, old tool/event items may no longer replay correctly. Start a new chat, or keep only `{role, content}` messages.
+</Warning>
+
+</Step>
+
+<Step title="Step 2: Configure FastAPI Endpoints" icon="diagram-project">
+
+Use FastAPI in one of two ways:
+
+- Single agency: call `agency.run_fastapi(...)` from an `Agency` instance.
+- Multiple agencies and/or standalone tools: use top-level `run_fastapi(agencies=..., tools=[...])`.
+
+<Info>
+There can be multiple agencies in one server, and each agency key becomes its own endpoint prefix.
+</Info>
+
+```python
+from agency_swarm import Agency, Agent, function_tool, run_fastapi
+
+@function_tool
+def health_check() -> str:
+    return "ok"
+
+def create_support_agency(load_threads_callback=None):
+    support = Agent(name="Support", instructions="You are a support agent.")
+    return Agency(
+        support,
+        name="support",
+        load_threads_callback=load_threads_callback,
+    )
+
+def create_sales_agency(load_threads_callback=None):
+    sales = Agent(name="Sales", instructions="You are a sales agent.")
+    return Agency(
+        sales,
+        name="sales",
+        load_threads_callback=load_threads_callback,
+    )
+
+run_fastapi(
+    agencies={
+        "support": create_support_agency,
+        "sales": create_sales_agency,
+    },
+    tools=[health_check],
+    app_token_env="APP_TOKEN",
+    cors_origins=["https://your-app.example"],
+)
+```
+
+<Note>
+`run_fastapi(agencies=...)` injects `load_threads_callback` per request (for `chat_history`) and does not inject `save_threads_callback`.
+If you need server-side persistence writes, wire that explicitly in your application flow.
+</Note>
+
+This creates separate agency endpoints plus tool endpoints, for example:
+
+- `/support/get_response` and `/support/get_response_stream`
+- `/sales/get_response` and `/sales/get_response_stream`
+- `/tool/health_check`
+
+FastAPI details:
+
+- [Setting Up FastAPI Endpoints](/additional-features/fastapi-integration#setting-up-fastapi-endpoints)
+- [Authentication](/additional-features/fastapi-integration#authentication)
+- [Implementation reference (multiple agencies and tools)](/additional-features/fastapi-integration#implementation-reference)
+- [API Usage Example](/additional-features/fastapi-integration#api-usage-example)
+
+If you need tools hosted separately from your agency service, expose tools as APIs and connect them with [OpenAPI schemas](/core-framework/tools/openapi-schemas), or use [MCP Integration](/core-framework/tools/mcp-integration).
+
+</Step>
+
+<Step title="Step 3: Deploy the Service" icon="rocket-launch">
+
+Use the [Starter Template](/welcome/getting-started/starter-template) as your production base. It already includes FastAPI wiring and deployment defaults.
+
+- Create a repo from the template
+- Set `OPENAI_API_KEY` and `APP_TOKEN`
+- Follow the template README to deploy
+
+If you are wiring your own server, see [FastAPI Integration](/additional-features/fastapi-integration) for endpoint and parameter details (`host`, `port`, `app_token_env`, `cors_origins`, `enable_agui`).
+
+</Step>
+</Steps>

docs/additional-features/fastapi-integration.mdx

@@ -0,0 +1,480 @@
+---
+title: "FastAPI Integration"
+description: "Serving your agencies and tools as APIs with FastAPI."
+icon: "server"
+---
+
+Agency Swarm supports serving your agencies and tools as production-ready HTTP APIs using [FastAPI](https://fastapi.tiangolo.com/). This enables you to interact with your agents and tools over HTTP, integrate with other services, or connect it to web frontends.
+
+## Installation
+
+FastAPI integration is an **optional installation**. To install all required dependencies, run:
+
+```bash
+pip install "agency-swarm[fastapi]"
+```
+
+## Setting Up FastAPI Endpoints
+
+You can expose your agencies and tools as API endpoints using the `run_fastapi()` function.
+
+### Example: Create an API endpoint for a single agency
+
+```python
+from agency_swarm import Agency, Agent
+
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant."
+)
+
+agency = Agency(agent, name="test_agency")
+
+agency.run_fastapi()
+```
+
+<Accordion title="run_fastapi parameters" defaultOpen={false}>
+
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| `host` | string | `"0.0.0.0"` | Interface to bind the server. |
+| `port` | integer | `8000` | Port to serve FastAPI on. |
+| `app_token_env` | string | `"APP_TOKEN"` | Env var name for the bearer token; if missing, auth is disabled. |
+| `return_app` | boolean | `false` | Return the FastAPI app instead of running the server. |
+| `cors_origins` | list | `["*"]` | Allowed CORS origins. When set to `["*"]`, `allow_credentials` is automatically set to `False` for security. |
+| `enable_agui` | boolean | `false` | Enable AG-UI streaming (hides the cancel endpoint). |
+| `enable_logging` | boolean | `false` | Track requests and expose `/get_logs` at the server root. |
+| `logs_dir` | string | `"activity-logs"` | Folder for request logs when logging is enabled. |
+| `allowed_local_file_dirs` | list | `None` | Allowlist for local `file_urls`; paths outside the list are rejected. |
+
+</Accordion>
+
+<Accordion title="Endpoint reference" defaultOpen={false}>
+
+- Agencies are served at:
+  - `/your_agency_name/get_response` (POST)
+  - `/your_agency_name/get_response_stream` (POST, streaming responses)
+  - `/your_agency_name/cancel_response_stream` (POST; not registered when `enable_agui=True`)
+  - `/your_agency_name/get_metadata` (GET)
+  - `/get_logs` (GET; when `enable_logging=True`)
+- Tools registered via `tools=[...]` are available at `/tool/ToolClassName` (BaseTools) or `/tool/function_name` (function tools).
+- OpenAPI and interactive docs: `/openapi.json`, `/docs`, `/redoc`.
+
+</Accordion>
+
+<Accordion title="Response format" defaultOpen={false}>
+
+**Non-streaming (`/get_response`):**
+
+```json
+{
+  "response": "Hello! How can I help you today?",
+  "new_messages": [
+    {
+      "type": "message",
+      "role": "user",
+      "content": [{"type": "input_text", "text": "Hello"}],
+      "agent": "Assistant",
+      "callerAgent": null,
+      "timestamp": 1704067200000
+    },
+    {
+      "type": "message",
+      "role": "assistant",
+      "content": [{"type": "output_text", "text": "Hello! How can I help you today?"}],
+      "agent": "Assistant",
+      "callerAgent": null,
+      "timestamp": 1704067201000
+    }
+  ],
+  "usage": {"input_tokens": 50, "output_tokens": 12, "total_cost": 0.0001},
+  "file_ids_map": {"document.pdf": "file-abc123"}
+}
+```
+
+**Streaming (`/get_response_stream`):**
+
+```
+event: meta
+data: {"run_id": "550e8400-e29b-41d4-a716-446655440000"}
+
+data: {"data": {"data": {"type": "response.output_text.delta", "delta": "Hello"}}}
+data: {"data": {"data": {"type": "response.output_text.delta", "delta": "!"}}}
+
+event: messages
+data: {"new_messages": [...], "run_id": "...", "cancelled": false, "usage": {...}, "file_ids_map": {...}}
+
+event: end
+data: [DONE]
+```
+
+**Cancel (`/cancel_response_stream`):**
+
+```json
+{
+  "ok": true,
+  "run_id": "550e8400-e29b-41d4-a716-446655440000",
+  "cancelled": true,
+  "cancel_mode": "immediate",
+  "new_messages": [...]
+}
+```
+
+**Metadata (`/get_metadata`):**
+
+```json
+{
+  "nodes": [
+    {
+      "id": "Assistant",
+      "type": "agent",
+      "data": {
+        "label": "Assistant",
+        "description": "Main assistant agent",
+        "conversationStarters": ["Support: I need help with billing"],
+        "quickReplies": ["hi", "hello"],
+        "isEntryPoint": true,
+        "toolCount": 2,
+        "tools": [
+          {
+            "name": "example_tool",
+            "type": "function",
+            "description": "...",
+            "inputSchema": {"type": "object", "properties": {"text": {"type": "string"}}}
+          }
+        ]
+      }
+    }
+  ],
+  "edges": [
+    {"id": "CEO->Developer", "source": "CEO", "target": "Developer", "type": "communication"}
+  ],
+  "metadata": {
+    "agencyName": "my_agency",
+    "totalAgents": 2,
+    "totalTools": 4,
+    "agents": ["CEO", "Developer"],
+    "entryPoints": ["CEO"]
+  },
+  "agency_swarm_version": "1.0.0"
+}
+```
+
+Conversation starters appear under `data.conversationStarters`, and quick-reply phrases appear under `data.quickReplies` when configured. See [Agent Overview](/core-framework/agents/overview).
+
+**Tool (`/tool/<name>`):**
+
+```json
+{
+  "response": "Output returned by the tool"
+}
+```
+
+</Accordion>
+
+<Accordion title="Usage tracking" defaultOpen={false}>
+
+Responses include a `usage` object with token counts and cost by default. For streaming, the final `event: messages` payload includes the same `usage` object.
+
+To understand what's inside `usage`, see [Observability](/additional-features/observability#usage-payload).
+
+Usage tracking is configured on the agent (not on FastAPI):
+
+```python
+from agency_swarm import Agent, ModelSettings
+
+agent = Agent(
+    name="Assistant",
+    instructions="You are a helpful assistant.",
+    model_settings=ModelSettings(include_usage=False),
+)
+```
+
+If you're using LiteLLM models and want usage in streaming responses, keep `include_usage=True`.
+
+</Accordion>
+
+<Note>
+Stream cancellation uses an in-memory registry per process. Use single-worker deployments (e.g., uvicorn `workers=1`) or sticky routing so cancel requests reach the same worker.
+</Note>
+
+### Authentication
+
+Set the environment variable named by `app_token_env` (default `APP_TOKEN`) to require `Authorization: Bearer <token>` on every endpoint. When the variable is absent, authentication is disabled.
+
+### Implementation reference
+
+<Accordion title="Example: Serving Multiple Agencies and Tools" defaultOpen={false}>
+
+```python
+from agency_swarm import Agency, Agent, function_tool, run_fastapi
+
+# Example tools using agents SDK
+@function_tool
+def example_tool(example_field: str) -> str:
+    """Example tool with input field."""
+    return f"Result of ExampleTool operation with {example_field}"
+
+@function_tool
+def test_tool(example_field: str) -> str:
+    """Test tool with input field."""
+    return f"Result of TestTool operation with {example_field}"
+
+# Create agents
+agent1 = Agent(name="Assistant1", instructions="You are assistant 1.")
+agent2 = Agent(name="Assistant2", instructions="You are assistant 2.")
+
+# Create agency factory functions for proper thread management
+def create_agency_1(load_threads_callback=None, save_threads_callback=None):
+    return Agency(
+        agent1, 
+        name="test_agency_1",
+        load_threads_callback=load_threads_callback,
+        save_threads_callback=save_threads_callback,
+    )
+
+def create_agency_2(load_threads_callback=None, save_threads_callback=None):
+    return Agency(
+        agent2, 
+        name="test_agency_2",
+        load_threads_callback=load_threads_callback,
+        save_threads_callback=save_threads_callback,
+    )
+
+run_fastapi(
+    agencies={
+        "test_agency_1": create_agency_1,
+        "test_agency_2": create_agency_2,
+    },
+    tools=[example_tool, test_tool],
+)
+```
+
+Endpoints follow the reference above; tool schemas mirror the definitions of `example_tool` and `test_tool`.
+
+</Accordion>
+
+---
+
+## API Usage Example
+
+You can interact with your agents and tools using HTTP requests:
+
+```python
+import requests
+
+agency_url = "http://127.0.0.1:8000/test_agency_1/get_response"
+payload = {
+    "message": "Hello",
+    "client_config": {
+        "base_url": "https://my-openai-gateway.example.com/v1",
+        "api_key": "sk-...",  # override per request
+    },
+}
+
+headers = {
+    "Authorization": "Bearer 123"  # Replace with your actual token if needed
+}
+
+agency_response = requests.post(agency_url, json=payload, headers=headers)
+print("Status code:", agency_response.status_code)
+print("Response:", agency_response.json())
+```
+
+<Accordion title="Request payload" defaultOpen={false}>
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `message` | string or structured list | Yes | User message to start or continue the conversation. Use a structured Responses input list for inline `input_text`, `input_image`, or `input_file` content. |
+| `chat_history` | list | No | Flat list of prior messages with metadata (`agent`, `callerAgent`, `timestamp`) to preserve context. |
+| `recipient_agent` | string | No | Target agent when you want to direct the next turn. |
+| `file_ids` | list | No | IDs of already uploaded files to attach. |
+| `file_urls` | object | No | `{filename: url_or_absolute_path}` map. Local paths require `allowed_local_file_dirs` on `run_fastapi`. |
+| `additional_instructions` | string | No | Extra guidance for the current request. |
+| `user_context` | object | No | Structured data passed to [Agency Context](/additional-features/agency-context) without exposing it to the LLM. |
+| `client_config` | object | No | Override `base_url` / `api_key` for this request (and optional `litellm_keys` for `litellm/` models). |
+
+### How user_context is applied
+- Merges with any `user_context` set on the agency instance.
+- Useful for structured data (ids, preferences, feature flags) you do not want in the prompt.
+- Accessible within tools for the duration of the run. See [Agency Context](/additional-features/agency-context).
+
+### How client_config is applied
+- Applies only to **OpenAI models** (no prefix or `openai/...`) and **LiteLLM models** (`litellm/...`).
+- **Custom Model subclasses** are not modified; the request still runs, but the override is skipped.
+- For LiteLLM, you can provide `litellm_keys` to pass different keys per provider. Requires LiteLLM installed.
+
+### client_config fields
+
+- `base_url` (string, optional): Override the API base URL for this request.
+- `api_key` (string, optional): Override the API key for this request.
+- `litellm_keys` (object, optional): Only for `litellm/...` models.
+  - Map `provider_name` → `api_key`.
+  - Example: `{"anthropic": "...", "gemini": "..."}`
+
+<Accordion title="client_config examples" defaultOpen={false}>
+
+**OpenAI model override (gpt-4o):**
+
+```json
+{
+  "message": "Hello",
+  "client_config": {
+    "base_url": "https://my-openai-gateway.example.com/v1",
+    "api_key": "sk-..."
+  }
+}
+```
+
+**LiteLLM mixed providers (requires `openai-agents[litellm]`):**
+
+```json
+{
+  "message": "Hello",
+  "client_config": {
+    "base_url": "https://my-litellm-proxy.example.com",
+    "litellm_keys": {
+      "anthropic": "sk-ant-...",
+      "gemini": "AIza..."
+    }
+  }
+}
+```
+
+</Accordion>
+
+</Accordion>
+
+
+## Cancelling Active Streams
+
+The streaming endpoint supports cancellation via two methods:
+
+### 1. Automatic Cancellation on Disconnect
+
+When a client disconnects (tab close, refresh, network failure), the stream is automatically cancelled to preserve token costs.
+
+### 2. Cancel Endpoint
+
+Call the cancel endpoint with the `run_id` received from the first event of the streaming response. 
+This will allow you to retrieve intermediate results that were generated before the run cancellation.
+Optionally include `cancel_mode` (defaults to `immediate`):
+- `immediate` — stop right away and return messages that were fully generated; the in-progress message is discarded.
+- `after_turn` — finish the current turn, then stop.
+
+```python
+import requests
+
+# Cancel an active stream
+cancel_url = "http://127.0.0.1:8000/test_agency/cancel_response_stream"
+payload = {"run_id": "your-run-id", "cancel_mode": "after_turn"}  # cancel_mode is optional
+response = requests.post(cancel_url, json=payload)
+# Returns: {"ok": True, "run_id": "...", "cancelled": True, "cancel_mode": "after_turn", "new_messages": [...]}
+```
+
+---
+
+## Serving Standalone Tools
+
+Expose tools as simple HTTP endpoints for external systems, webhooks, or other agents to call directly without agency orchestration.
+
+```python
+from agency_swarm import BaseTool, run_fastapi
+
+class Address(BaseTool):
+    street: str
+    zip_code: int
+
+    def run(self) -> str:
+        return f"{self.street} {self.zip_code}"
+
+run_fastapi(tools=[Address], port=8080)
+```
+
+This creates:
+- `POST /tool/Address` — execute the tool
+- `GET /openapi.json` — full OpenAPI schema
+- `GET /docs` — interactive Swagger UI
+
+<Accordion title="Generate OpenAPI schema programmatically" defaultOpen={false}>
+
+Use `ToolFactory.get_openapi_schema()` to generate the OpenAPI spec programmatically:
+
+```python
+from agency_swarm.tools import ToolFactory
+
+schema = ToolFactory.get_openapi_schema(
+    [Address],
+    url="https://your-server.com",
+    title="My Tools API"
+)
+print(schema)  # Returns a JSON string
+```
+
+</Accordion>
+
+---
+
+## File Attachments
+
+Attach files to agency requests using `file_ids` or `file_urls` in the payload:
+
+```json
+{
+  "message": "Summarize this document",
+  "file_urls": {"report.pdf": "https://example.com/report.pdf"}
+}
+```
+
+For inline Responses attachments that should not be uploaded through the Files API, pass a structured `message`:
+
+```json
+{
+  "message": [
+    {
+      "role": "user",
+      "content": [
+        {"type": "input_image", "image_url": "data:image/png;base64,...", "detail": "auto"},
+        {"type": "input_text", "text": "Describe this image"}
+      ]
+    }
+  ]
+}
+```
+
+With manual `chat_history`, clients can keep structured attachment parts in history so follow-up turns work without reattaching. This may resend inline attachment content or references; it does not reuse server-managed state, `previous_response_id`, Conversations, or `file_id` values.
+
+The response includes `file_ids_map` with the uploaded file IDs:
+
+```json
+{
+  "response": "...",
+  "file_ids_map": {"report.pdf": "file-abc123"}
+}
+```
+
+When `file_urls` is used, Agency Swarm also prepends a `system` message for that turn that records the original source string for each attached file. That system message is included in `new_messages`, so if your client persists `new_messages` as chat history, later turns will keep the original attachment source URL or local path in model context.
+
+**Supported filetypes:** `.pdf`, `.jpeg`, `.jpg`, `.gif`, `.png`, `.c`, `.cs`, `.cpp`, `.csv`, `.html`, `.java`, `.json`, `.php`, `.py`, `.rb`, `.css`, `.js`, `.sh`, `.ts`, `.pkl`, `.tar`, `.xlsx`, `.xml`, `.zip`, `.doc`, `.docx`, `.md`, `.pptx`, `.tex`, `.txt`
+
+<Accordion title="Local file paths" defaultOpen={false}>
+
+To support passing local filepaths in the `file_urls` field, set `allowed_local_file_dirs` on `run_fastapi`:
+
+```python
+run_fastapi(agencies=..., allowed_local_file_dirs=["/data/uploads"])
+```
+
+Then pass absolute file paths in `file_urls`:
+
+```json
+{"file_urls": {"doc.pdf": "/data/uploads/doc.pdf"}}
+```
+
+Invalid paths return an `error` field in the response body.
+
+<Note>
+`allowed_local_file_dirs` uses strict request-time validation for invalid entries: if an entry exists but is not a directory, local `file_urls` requests fail with an error. Missing directories are skipped and can be created later. The `/get_metadata` field `allowed_local_file_dirs` lists only currently usable directory entries.
+</Note>
+
+</Accordion>

docs/additional-features/few-shot-examples.mdx

@@ -0,0 +1,74 @@
+---
+title: "Few-Shot Examples"
+description: "Guide agent responses using few-shot prompting."
+icon: "clone"
+---
+
+
+**Few-shot prompting** is a powerful technique where you provide a small number of sample interactions (typically 2 to 5) to guide your agent's behavior. This method helps the agent understand the desired output format and task requirements by learning from the given examples, thereby improving performance without writing extensive instructions.
+
+## Crafting Effective Examples
+
+- **Provide Task Demonstrations**: Use examples that clearly illustrate the tasks that your agents will perform.
+- **Use Realistic Scenarios**: Include interactions that mirror actual conversations that your agent will handle.
+- **Use Preferred Tone and Style**: Ensure the agent's replies in your examples match your desired brand voice.
+
+## Defining Few-Shot Examples
+
+In **Agency Swarm**, few-shot examples are earlier messages that show the style you want. Put them in `instructions` as plain text or pass them as message history to `get_response` / `get_response_stream`.
+
+Optional fields like `attachments` and `metadata` can be included in message history but are not required for basic examples.
+
+## Using Few-Shot Examples
+
+Pick one of these ways:
+
+<Tabs>
+    <Tab title="Message History (Scalable)">
+
+    ```python
+    from agency_swarm import Agency, Agent
+
+    support_agent = Agent(
+        name="CustomerSupportAgent",
+        instructions="You assist customers with troubleshooting.",
+    )
+    agency = Agency(support_agent)
+
+    examples = [
+        {"role": "user", "content": "My device won't turn on."},
+        {"role": "assistant", "content": "Please hold the power button for 10 seconds to restart the device."},
+    ]
+    new_message = {"role": "user", "content": "It still won't start."}
+
+    response = await agency.get_response(examples + [new_message])
+    ```
+
+    </Tab>
+
+    <Tab title="Instructions (Simple)">
+
+    ```python
+    from agency_swarm import Agent
+
+    instructions = """
+    You assist customers with troubleshooting.
+
+    Example:
+    User: My device won't turn on.
+    Assistant: Please hold the power button for 10 seconds to restart the device.
+    """
+
+    agent = Agent(
+        name="CustomerSupportAgent",
+        instructions=instructions,
+    )
+    ```
+
+    </Tab>
+
+</Tabs>
+
+Message history is more scalable. Instructions are best for short examples.
+
+See more advanced features in [Agent Class](/core-framework/agents/advanced-configuration)

docs/additional-features/guardrails/input-guardrails.mdx

@@ -0,0 +1,288 @@
+---
+title: "Input Guardrails"
+description: "Validate incoming messages before they reach the agent."
+icon: "arrow-right-to-bracket"
+---
+
+Input guardrails validate incoming messages **before** they reach the agent. They screen both user input and inter-agent communication.
+
+## Simplified Input Processing
+
+Agency Swarm automatically extracts text content from messages, so your guardrails receive clean text instead of full message objects.
+
+## Function Signature
+
+Each input guardrail receives three parameters:
+
+```python
+from agency_swarm import Agent, GuardrailFunctionOutput, RunContextWrapper, input_guardrail
+
+@input_guardrail
+async def my_input_guardrail(
+    context: RunContextWrapper,
+    agent: Agent,
+    user_input: str | list[str],
+) -> GuardrailFunctionOutput:
+    """Validate user input."""
+    return GuardrailFunctionOutput(output_info="", tripwire_triggered=False)
+```
+
+**Parameters:**
+- `context`: Run context wrapper with access to shared state.
+- `agent`: The Agent instance receiving the input.
+- `user_input`: Extracted text content.
+  - Single message: a string containing the message content.
+  - Multiple consecutive messages: a list of strings, one per message.
+
+**Return:**
+- `GuardrailFunctionOutput` with:
+  - `tripwire_triggered` (bool): `True` if validation failed.
+  - `output_info` (str): Guidance message returned to the caller.
+
+<Note>
+File and image inputs inside messages are not passed to input guardrails.
+</Note>
+
+## Input Types
+
+When a user sends multiple messages:
+
+```json
+[
+  {"role": "user", "content": "Hi"},
+  {"role": "user", "content": "How are you?"}
+]
+```
+
+Your guardrail receives:
+
+```python
+["Hi", "How are you?"]
+```
+
+This allows you to process each new input message individually or validate them as a group.
+
+## Basic Input Guardrail
+
+```python
+from agency_swarm import Agent, GuardrailFunctionOutput, RunContextWrapper, input_guardrail
+
+@input_guardrail
+async def require_task_prefix(
+    context: RunContextWrapper, agent: Agent, user_input: str | list[str]
+) -> GuardrailFunctionOutput:
+    text = user_input if isinstance(user_input, str) else " ".join(user_input)
+    blocked = not text.startswith("Request:")
+
+    return GuardrailFunctionOutput(
+        output_info="Prefix your request with 'Request:' describing what you need." if blocked else "",
+        tripwire_triggered=blocked,
+    )
+
+agent = Agent(
+    name="CustomerSupportAgent",
+    instructions="You are a helpful customer support agent.",
+    input_guardrails=[require_task_prefix],
+)
+```
+
+## Practical Example: Filtering Off-Topic Questions
+
+Use input guardrails to keep agents focused on their domain. This example delegates relevance decisions to an evaluator agent:
+
+```python
+from agency_swarm import (
+    Agent,
+    GuardrailFunctionOutput,
+    ModelSettings,
+    Reasoning,
+    RunContextWrapper,
+    input_guardrail,
+)
+from pydantic import BaseModel
+
+class RelevanceDecision(BaseModel):
+    is_relevant: bool
+    reason: str
+
+guardrail_agent = Agent(
+    name="GuardrailAgent",
+    instructions=(
+        "You screen incoming messages for a customer-support assistant. "
+        "Treat questions about account access, billing, and troubleshooting as relevant. "
+        "Flag any unrelated requests as irrelevant."
+    ),
+    model="gpt-5.4-mini",
+    model_settings=ModelSettings(reasoning=Reasoning(effort="low")),
+    output_type=RelevanceDecision,
+)
+
+@input_guardrail
+async def require_support_topic(
+    context: RunContextWrapper, agent: Agent, user_input: str | list[str]
+) -> GuardrailFunctionOutput:
+    candidate = user_input if isinstance(user_input, str) else "\n".join(user_input)
+    guardrail_result = await guardrail_agent.get_response(candidate, context=context.context)
+    decision = RelevanceDecision.model_validate(guardrail_result.final_output)
+
+    if not decision.is_relevant:
+        return GuardrailFunctionOutput(
+            output_info="Only support questions are allowed. Ask about billing, account access, or troubleshooting.",
+            tripwire_triggered=True,
+        )
+    return GuardrailFunctionOutput(output_info="", tripwire_triggered=False)
+
+support_agent = Agent(
+    name="CustomerSupportAgent",
+    instructions="You help customers resolve account, billing, and troubleshooting issues.",
+    model="gpt-5.4-mini",
+    input_guardrails=[require_support_topic],
+    raise_input_guardrail_error=False,  # Non-strict mode: guidance returned as assistant message
+)
+```
+
+See the full example at [`examples/guardrails_input.py`](https://github.com/VRSEN/agency-swarm/blob/main/examples/guardrails_input.py).
+
+## Non-strict vs Strict Mode
+
+Input guardrails support two modes that control how guidance is delivered. Use `raise_input_guardrail_error` to control this behavior.
+
+### Non-strict Mode (Default)
+
+**Setting:** `raise_input_guardrail_error=False`
+
+In non-strict mode, guardrail guidance flows naturally as assistant output:
+- Guidance is returned as `final_output` (non-streaming) or `message_output_created` event (streaming).
+- No exception is raised.
+- Guidance persists as an assistant message with `message_origin="input_guardrail_message"`.
+
+### Strict Mode
+
+**Setting:** `raise_input_guardrail_error=True`
+
+In strict mode, guardrail failures abort the turn immediately:
+- `InputGuardrailTripwireTriggered` is raised.
+- Guidance persists as a system message with `message_origin="input_guardrail_error"`.
+- The turn is aborted before the agent processes input.
+- The caller must handle the exception.
+
+<Accordion title="Strict mode usage example">
+
+```python
+from agency_swarm import Agent, InputGuardrailTripwireTriggered
+
+agent = Agent(
+    name="CustomerSupportAgent",
+    instructions="You are a helpful customer support agent.",
+    input_guardrails=[require_task_prefix],
+    raise_input_guardrail_error=True,
+)
+
+try:
+    response = await agency.get_response("Hello!")
+except InputGuardrailTripwireTriggered as exc:
+    print(f"Validation failed: {exc.guardrail_result.output_info}")
+```
+</Accordion>
+
+### Comparison Table
+
+| Mode | `raise_input_guardrail_error` | Caller sees | Persisted entry | Role | Use case |
+|------|-------------------------------|-------------|-----------------|------|----------|
+| **Non-strict** | `False` (default) | Guardrail text as `final_output` or streaming event | Assistant message (`input_guardrail_message`) | `assistant` | Conversational flows, helpful guidance |
+| **Strict** | `True` | `InputGuardrailTripwireTriggered` exception | System message (`input_guardrail_error`) | `system` | Hard requirements, compliance, security |
+
+<Accordion title="Should I use non-strict or strict mode?">
+**Use non-strict mode when:**
+- You want a conversational user experience.
+- Agents are communicating with each other internally.
+- Guardrail feedback is helpful guidance, not a hard block.
+- You do not want to write exception handling code.
+
+**Use strict mode when:**
+- You are enforcing non-negotiable requirements.
+- Security or compliance rules must block processing.
+- You want explicit control over error handling.
+- The caller should know immediately that validation failed.
+</Accordion>
+
+<Accordion title="Streaming behavior example">
+
+```text
+RunItemStreamEvent(
+    name='message_output_created',
+    item=MessageOutputItem(
+        raw_item=ResponseOutputMessage(
+            id='msg_input_guardrail_guidance',
+            content=[ResponseOutputText(text="Prefix your request...")],
+            role='assistant',
+            status='completed'
+        )
+    )
+)
+```
+</Accordion>
+
+## Guardrails in Message History
+
+Each guardrail trigger is recorded in chat history with a guidance entry. Every entry carries `message_origin` to identify which guardrail fired.
+For most use cases, `role`, `content`, and `message_origin` are enough. Additional metadata is mainly for tracing multi-agent runs.
+
+### Message Origin Values
+
+- `input_guardrail_message`: Input guardrail in non-strict mode.
+- `input_guardrail_error`: Input guardrail in strict mode.
+- `output_guardrail_error`: Output guardrail failure (always a system message).
+
+### Persistence Behavior
+
+| Mode | `raise_input_guardrail_error` | Streaming Event | Persisted Entry |
+|------|-------------------------------|-----------------|-----------------|
+| **Non-strict** | `False` (default) | `message_output_created` with guidance text | Assistant message, `message_origin="input_guardrail_message"` |
+| **Strict** | `True` | `{"type": "error", "content": guidance}` | System message, `message_origin="input_guardrail_error"` |
+
+<Note>
+`validation_attempts` does not apply to input guardrails. Input guardrails trigger immediately on validation failure.
+</Note>
+
+### Message History After Guardrails Trip
+
+When an input guardrail trips, agent-to-agent request messages remain in history alongside guardrail guidance. This preserves context so calling agents can adjust their approach.
+
+Output guardrail messages also persist in history to guide retry attempts.
+
+<Accordion title="Example message history entries (illustrative)">
+
+```json
+[
+  {
+    "role": "assistant",
+    "content": "Please, prefix your request with 'Support:' describing what you need.",
+    "message_origin": "input_guardrail_message",
+    "agent": "CustomerSupportAgent"
+  },
+  {
+    "role": "assistant",
+    "content": "When chatting with this agent, provide your name first.",
+    "message_origin": "input_guardrail_message",
+    "agent": "DatabaseAgent",
+    "callerAgent": "CustomerSupportAgent"
+  },
+  {
+    "role": "system",
+    "content": "Do not include email addresses in your response.",
+    "message_origin": "output_guardrail_error",
+    "agent": "DatabaseAgent",
+    "callerAgent": "CustomerSupportAgent"
+  }
+]
+```
+</Accordion>
+
+## Internal Agent Communication
+
+For many agent-to-agent flows, non-strict mode (`raise_input_guardrail_error=False`) is easier to work with because guidance is returned inline instead of raising exceptions mid-chain.
+
+<Warning>
+Due to the nature of handoffs, using `Handoff` for agent-to-agent communication can bypass input guardrails between agents.
+</Warning>

docs/additional-features/guardrails/output-guardrails.mdx

@@ -0,0 +1,240 @@
+---
+title: "Output Guardrails"
+description: "Validate agent responses before they reach users."
+icon: "arrow-right-from-bracket"
+---
+
+Output guardrails validate agent responses **before** they reach users or other agents. When a guardrail trips, the agent receives feedback and retries.
+
+## Function Signature
+
+Each output guardrail receives three parameters:
+
+```python
+from agency_swarm import Agent, GuardrailFunctionOutput, RunContextWrapper, output_guardrail
+from pydantic import BaseModel
+
+@output_guardrail
+async def my_output_guardrail(
+    context: RunContextWrapper,
+    agent: Agent,
+    response_text: str | BaseModel,
+) -> GuardrailFunctionOutput:
+    """Validate agent output."""
+    return GuardrailFunctionOutput(output_info="", tripwire_triggered=False)
+```
+
+**Parameters:**
+- `context`: Run context wrapper with access to shared state.
+- `agent`: The Agent instance generating the response.
+- `response_text`: The agent response as a string, or a structured model when `output_type` is set.
+
+**Return:**
+- `GuardrailFunctionOutput` with:
+  - `tripwire_triggered` (bool): `True` if validation failed.
+  - `output_info` (str): Feedback message sent to the agent when `tripwire_triggered=True`.
+
+## Basic Output Guardrail
+
+```python
+from agency_swarm import Agent, GuardrailFunctionOutput, RunContextWrapper, output_guardrail
+
+@output_guardrail
+async def response_content_guardrail(
+    context: RunContextWrapper, agent: Agent, response_text: str
+) -> GuardrailFunctionOutput:
+    tripwire_triggered = "bad word" in response_text.lower()
+    output_info = "Please avoid using inappropriate language." if tripwire_triggered else ""
+    return GuardrailFunctionOutput(output_info=output_info, tripwire_triggered=tripwire_triggered)
+
+agent = Agent(
+    name="CustomerSupportAgent",
+    instructions="You are a helpful customer support agent.",
+    output_guardrails=[response_content_guardrail],
+)
+```
+
+## Practical Example: Preventing Sensitive Information Leaks
+
+```python
+from agency_swarm import Agent, GuardrailFunctionOutput, RunContextWrapper, output_guardrail
+
+@output_guardrail(name="ForbidSensitiveEmail")
+async def forbid_sensitive_email(
+    context: RunContextWrapper, agent: Agent, response_text: str
+) -> GuardrailFunctionOutput:
+    if "@" in response_text:
+        return GuardrailFunctionOutput(
+            output_info="Do not share email addresses. Offer to connect via the support portal instead.",
+            tripwire_triggered=True,
+        )
+    return GuardrailFunctionOutput(output_info="", tripwire_triggered=False)
+
+support_agent = Agent(
+    name="SupportPilot",
+    instructions="You handle customer support. Official email: support@example.com.",
+    model="gpt-5.4-mini",
+    output_guardrails=[forbid_sensitive_email],
+    validation_attempts=1,
+)
+```
+
+See the full example at [`examples/guardrails_output.py`](https://github.com/VRSEN/agency-swarm/blob/main/examples/guardrails_output.py).
+
+## Example: Simple Format Enforcement
+
+```python
+import json
+from agency_swarm import GuardrailFunctionOutput, RunContextWrapper, output_guardrail
+
+@output_guardrail(name="RequireJSONFormat")
+async def require_json_format(
+    context: RunContextWrapper, agent: Agent, response_text: str
+) -> GuardrailFunctionOutput:
+    try:
+        json.loads(response_text)
+        return GuardrailFunctionOutput(output_info="", tripwire_triggered=False)
+    except json.JSONDecodeError:
+        return GuardrailFunctionOutput(
+            output_info="Response must be valid JSON. Wrap your response in curly braces.",
+            tripwire_triggered=True,
+        )
+```
+
+## Output Guardrail Retry Flow
+
+When an output guardrail trips, the agent gets multiple chances to fix its response. The `validation_attempts` parameter controls this behavior.
+
+### How Retry Works
+
+<Steps>
+  <Step title="Agent generates response">
+    The agent produces its initial response.
+  </Step>
+  <Step title="Output guardrail checks response">
+    Each output guardrail validates the response.
+  </Step>
+  <Step title="If validation fails">
+    The agent receives a **system message** containing the guardrail `output_info`.
+  </Step>
+  <Step title="Agent retries">
+    The agent generates a new response, informed by that message.
+  </Step>
+  <Step title="Repeat until success or limit reached">
+    This cycle continues up to `validation_attempts` times.
+  </Step>
+  <Step title="If all attempts fail">
+    `OutputGuardrailTripwireTriggered` is raised.
+  </Step>
+</Steps>
+
+## Configure `validation_attempts`
+
+```python
+agent = Agent(
+    name="CustomerSupportAgent",
+    instructions="You are a helpful customer support agent.",
+    output_guardrails=[response_content_guardrail],
+    validation_attempts=2,
+)
+```
+
+| Setting | Behavior |
+|---------|----------|
+| `validation_attempts=0` | Fail-fast (no retry, immediate exception) |
+| `validation_attempts=1` | Default (one retry after initial failure) |
+| `validation_attempts=2+` | Multiple retries for more complex validations |
+
+<Note>
+Each retry sends the guardrail `output_info` message to the agent as a system message, giving the agent context to adjust its response.
+</Note>
+
+## Handling Validation Failures
+
+```python
+from agency_swarm import OutputGuardrailTripwireTriggered
+
+try:
+    response = await agency.get_response("Hello!")
+except OutputGuardrailTripwireTriggered as exc:
+    print(f"Validation failed: {exc.guardrail_result.output_info}")
+```
+
+## Message History
+
+Output guardrail failures are stored as system messages with `message_origin="output_guardrail_error"`.
+For most use cases, `role`, `content`, and `message_origin` are enough. Extra metadata is mainly for debugging and run tracing.
+
+| Origin | Meaning |
+|--------|---------|
+| `output_guardrail_error` | Output guardrail failure (system message) |
+
+<Accordion title="Example history entry (with debug metadata)">
+
+```json
+{
+  "role": "system",
+  "content": "You are not allowed to include your email address in your response. Ask agent to redirect user to the contact page: https://www.example.com/contact",
+  "message_origin": "output_guardrail_error",
+  "agent": "DatabaseAgent",
+  "callerAgent": "CustomerSupportAgent",
+  "agent_run_id": "agent_run_id",
+  "parent_run_id": "call_id",
+  "timestamp": 1758103770629217,
+  "type": "message"
+}
+```
+</Accordion>
+
+## Agent-to-Agent Validation
+
+Use guardrails to control how agents communicate with each other. When adding communication flows between agents, the recipient agent's guardrails define the message format.
+
+<Accordion title="Example: Task/Response contract between agents">
+
+```python
+from agency_swarm import Agency, Agent, GuardrailFunctionOutput, RunContextWrapper, input_guardrail, output_guardrail
+
+@input_guardrail(name="RequireTaskPrefix")
+async def require_task_prefix(
+    context: RunContextWrapper, agent: Agent, agent_input: str | list[str]
+) -> GuardrailFunctionOutput:
+    text = agent_input if isinstance(agent_input, str) else " ".join(agent_input)
+    blocked = not text.startswith("Task:")
+    return GuardrailFunctionOutput(
+        output_info="ERROR: Requests to this agent must begin with 'Task:'" if blocked else "",
+        tripwire_triggered=blocked,
+    )
+
+@output_guardrail(name="RequireResponsePrefix")
+async def require_response_prefix(
+    context: RunContextWrapper, agent: Agent, response_text: str
+) -> GuardrailFunctionOutput:
+    blocked = not response_text.startswith("Response:")
+    return GuardrailFunctionOutput(
+        output_info="ERROR: Responses must start with 'Response:'" if blocked else "",
+        tripwire_triggered=blocked,
+    )
+
+ceo = Agent(name="CEO", instructions="You are the CEO agent.")
+
+worker = Agent(
+    name="Worker",
+    instructions="You are the worker agent.",
+    input_guardrails=[require_task_prefix],
+    output_guardrails=[require_response_prefix],
+    raise_input_guardrail_error=True,
+)
+
+agency = Agency(ceo, communication_flows=[(ceo, worker)])
+```
+</Accordion>
+
+In this example:
+- If the CEO sends a message that does not start with `Task:`, the worker input guardrail triggers.
+- The CEO receives an error and adjusts its message.
+- The worker output guardrail enforces `Response:` in returned messages.
+
+<Note>
+Agent-to-agent messages are always single strings, so input guardrails for inter-agent communication receive a string (not a list).
+</Note>

docs/additional-features/guardrails/overview.mdx

@@ -0,0 +1,27 @@
+---
+title: "Guardrails Overview"
+description: "Screen agent inputs and review outputs with guardrails."
+icon: "shield-halved"
+sidebarTitle: "Overview"
+---
+
+Guardrails are checkpoint functions that keep agent behavior safe and predictable. Use them to validate incoming messages before execution and validate responses before delivery.
+
+## Choose the Right Guardrail
+
+| Type | Runs When | On Failure | Page |
+|------|-----------|------------|------|
+| **Input Guardrails** | Before the agent processes input | Return guidance (non-strict) or raise `InputGuardrailTripwireTriggered` (strict) | [Input Guardrails](/additional-features/guardrails/input-guardrails) |
+| **Output Guardrails** | After the agent drafts output, before delivery | Retry up to `validation_attempts`, then raise `OutputGuardrailTripwireTriggered` | [Output Guardrails](/additional-features/guardrails/output-guardrails) |
+
+## Runnable GitHub Examples
+
+- Input guardrails example: [`examples/guardrails_input.py`](https://github.com/VRSEN/agency-swarm/blob/main/examples/guardrails_input.py)
+- Output guardrails example: [`examples/guardrails_output.py`](https://github.com/VRSEN/agency-swarm/blob/main/examples/guardrails_output.py)
+
+## Best Practices
+
+- Keep each guardrail focused on one responsibility.
+- Write clear `output_info` messages so the model knows how to recover.
+- Use non-strict mode for guidance and strict mode for hard requirements.
+- For tool argument validation (field/model validators), use [Input Validation](/core-framework/tools/custom-tools/validation).

docs/additional-features/mcp-tools-server.mdx

@@ -0,0 +1,156 @@
+---
+title: "MCP Tools Server"
+description: "Serving your tools as MCP (Model Context Protocol) endpoints."
+icon: "server"
+---
+
+Agency Swarm supports serving your tools as production-ready MCP (Model Context Protocol) endpoints.
+This enables AI models to interact with your tools remotely over HTTP, making them accessible to any MCP-compatible client or AI system.
+
+## Setting Up MCP Server
+
+To expose tools as a standalone MCP endpoint, use the `run_mcp()` function from the integrations module.
+This will create an MCP server that will serve provided tools over the streamable HTTP protocol.
+
+### Example: Serving Individual Tools
+
+```python
+from agency_swarm import function_tool, run_mcp
+from pydantic import BaseModel, Field
+
+class InputArgs(BaseModel):
+    input_field: str = Field(..., description="Test input for the tool")
+
+@function_tool
+async def echo_function(args: InputArgs) -> str:
+    """Returns a unique id"""
+    return f"Tool called with input: {args.input_field}"
+
+# Start MCP server with individual tools.
+# This will setup a streamable-http server by default on port 8000
+run_mcp(tools=[echo_function])
+```
+
+### Configuration Options
+
+The `run_mcp()` function accepts several configuration parameters:
+
+```python
+run_mcp(
+    tools=[ExampleTool, TestTool],  # List of Function tools or BaseTools
+    host="0.0.0.0",                 # Host to bind server to
+    port=8000,                      # Port to bind server to
+    app_token_env="APP_TOKEN",      # Environment variable for auth token
+    server_name="mcp-tools-server", # MCP server identifier
+    return_app=False,               # Return app instead of running server
+    transport="streamable-http"     # Preferred mcp protocol to use
+)
+```
+
+### Authentication
+
+Authentication is controlled via environment variables:
+
+```python
+import os
+os.environ["APP_TOKEN"] = "your-secret-token"  # Or set in .env file
+```
+
+If no `APP_TOKEN` is set, **authentication will be disabled** and the server will accept all requests.
+
+---
+
+## MCP Client Usage
+
+<Tabs>
+<Tab title="Local MCP Server">
+
+This example shows how to use a local MCP server with stdio transport:
+
+```python
+import asyncio
+from agents.mcp.server import MCPServerStdio, MCPServerStdioParams
+from agency_swarm import Agency, Agent
+
+# Set up local MCP server using stdio transport
+stdio_server = MCPServerStdio(
+    MCPServerStdioParams(
+        command="python", # or "npx" if available
+        # Path to your MCP server script or npx arguments
+        args=["./path/to/your/mcp_server.py"]
+    ),
+    cache_tools_list=True
+)
+
+# Create agent with local MCP server
+mcp_agent = Agent(
+    name="LocalMCPAgent",
+    mcp_servers=[stdio_server],
+)
+
+agency = Agency(mcp_agent)
+
+async def run_local_example():
+    await stdio_server.connect()
+    response = await agency.get_response("List all mcp tools")
+    print(response.final_output)
+    await stdio_server.cleanup()
+
+if __name__ == "__main__":
+    asyncio.run(run_local_example())
+```
+
+</Tab>
+<Tab title="Hosted MCP Server">
+
+This example shows how to connect to a hosted MCP server over HTTP:
+
+```python
+import os
+import asyncio
+from agency_swarm import Agency, Agent, HostedMCPTool
+
+# Create agent with hosted MCP server
+mcp_agent = Agent(
+    name="HostedMCPAgent",
+    tools=[
+        HostedMCPTool(
+            tool_config={
+                "type": "mcp",
+                "server_label": "mcp-tools-server",
+                # Update with your hosted MCP server URL
+                "server_url": "https://your-server.com/mcp/",
+                "require_approval": "never",
+                "headers": {
+                    "Authorization": (
+                        f"Bearer {os.getenv('APP_TOKEN', 'your-token')}"
+                    )
+                }
+            }
+        ),
+    ],
+)
+
+agency = Agency(mcp_agent)
+
+async def run_hosted_example():
+    # HostedMCPTools do not require manual connection
+    response = await agency.get_response("List all mcp tools")
+    print(response.final_output)
+
+if __name__ == "__main__":
+    asyncio.run(run_hosted_example())
+```
+
+<Note>
+For hosted MCP servers, ensure your server is accessible from the internet.
+You can use tools like ngrok for local development.
+</Note>
+
+</Tab>
+</Tabs>
+
+## See Also
+
+- [Agents SDK MCP guide](https://openai.github.io/openai-agents-python/mcp/)
+- [Agents SDK MCP server reference](https://openai.github.io/openai-agents-python/ref/mcp/server/)

docs/additional-features/observability.mdx

@@ -0,0 +1,181 @@
+---
+title: "Observability"
+description: "Track and analyze your agent performance and behavior by connecting with third party observability tools."
+icon: "eyes"
+---
+
+Agency Swarm supports multiple observability approaches to help you track and analyze your agent's behavior and performance.
+
+## Usage Payload
+
+When usage tracking is enabled, responses include a `usage` object with token counts and cost.
+
+```json
+{
+  "response": "Test response",
+  "new_messages": [],
+  "usage": {
+    "request_count": 1,
+    "cached_tokens": 0,
+    "input_tokens": 10,
+    "output_tokens": 20,
+    "total_tokens": 30,
+    "total_cost": 0.0
+  }
+}
+```
+
+**Fields:**
+
+- `request_count`: Number of model requests
+- `cached_tokens`: Tokens served from cache (if available)
+- `input_tokens`: Tokens sent to the model
+- `output_tokens`: Tokens generated by the model
+- `total_tokens`: Total tokens for the request
+- `total_cost`: Estimated cost (USD)
+- `reasoning_tokens` (optional): Reasoning tokens (if available)
+
+**Where you'll see it:**
+
+- [FastAPI Integration](/additional-features/fastapi-integration): `POST /get_response` returns JSON with `usage`, and the final `event: messages` in `POST /get_response_stream` includes `usage`.
+- [Running an Agency](/core-framework/agencies/running-agency#track-usage-and-cost): use `/cost` in the TUI to see session usage and cost.
+
+## Supported Observability Platforms
+
+Agency Swarm supports three main observability approaches:
+
+<CardGroup cols={3}>
+  <Card title="OpenAI Tracing" icon="chart-line" href="#openai-tracing">
+    Built-in tracing using OpenAI's native tools
+  </Card>
+  <Card title="Langfuse" icon="gauge-high" href="#langfuse-tracing">
+    Advanced tracing and debugging platform
+  </Card>
+  <Card title="AgentOps" icon="database" href="#agentops-tracing">
+    Specialized agent monitoring and analytics
+  </Card>
+</CardGroup>
+
+## Getting Started
+
+Let's walk through setting up each tracing solution. You can use them individually or combine them for monitoring.
+
+<Tabs>
+  <Tab title="OpenAI Tracing">
+    <Steps>
+      <Step title="Basic Setup">
+        OpenAI tracing is built into Agency Swarm and requires no additional packages.
+      </Step>
+      <Step title="Implementation">
+        ```python
+        from agency_swarm import trace
+
+        async def openai_tracing(input_message: str) -> str:
+            agency_instance = create_agency()
+            with trace("OpenAI tracing"):
+                response = await agency_instance.get_response(message=input_message)
+            return response.final_output
+        ```
+      </Step>
+      <Step title="View Traces">
+        After running your code, view your traces at [platform.openai.com/traces](https://platform.openai.com/traces)
+      </Step>
+    </Steps>
+  </Tab>
+
+  <Tab title="Langfuse">
+    <Steps>
+      <Step title="Install Package">
+        ```bash
+        pip install langfuse
+        ```
+      </Step>
+      <Step title="Set Environment Variables">
+        ```bash
+        export LANGFUSE_SECRET_KEY=<your-secret-key>
+        export LANGFUSE_PUBLIC_KEY=<your-public-key>
+        export LANGFUSE_HOST=<your-host>
+        ```
+      </Step>
+      <Step title="Implementation">
+        ```python
+        from langfuse import observe
+
+        @observe()
+        async def langfuse_tracing(input_message: str) -> str:
+            agency_instance = create_agency()
+
+            @observe()
+            async def get_response_wrapper(message: str):
+                return await agency_instance.get_response(message=message)
+
+            response = await get_response_wrapper(input_message)
+            return response.final_output
+        ```
+      </Step>
+      <Step title="View Traces">
+        Access your traces at [cloud.langfuse.com](https://cloud.langfuse.com) and select your project.
+      </Step>
+    </Steps>
+  </Tab>
+
+  <Tab title="AgentOps">
+    <Steps>
+      <Step title="Install Package">
+        ```bash
+        pip install agentops
+        ```
+      </Step>
+      <Step title="Set Environment Variables">
+        ```bash
+        export AGENTOPS_API_KEY=<your-api-key>
+        ```
+      </Step>
+      <Step title="Implementation">
+        ```python
+        import agentops
+
+        async def agentops_tracing(input_message: str) -> str:
+            agentops.init(
+                auto_start_session=True,
+                trace_name="Agentops tracing",
+                tags=["openai", "agentops-example"]
+            )
+            tracer = agentops.start_trace(
+                trace_name="Agentops tracing",
+                tags=["openai", "agentops-example"]
+            )
+
+            agency_instance = create_agency()
+            response = await agency_instance.get_response(message=input_message)
+
+            agentops.end_trace(tracer, end_state="Success")
+            return response.final_output
+        ```
+      </Step>
+      <Step title="View Traces">
+        When you run your code, AgentOps will print a session replay URL in the console that looks like: `https://app.agentops.ai/sessions?trace_id=<your-trace-id>`
+      </Step>
+    </Steps>
+  </Tab>
+</Tabs>
+
+## Implementation Example
+
+For a complete working example that demonstrates all three tracing methods with a multi-agent agency, see [observability.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/observability.py) in the examples directory.
+
+The example shows:
+- How to set up a basic agency with CEO, Developer, and Data Analyst roles
+- Implementation of all three tracing methods (OpenAI, Langfuse, AgentOps)
+- A sample tool for data analysis
+- Error handling and proper tracing setup
+
+You can run the example with:
+```bash
+python examples/observability_demo.py
+```
+
+For more information about each platform's capabilities and configuration options, refer to their respective documentation:
+- [OpenAI Documentation](https://platform.openai.com/docs)
+- [Langfuse Documentation](https://langfuse.com/docs)
+- [AgentOps Documentation](https://docs.agentops.ai)

docs/additional-features/streaming.mdx

@@ -0,0 +1,216 @@
+---
+title: "Streaming"
+description: "Implementing streaming in Agency Swarm."
+icon: "ellipsis"
+---
+
+Streaming enables agents to return outputs immediately, significantly improving user experience. Instead of waiting for the entire response to be generated, the user can see the response being generated in real-time.
+
+## Streaming Responses
+
+In Agency Swarm, streaming is handled through the `get_response_stream` method. The framework returns [StreamEvent](https://openai.github.io/openai-agents-python/ref/stream_events/#agents.stream_events.StreamEvent) objects as they are returned by OpenAI, providing direct access to the underlying streaming events.
+
+```python
+async def stream_response(message: str):
+    """Stream a response and handle events properly."""
+    full_text = ""
+
+    async for event in agency.get_response_stream(message):
+        # Handle streaming events with data
+        if hasattr(event, "data"):
+            data = event.data
+
+            # Only capture actual response text, not tool call arguments
+            if hasattr(data, "delta") and hasattr(data, "type"):
+                if data.type == "response.output_text.delta":
+                    # Stream the actual response text in real-time
+                    delta_text = data.delta
+                    if delta_text:
+                        print(delta_text, end="", flush=True)
+                        full_text += delta_text
+                # Skip tool call deltas (we don't want to show those to users)
+                elif data.type == "response.function_call_arguments.delta":
+                    continue
+
+        # Handle validation errors
+        elif isinstance(event, dict):
+            event_type = event.get("event", event.get("type"))
+            if event_type == "error":
+                print(f"\n❌ Error: {event.get('content', event.get('data', 'Unknown error'))}")
+                break
+
+    print("\n✅ Stream complete")
+    return full_text
+
+# Usage
+await stream_response("I want you to build me a website")
+```
+
+## Streaming from Tools
+
+Tools can inject events into the parent SSE stream while they execute. This is especially useful when a tool runs a sub-agent or a long-running operation and you want the client to receive live progress updates alongside the normal agent output.
+
+### Accessing the Streaming Context
+
+Inside any `BaseTool.run()` method, two properties give you access to the live stream:
+
+| Field | Type | What it is |
+|---|---|---|
+| `self.context.streaming_context` | `StreamingContext \| None` | The queue that feeds the parent stream. `None` when the request is not streaming. |
+| `self.tool_call_id` | `str \| None` | The unique ID of this specific tool invocation. Use it to let clients correlate events with the tool call. |
+
+```python
+streaming_ctx = self.context.streaming_context
+tool_call_id  = self.tool_call_id or ""
+```
+
+`streaming_ctx` is `None` when the request is not streaming, so always guard before calling `put_event`.
+
+Any object passed to `streaming_ctx.put_event(event)` is forwarded into the same stream your client is already consuming. There are three ways to use this, depending on how informative you want the events to be.
+
+### Method 1: Raw values
+
+The simplest option — emit any plain value directly. Useful for quick progress strings during development.
+
+```python
+class MyTool(BaseTool):
+    """Does something and reports progress."""
+
+    async def run(self):
+        streaming_ctx = self.context.streaming_context
+
+        if streaming_ctx:
+            await streaming_ctx.put_event("step 1/3: fetching data…")
+
+        data = await _fetch()
+
+        if streaming_ctx:
+            await streaming_ctx.put_event("step 2/3: processing…")
+
+        result = await _process(data)
+
+        if streaming_ctx:
+            await streaming_ctx.put_event("step 3/3: done.")
+
+        return result
+```
+
+On the consumer side:
+
+```python
+async for event in agency.get_response_stream(message):
+    if isinstance(event, str):
+        print(f"[tool] {event}")
+```
+
+### Method 2: Existing SDK event types
+
+While neither the OpenAI API nor the `agents` SDK contains event types specifically designed for streaming output from tool execution, you can construct a [`RawResponsesStreamEvent`](https://openai.github.io/openai-agents-python/ref/stream_events/#agents.stream_events.RawResponsesStreamEvent) wrapping a `ResponseTextDeltaEvent` directly inside the tool. The internal tracking fields (`item_id`, `content_index`, etc.) just need placeholder values — the consumer's existing delta-handling code treats it identically to a normal LLM text delta.
+
+```python
+from agents import RawResponsesStreamEvent
+from openai.types.responses import ResponseTextDeltaEvent
+from agency_swarm.tools import BaseTool
+from pydantic import Field
+
+
+class MyTool(BaseTool):
+    """Does something and streams progress as text deltas."""
+
+    task: str = Field(..., description="The task to perform")
+
+    async def run(self):
+        streaming_ctx = self.context.streaming_context
+
+        async def emit_delta(text: str) -> None:
+            if streaming_ctx:
+                await streaming_ctx.put_event(
+                    RawResponsesStreamEvent(
+                        data=ResponseTextDeltaEvent(
+                            content_index=0,
+                            output_index=0,
+                            sequence_number=0,
+                            item_id="tool_progress",
+                            logprobs=[],
+                            delta=text,
+                            type="response.output_text.delta",
+                        )
+                    )
+                )
+
+        await emit_delta("Starting…")
+        result = await _perform_task(self.task)
+        await emit_delta(" Done.")
+        return result
+```
+
+On the consumer side, these events are indistinguishable from regular LLM text deltas unless you inspect the `item_id` you set on the event:
+
+```python
+from agents import RawResponsesStreamEvent
+from openai.types.responses import ResponseTextDeltaEvent
+
+async for event in agency.get_response_stream(message):
+    if isinstance(event, RawResponsesStreamEvent) and isinstance(event.data, ResponseTextDeltaEvent):
+        if event.data.item_id == "tool_progress":
+            print(f"[tool] {event.data.delta}", end="", flush=True)
+        else:
+            print(event.data.delta, end="", flush=True)
+```
+
+### Method 3: Custom event model
+
+For the most informative output you can construct your own class that includes structured metadata — status, tool call ID for correlation, error details, etc. No built-in SDK type covers tool execution progress, so this is the recommended approach for production use, but it will require explicit checks on the consumer side to separate these events from standard SDK events.
+
+```python
+from typing import Literal
+from pydantic import BaseModel, Field
+from agency_swarm.tools import BaseTool
+
+
+class ToolProgressEvent(BaseModel):
+    """Streaming progress event emitted by a tool invocation."""
+
+    call_id: str
+    status: Literal["in_progress", "completed", "failed"] = "in_progress"
+    delta: str | None = None
+    error: str | None = None
+
+
+class LongRunningTool(BaseTool):
+    """A tool that reports live progress through the parent stream."""
+
+    task: str = Field(..., description="The task to perform")
+
+    async def run(self):
+        streaming_ctx = self.context.streaming_context
+        tool_call_id = self.tool_call_id or ""
+
+        async def emit(status: str, delta: str | None = None, error: str | None = None) -> None:
+            if streaming_ctx:
+                await streaming_ctx.put_event(
+                    ToolProgressEvent(call_id=tool_call_id, status=status, delta=delta, error=error)
+                )
+
+        await emit("in_progress", delta="Starting…")
+
+        try:
+            result = await _perform_task(self.task)
+            await emit("completed")
+            return result
+        except Exception as exc:
+            await emit("failed", error=str(exc))
+            raise
+```
+
+On the consumer side, filter by type:
+
+```python
+async for event in agency.get_response_stream(message):
+    if isinstance(event, ToolProgressEvent):
+        print(f"[{event.status}] {event.delta or ''}")
+```
+
+<Warning>
+Regardless of the chosen method, events emitted via `put_event()` are only visible to the **client consuming the stream** — the calling agent never sees them. From the agent's perspective, the tool returns only its final `return` value, which is what gets added to the conversation history and passed back to the model.
+</Warning>

docs/additional-features/third-party-models.mdx

@@ -0,0 +1,201 @@
+---
+title: "Third-Party Models"
+description: "Use models from Anthropic, Google, AWS, or self-hosted open-source models via LiteLLM."
+icon: "server"
+---
+
+While OpenAI is generally recommended, there are situations where you might prefer third-party models. Agency Swarm supports proprietary providers (Anthropic, Google, AWS) and self-hosted open-source models (Llama, Mistral, etc.) through LiteLLM integration:
+
+## LiteLLM Integration
+
+Since Agents SDK no longer uses assistants, most of the previously available frameworks became incompatible with it. One of the few frameworks that has been ported for the new SDK is [LiteLLM](https://docs.litellm.ai/docs/response_api), which you can use to connect your agent to various providers (Anthropic, Google Vertex AI, AWS Bedrock, Azure) as well as self-hosted open-source models via Ollama, vLLM, and other local serving solutions.
+
+
+<Tabs>
+<Tab title="Using OpenAI's LiteLLM model">
+<Steps>
+
+<Step title="Install LiteLLM">
+Install LiteLLM to get started with open-source model support:
+
+```bash
+pip install "openai-agents[litellm]"
+```
+</Step>
+
+<Step title="Configure Agency Swarm Agent">
+Create an agent that connects to your LiteLLM proxy:
+
+```python
+import os
+from agency_swarm import Agent
+from agents.extensions.models.litellm_model import LitellmModel
+
+# Requires GOOGLE_API_KEY environment variable set
+gemini_agent = Agent(
+    name="GeminiAgent",
+    instructions="You are a helpful assistant",
+    model="litellm/gemini/gemini-2.0-flash"
+)
+```
+</Step>
+
+<Step title="Create and Run Agency">
+Set up your agency and start using third-party models:
+
+```python
+from agency_swarm import Agency
+
+agency = Agency(gemini_agent)
+
+agency.tui()
+```
+
+The first terminal run downloads the matching terminal app automatically.
+</Step>
+
+</Steps>
+</Tab>
+
+<Tab title="Using proxy server">
+<Steps>
+
+<Step title="Install LiteLLM">
+Install LiteLLM to get started with open-source model support:
+
+```bash
+pip install "litellm[proxy]"
+```
+</Step>
+
+<Step title="Create LiteLLM Configuration">
+Create a `config.yaml` file to configure your models and providers:
+
+```yaml
+model_list:
+  - model_name: gemini-flash
+    litellm_params:
+      model: gemini/gemini-2.0-flash
+      api_key: os.environ/GEMINI_API_KEY # or paste your key directly here
+  - model_name: claude-sonnet
+    litellm_params:
+      model: anthropic/claude-3-5-sonnet-20240620
+      api_key: os.environ/ANTHROPIC_API_KEY
+  - model_name: llama-groq
+    litellm_params:
+      model: groq/llama-3.1-70b-versatile
+      api_key: os.environ/GROQ_API_KEY
+
+general_settings:
+  store_prompts_in_spend_logs: true  # Enable session management
+```
+</Step>
+
+<Step title="Set Environment Variables">
+Add your API keys to your environment variables:
+
+```bash
+export GEMINI_API_KEY="your-gemini-api-key"
+export ANTHROPIC_API_KEY="your-anthropic-api-key"
+export GROQ_API_KEY="your-groq-api-key"
+```
+</Step>
+
+<Step title="Start LiteLLM Proxy Server">
+Launch the LiteLLM proxy server with your configuration:
+
+```bash
+litellm --config /path/to/config.yaml
+
+# Server will start on http://localhost:4000
+```
+</Step>
+
+<Step title="Configure Agency Swarm Agent">
+Create an agent that connects to your LiteLLM proxy:
+
+```python
+import os
+from openai import AsyncOpenAI
+from agency_swarm import Agent, OpenAIChatCompletionsModel
+
+custom_client = AsyncOpenAI(
+    api_key="xxx",  # Any if proxy key wasn't set
+    base_url="http://localhost:4000",
+)
+
+gemini_agent = Agent(
+    name="GeminiAgent",
+    instructions="You are a helpful assistant",
+    model=OpenAIChatCompletionsModel(
+        model="gemini/gemini-2.0-flash",
+        openai_client=custom_client
+    )
+)
+```
+</Step>
+
+<Step title="Create and Run Agency">
+Set up your agency and start using third-party models:
+
+```python
+from agency_swarm import Agency
+
+agency = Agency(gemini_agent)
+
+agency.tui()
+```
+
+The first terminal run downloads the matching terminal app automatically.
+</Step>
+
+</Steps>
+
+</Tab>
+</Tabs>
+
+## Using model-specific tools
+
+Some models, like gemini or claude have their internal tools, which can be attached to an agent by utilizing `extra_body` parameter in agent's `model_settings`:
+
+```python
+import os
+from agency_swarm import Agent
+from agents.extensions.models.litellm_model import LitellmModel
+
+# Requires GOOGLE_API_KEY environment variable set
+gemini_agent = Agent(
+    name="GeminiAgent",
+    instructions="You are a helpful assistant",
+    model="litellm/gemini/gemini-2.0-flash"
+)
+
+# Requires XAI_API_KEY environment variable set
+grok_agent = Agent(
+    name="GrokAgent",
+    instructions="You are a helpful assistant",
+    model="litellm/xai/grok-4-0709"
+)
+```
+
+Here both Grok and Gemini agents will be able to use their native search tools, which are similar to OpenAI's WebSearch() tool. Consider checking out [LiteLLM's documentation](https://docs.litellm.ai/docs) to find a full list of supported tools.
+
+## Limitations
+
+<Warning>
+Be aware of the limitations when using third-party models.
+</Warning>
+
+- **Hosted tools are not supported**: Patched agents are not able to utilize hosted tools, such as WebSearch, FileSearch, CodeInterpreter and others.
+- **Patched and unpatched models should not use handoffs to communicate**: You may use standard OpenAI client and patched agents in a single agency, however using handoff to transfer chat from patched model to unpatched or vice-versa will lead to an error.
+- **Function calling may not be supported by some third-party models**: This limitation prevents the agent from communicating with other agents in the agency. Therefore, it must be positioned at the end of the agency chart and cannot utilize any tools.
+- **RAG is typically limited**: Most open-source implementations have restricted Retrieval-Augmented Generation capabilities. It is recommended to develop a custom tool with your own vector database.
+- **Potential library conflicts**: the Agents SDK is still a fairly new framework which is being actively developed and improved. Due to that, there might be potential conflicts between litellm and openai-agents packages on recent releases.
+
+For Azure OpenAI, see [Azure OpenAI](/additional-features/azure-openai).
+
+## Future Plans
+
+Updates will be provided as new open-source assistant API implementations stabilize.
+
+If you successfully integrate other projects with agency-swarm, please share your experience through an issue or pull request.

docs/analise_docs.py

@@ -0,0 +1,105 @@
+import os
+import re
+
+import pandas as pd
+import textstat
+
+
+def process_inline_code(code):
+    # Replace dot access with whitespace if detected
+    if re.search(r"\w+\.\w+", code):
+        code = code.replace(".", " ")
+    # Replace square brackets with whitespace
+    if "[" in code or "]" in code:
+        code = code.replace("[", " ").replace("]", " ")
+    return code
+
+
+def clean_markdown(text):
+    # Remove code blocks (triple backticks)
+    text = re.sub(r"```.*?```", "", text, flags=re.DOTALL)
+
+    # Process inline code: Replace inline code blocks with their processed plaintext
+    def inline_code_replacer(match):
+        code_content = match.group(1)
+        processed = process_inline_code(code_content)
+        return processed  # Inline code is replaced with its processed content
+
+    text = re.sub(r"`([^`]+)`", inline_code_replacer, text)
+
+    # Replace markdown links with their placeholder value (the text inside the square brackets)
+    text = re.sub(r"\[([^\]]+)\]\([^)]+\)", r"\1", text)
+
+    # Optionally, remove or simplify other markdown formatting:
+    # Remove headers (leading '#' characters) and emphasis markers
+    text = re.sub(r"^#+\s*", "", text, flags=re.MULTILINE)
+    text = re.sub(r"[*_~]", "", text)
+
+    return text
+
+
+def compute_readability(file_path):
+    with open(file_path, encoding="utf-8") as f:
+        content = f.read()
+    # Clean markdown formatting for better readability analysis
+    plain_text = clean_markdown(content)
+
+    scores = {
+        "File": file_path,
+        "Flesch-Kincaid": textstat.flesch_kincaid_grade(plain_text),
+        "SMOG Index": textstat.smog_index(plain_text),
+        "ARI Index": textstat.automated_readability_index(plain_text),
+        "Coleman-Liau": textstat.coleman_liau_index(plain_text),
+    }
+    return scores
+
+
+def analyze_docs(root_directory):
+    results = []
+    for root, _, files in os.walk(root_directory):
+        for file in files:
+            if file.endswith(".mdx") or file.endswith(".md"):
+                file_path = os.path.join(root, file)
+                file_path = file_path.replace("\\", "/")
+                try:
+                    scores = compute_readability(file_path)
+                    results.append(scores)
+                except Exception as e:
+                    print(f"Error processing {file_path}: {e}")
+    return results
+
+
+# Replace 'docs_directory' with the path to your documentation
+docs_directory = r"."
+readability_results = analyze_docs(docs_directory)
+
+# Convert results to a DataFrame for a clean report
+df = pd.DataFrame(readability_results)
+print(df)
+
+# Define the threshold
+threshold = 15
+
+# Filter the DataFrame where any of the readability scores is above the threshold
+filtered_df = df[
+    (df["Flesch-Kincaid"] > threshold)
+    | (df["SMOG Index"] > threshold)
+    | (df["ARI Index"] > threshold)
+    | (df["Coleman-Liau"] > threshold)
+]
+
+# Extract the list of file names
+pages_above_threshold = filtered_df["File"].tolist()
+print("Pages with at least one readability score above", threshold, ":", pages_above_threshold)
+
+
+# Optionally, save the report to CSV for further analysis
+df.to_csv("readability_report.csv", index=False)
+
+"""Explainer of results:
+Each test shows how many years of education a person needs to be able to effectively read through the text.
+Flesch-Kincaid and SMOG Index are popular linguistic benchmarks applicable for most texts
+ARI Index and Coleman-Liau are recommended for technical texts.
+Generally is it considered that the lower the number is the easier the text is to approach.
+When analysing the results just look for outliers.
+"""

docs/contributing/contributing.mdx

@@ -0,0 +1,127 @@
+---
+title: "Contributing to Agency Swarm"
+description: "Learn how to contribute to Agency Swarm"
+icon: "code-fork"
+---
+
+We welcome contributions to Agency Swarm! By contributing, you help improve the framework for everyone. Here's how you can get involved:
+
+## Setting Up Your Development Environment
+
+### Prerequisites
+
+- Python 3.12 or higher
+- Pip
+- Git
+
+### Setup
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/VRSEN/agency-swarm.git
+   cd agency-swarm
+   ```
+2. Create and activate a virtual environment (recommended):
+   ```bash
+   python -m venv .venv
+   source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`
+   ```
+3. Install dependencies including development tools:
+   ```bash
+   pip install -e ".[dev]"
+   ```
+
+4. Install Pre-Commit Hooks:
+   ```bash
+   pip install pre-commit
+   pre-commit install
+   ```
+
+## Running Tests
+
+<Tip>
+  Testing ensures that your contributions work as intended and do not break existing functionality.
+</Tip>
+
+<Steps titleSize="h3">
+
+<Step title="Install Test Dependencies" icon="download" iconType="solid">
+Ensure all test dependencies are installed.
+
+```bash
+pip install -e ".[dev]"
+```
+
+</Step>
+
+<Step title="Run Tests" icon="play" iconType="solid">
+Run the test suite using Pytest.
+
+```bash
+pytest
+```
+
+</Step>
+
+<Step title="Check Test Coverage" icon="chart-bar" iconType="solid">
+Check the test coverage to ensure comprehensive testing.
+
+```bash
+pytest --cov=agency_swarm tests/
+```
+
+</Step>
+
+</Steps>
+
+## Submitting Changes
+
+<AccordionGroup>
+
+  <Accordion title="Create Branch" icon="code-branch" iconType="solid">
+    Create a branch for your work:
+    ```bash
+    git checkout -b feature/your-feature-name
+    ```
+  </Accordion>
+
+  <Accordion title="Commit Changes" icon="git" iconType="solid">
+    Commit your updates:
+    ```bash
+    git add .
+    git commit -m "Add [feature]: Description"
+    ```
+  </Accordion>
+
+  <Accordion title="Push Branch" icon="code-fork" iconType="solid">
+    Push your branch:
+    ```bash
+    git push origin feature/your-feature-name
+    ```
+  </Accordion>
+
+  <Accordion title="Open PR" icon="paper-plane" iconType="solid">
+    Open a pull request on GitHub:
+    ```markdown
+    - Provide a concise title and description.
+    - Reference related issues.
+    ```
+  </Accordion>
+
+</AccordionGroup>
+
+### Code Style and Linting
+
+This project uses `ruff` for linting and code formatting. Configuration for this tool can be found in `pyproject.toml`.
+
+Before committing your changes, please check and fix linting errors:
+
+```bash
+ruff check . --fix
+```
+
+It's recommended to install these tools in your development environment. If you followed the setup instructions, they should already be installed via:
+
+```bash
+pip install -e ".[dev]"
+```

docs/core-framework/agencies/agent-swarm-cli.mdx

@@ -0,0 +1,127 @@
+---
+title: "Agent Swarm TUI"
+description: "Start the terminal UI with the main npx launcher, then expand optional sections only if you need them."
+icon: "terminal"
+---
+
+Agent Swarm TUI is the terminal UI for Agency Swarm.
+
+Use it when you want to build or test your Agency Swarm project in the terminal.
+
+## Start the TUI
+
+For most users, the right way to start is:
+
+```bash
+npx @vrsen/agentswarm
+```
+
+This is the main launch path. It handles first-run setup, then connects the terminal UI to your Agency Swarm server.
+
+Run it from your project root. If you are starting fresh, run it in a new empty folder.
+
+You do not need to install the TUI globally first.
+
+![Agent Swarm TUI startup screen](/images/agent-swarm-cli-preview.png)
+
+## Before You Start
+
+Make sure you have:
+
+- Node.js installed so `npx` is available
+- Python 3.12 or newer available for Agency Swarm projects
+- a model provider credential if you want to send prompts right away, or you can add it later with `/auth`
+- an existing agency project, or a starting point from [From Scratch](/welcome/getting-started/from-scratch) or the [Starter Template](/welcome/getting-started/starter-template)
+
+## What Happens on First Launch
+
+On first launch, you will usually see this flow:
+
+<Steps>
+  <Step title="Start the launcher">
+    Start with `npx @vrsen/agentswarm`.
+  </Step>
+  <Step title="Point the launcher at an agency">
+    The launcher can reuse the current Agency Swarm project, create a starter project, or connect to an agency that is already running.
+  </Step>
+  <Step title="Set up the project environment">
+    The launcher checks for a project `.venv`. If it needs to create one, it asks first and then installs the project dependencies before opening the TUI.
+  </Step>
+  <Step title="Open the TUI and add auth if needed">
+    The TUI opens connected to your agency. If you do not already have a usable model provider configured, use `/auth`.
+  </Step>
+</Steps>
+
+This is the path we recommend for onboarding, videos, and first-time users.
+
+## What You Can Do in the TUI
+
+Once the TUI is running, you get:
+
+- a keyboard-first terminal workflow
+- session history, export, undo, redo, and `/compact`
+- `/agents` to switch between top-level agents
+- `@AgentName` mentions to route a prompt to a specific top-level agent
+- `@` file and resource references to attach local or MCP context in the same prompt flow
+- `Tab` autocomplete for both agent mentions and file and resource references
+- direct access to local project files for prompt context
+
+![Agent Swarm TUI agent picker](/images/agent-swarm-cli-agent-selection.png)
+
+## Optional Paths
+
+If this is your first run, you can ignore everything below.
+
+<Accordion title="Connect to a running agency (optional)" defaultOpen={false}>
+Use the same `npx @vrsen/agentswarm` command, then choose **Connect to a running agency** during onboarding.
+
+This is the optional `/connect` path.
+
+The launcher asks for:
+
+1. the Agency Swarm base URL
+2. whether the server needs a bearer token
+3. the agency id, if automatic discovery does not already find it
+
+Use it when:
+
+- a local Agency Swarm server is already running
+- you want to connect to a remote Agency Swarm server
+- the server is protected and needs a bearer token
+
+Current limitations for this path:
+
+- `/models` does not switch the models configured inside your Agency Swarm backend yet
+- local file tools are not available; if you want the TUI to work directly on project files, start with `npx @vrsen/agentswarm` from that project directory instead
+
+Use your Python config to choose backend models and providers.
+</Accordion>
+
+<Accordion title="Alternative: Launch from Python with agency.tui()" defaultOpen={false}>
+If your project already launches from Python, `agency.tui()` still works as the secondary entrypoint.
+
+```python
+agency.tui()
+```
+
+Then start your project the usual way:
+
+```bash
+python agency.py
+```
+
+This path stays bound to the exact `Agency` instance you passed in Python. It starts the local bridge for that agency, then opens the TUI connected to it.
+
+Use it when your team already starts the project from Python and you want a quick TUI test path without switching directories or changing entrypoints.
+</Accordion>
+
+`tui(show_reasoning=False)` is not supported in the new TUI yet.
+
+## Related Pages
+
+- [Installation](/welcome/installation)
+- [From Scratch](/welcome/getting-started/from-scratch)
+- [Third-Party Models](/additional-features/third-party-models)
+- [Running an Agency](/core-framework/agencies/running-agency)
+- [FastAPI Integration](/additional-features/fastapi-integration)
+- [API Reference](/references/api)

docs/core-framework/agencies/communication-flows.mdx

@@ -0,0 +1,129 @@
+---
+title: "Communication Flows"
+description: "Understanding communication flows in Agency Swarm."
+icon: "comments"
+---
+
+<Note>
+Always start with one agent. Never build two agents simultaneously unless you know exactly what you're doing. The more agents you have, the harder it becomes to train them on specific tasks.
+</Note>
+
+## Orchestration Patterns
+
+Agency Swarm supports flexible orchestration patterns. Unlike all other frameworks, communication flows in Agency Swarm are **uniform**, meaning they can be defined in any way you want.
+
+| Pattern | Description | Reliability | Autonomy | Costs | When to Use |
+|---------|-------------|-------------|----------|-------|-------------|
+| **Handoff** | Control transfers completely to another agent who continues the conversation | Very High | Low | Lower | Sequential workflows where each step requires tight feedback from the user |
+| **Orchestrator-Worker** | One agent assigns tasks to multiple agents and compiles their responses | Lower (mitigated with guardrails) | Very High | Higher | Complex multi-step tasks with independent not-very-high stakes steps |
+
+_Scroll table to the right to see the full description of each pattern._
+
+**Examples**:
+
+- **Handoff**: Creative script writing with planner and script writer agents - requires tight user feedback at each stage to refine the story direction
+- **Orchestrator-Worker**: News aggregation and research from various sources - quality of individual sources isn't critical, main agent filters and compiles them
+
+
+## Handoff Pattern
+
+Control transfers completely to another agent who takes over the interaction. The receiving agent gets full conversation history and continues from there.
+
+```python
+from agency_swarm import Agent
+from agency_swarm import Handoff
+
+# Triage agent routes to specialists
+triage_agent = Agent(
+    name="TriageAgent",
+    instructions="Assess customer inquiries and route to appropriate specialist",
+)
+
+billing_specialist = Agent(
+    name="BillingSpecialist",
+    description="Handles billing inquiries, payment issues, and invoice questions",
+    instructions="Resolve customer billing issues with full context from previous conversation",
+)
+
+technical_specialist = Agent(
+    name="TechnicalSpecialist",
+    description="Handles technical support and troubleshooting",
+    instructions="Provide technical support with full conversation history",
+)
+
+agency = Agency(
+    triage_agent,
+    communication_flows=[
+        (triage_agent, billing_specialist, Handoff),      # Handoff to billing
+        (triage_agent, technical_specialist, Handoff),    # Handoff to technical
+    ]
+)
+```
+
+The TriageAgent transfers control completely to the appropriate specialist, who receives full conversation history and continues the interaction. Control does not return to TriageAgent.
+
+## Orchestrator-Worker Pattern
+
+One agent assigns tasks to multiple other agents and compiles their responses. Agents use other agents as specialized tools through the `SendMessage` mechanism. Control always returns to the orchestrator after each delegation.
+
+```python
+# Portfolio Manager orchestrates investment research
+portfolio_manager = Agent(
+    name="PortfolioManager",
+    instructions="Orchestrate investment research by gathering data, delegating analysis, and compiling recommendations",
+    tools=[fetch_market_data],
+)
+
+risk_analyst = Agent(
+    name="RiskAnalyst",
+    instructions="Specialize in investment risk analysis",
+    tools=[analyze_risk_factors],
+    output_type=RiskAssessment,  # Structured output
+)
+
+report_generator = Agent(
+    name="ReportGenerator",
+    instructions="Generate professional investment reports",
+    tools=[create_report],
+)
+
+agency = Agency(
+    portfolio_manager,  # Entry point and orchestrator
+    communication_flows=[
+        (portfolio_manager, risk_analyst),     # Can request risk analysis
+        (portfolio_manager, report_generator), # Can request report generation
+    ]
+)
+```
+
+The Portfolio Manager delegates to specialists, receives their structured responses, and compiles them into a final investment decision.
+
+## Understanding Communication Flows
+
+Communication flows are defined using tuples in the `communication_flows` parameter:
+
+```python
+from agency_swarm import Agency
+from agency_swarm import Handoff
+
+agency = Agency(
+    ceo, dev,  # Entry points - agents that can communicate with users
+    communication_flows=[
+        (ceo, dev, Handoff),   # CEO can transfer the user to the developer
+        (ceo, dev), # CEO can assign tasks to developer
+        (dev, va) # developer can assign tasks to virtual assistant
+    ]
+)
+```
+
+Each tuple `(sender, receiver)`, `(sender > receiver)`, or `(receiver < sender)` defines a directional communication path. Entry points are agents that can communicate with users.
+
+In the example above, the CEO can transfer the user to the Developer and the developer will proceed to interact with the user directly. 
+
+At the same time, the CEO can assign tasks to both Developer and Virtual Assistant, so they will run in parallel in different threads and come back with their results to the CEO.
+
+## Under the Hood
+
+Agency Swarm uses a `SendMessage` tool for inter-agent communication. Defining communication flows adds recipients to this tool.
+
+For advanced customization, see [Custom Communication Flows](/additional-features/custom-communication-flows/overview).

docs/core-framework/agencies/overview.mdx

@@ -0,0 +1,89 @@
+---
+title: "Overview"
+description: "Understanding agencies in Agency Swarm."
+icon: "globe"
+---
+
+Agency in Agency Swarm is a collection of agents that can collaborate with one another.
+
+## Benefits of Using an Agency
+
+Utilizing an Agency consisting of multiple agents offers several benefits:
+
+<CardGroup cols={3}>
+<Card title="Fewer Hallucinations" icon="bug" iconType="solid">
+  Agents within an agency can supervise each other, reducing mistakes and handling unexpected scenarios more effectively.
+</Card>
+
+<Card title="Complex Tasks" icon="diagram-project" iconType="solid">
+  Adding more agents allows for longer sequences of actions, enabling the completion of more complex tasks before delivering results to the user.
+</Card>
+
+<Card title="Scalability" icon="arrow-up-right-dots" iconType="solid">
+  Agencies allow you to scale your solutions seamlessly by adding more agents, as the complexity of your system grows.
+</Card>
+</CardGroup>
+
+<Tip>
+  Start with a minimal number of agents. Fine-tune them to ensure they function correctly before adding more.
+  Introducing too many agents initially can make debugging and understanding interactions challenging.
+</Tip>
+
+In the latest version, the Agency class orchestrates a collection of `Agent` instances based on a defined structure. It provides enhanced thread management, persistence hooks, and improved communication patterns between agents.
+
+## Agency Parameters
+
+Overview of parameters in the new `Agency` class:
+
+| Name | Parameter | Description |
+|------|-----------|-------------|
+| Entry Points | `*entry_points_args` | Positional arguments representing Agent instances that serve as entry points for external interaction. These agents can be directly messaged by users. |
+| Communication Flows *(optional)* | `communication_flows` | List of (sender, receiver) tuples defining allowed agent-to-agent message paths. Example: `[(ceo, dev), (ceo, va)]`. Default: `None` |
+| Name *(optional)* | `name` | A name for the agency instance. Default: `None` |
+| Shared Instructions *(optional)* | `shared_instructions` | Instructions prepended to all agents' system prompts in a string format or a path to markdown file. Default: `None` |
+| Shared Tools *(optional)* | `shared_tools` | List of tool instances or BaseTool classes to add to all agents. Default: `None` |
+| Shared Tools Folder *(optional)* | `shared_tools_folder` | Path to a folder containing tool files to load and share with all agents. Default: `None` |
+| Shared Files Folder *(optional)* | `shared_files_folder` | Path to a folder of files to upload and share with all agents via a common vector store. Default: `None` |
+| Shared MCP Servers *(optional)* | `shared_mcp_servers` | List of MCP server instances to attach to all agents. Default: `None` |
+| Send Message Tool Class *(optional)* | `send_message_tool_class` | Fallback SendMessage tool class when a `communication_flows` entry does not specify its own tool. Prefer configuring SendMessage variants directly through `communication_flows`. Default: `None` |
+| Load Threads Callback *(optional)* | `load_threads_callback` | A callable to load conversation threads for persistence. Default: `None` |
+| Save Threads Callback *(optional)* | `save_threads_callback` | A callable to save conversation threads for persistence. Default: `None` |
+| User Context *(optional)* | `user_context` | Initial shared context accessible to all agents during runs. Default: `None` |
+
+## Example
+
+Quick example of how to create an agency with 3 agents using the new structure:
+
+```python
+from datetime import datetime
+from agency_swarm import Agency, function_tool
+from .ceo import CEO
+from .developer import Developer
+from .virtual_assistant import VirtualAssistant
+
+ceo = CEO()
+dev = Developer()
+va = VirtualAssistant()
+
+@function_tool
+def get_current_time() -> str:
+    """Get the current time."""
+    return datetime.now().isoformat()
+
+# New structure: entry points as positional args, communication flows as keyword arg
+agency = Agency(
+    ceo, dev,  # Entry points - these agents can interact with users
+    communication_flows=[
+        (ceo, dev),  # CEO can initiate communication with Developer
+        (ceo, va),   # CEO can initiate communication with Virtual Assistant
+        (dev, va)    # Developer can initiate communication with Virtual Assistant
+    ],
+    shared_instructions="./shared_instructions.md",
+    shared_tools=[get_current_time],  # Available to all agents
+    user_context={"project_type": "web_application"}
+)
+```
+
+## Next Steps
+
+Make sure to learn more about [Communication Flows](/core-framework/agencies/communication-flows) and [Running an Agency](/core-framework/agencies/running-agency).

docs/core-framework/agencies/running-agency.mdx

@@ -0,0 +1,119 @@
+---
+title: "Running an Agency"
+description: "How to run an Agency."
+icon: "rocket"
+---
+
+When it comes to running your agency, Agency Swarm provides 3 main methods:
+
+1. **CopilotKit/AG-UI Interface**: The most modern and recommended way to get started.
+2. **Get Response**: For backend or custom integrations.
+3. **Terminal Version**: Best for quick debugging and testing.
+
+## Pre-requisites for CopilotKit/AG-UI Demo
+
+To use the CopilotKit/AG-UI demo (`copilot_demo()`), make sure you have the following installed:
+
+- **Node.js** (v18 or newer recommended): [Download Node.js](https://nodejs.org/)
+- **npm** (comes with Node.js)
+
+If these requirements are not met, the demo will not start and you will see an error message.
+
+## CopilotKit/AG-UI Interface
+
+To open a CopilotKit interface, use the `copilot_demo` method:
+
+```python
+agency.copilot_demo()
+```
+
+This will launch both the backend and a Next.js frontend. Simply follow the `localhost` link from the terminal to start using your agency in a chat-based UI.
+
+## Get Response
+
+To get a response from your agency directly in code, use the async `get_response` method:
+
+```python
+import asyncio
+
+async def main():
+    result = await agency.get_response("I want you to build me a website")
+    print(result.final_output)
+
+asyncio.run(main())
+```
+
+**With additional parameters:**
+
+```python
+async def main():
+    result = await agency.get_response(
+        message="I want you to build me a website",
+        additional_instructions="This is an additional instruction for the task.",
+        recipient_agent=dev  # Optional: specify which agent to send to
+    )
+    print(result.final_output)
+
+asyncio.run(main())
+```
+
+**Synchronous version:**
+
+```python
+result = agency.get_response_sync(
+    message="I want you to build me a website",
+    additional_instructions="This is an additional instruction for the task.",
+    recipient_agent=dev  # Optional: specify which agent to send to
+)
+print(result.final_output)
+```
+
+**Parameters**:
+
+- `message`: The message to send to the agency.
+- `additional_instructions` (optional): Additional instructions that will be appended at the end of instructions for the recipient agent.
+- `recipient_agent` (optional): The agent to which the message should be sent.
+
+## Track Usage and Cost
+
+<Tip>
+Use the `/cost` command in the TUI to see the current session usage and cost.
+</Tip>
+
+![TUI `/cost` output showing session usage and cost](/images/cost.png)
+
+To understand what's inside the `usage` object, see [Observability](/additional-features/observability#usage-payload).
+
+If you're running your agency as an HTTP API, see [Serving Agencies as APIs](/additional-features/fastapi-integration).
+
+## Terminal UI
+
+The recommended terminal launch path is:
+
+```bash
+npx @vrsen/agentswarm
+```
+
+Run it from your project root when you want the launcher to handle first-run setup and open the terminal UI for you.
+
+This path lets the launcher detect the agency from your project and open the TUI connected to it. Use it when you want the easiest setup path.
+
+For the full launch flow, first-run auth, and the optional terminal launch paths, see [Agent Swarm TUI](/core-framework/agencies/agent-swarm-cli).
+
+<Note>
+If you already launch from Python, `agency.tui()` is still supported:
+
+```python
+agency.tui()
+```
+
+Use `agency.tui(reload=False)` if you want to turn off hot reload on file changes.
+
+This Python path stays bound to the `Agency` instance you launch from code by starting the local bridge automatically.
+</Note>
+
+<Tip>
+When using the terminal to run the agency, you can send messages directly to any top-level agent by using the "mentions" feature. To do this, start your message with the agent's name preceded by an @ symbol (for example, `@Developer I want you to build me a website`). This directs your message to the specified agent instead of the CEO. You can also press the tab key to autocomplete the agent's name.
+</Tip>
+
+`tui(show_reasoning=False)` is not supported in the new TUI yet.

docs/core-framework/agencies/visualization.mdx

@@ -0,0 +1,143 @@
+---
+title: "Agency Visualization"
+description: "Create interactive HTML visualizations and get ReactFlow-compatible data"
+icon: "chart-network"
+---
+
+Agency Swarm provides two visualization methods:
+
+1. **`visualize()`** - Creates interactive HTML files
+2. **`get_agency_graph()`** - Returns ReactFlow-compatible JSON
+
+<Tabs>
+<Tab title="HTML Visualization">
+
+## `visualize()`
+
+Creates a self-contained HTML file with interactive agency visualization.
+
+```python
+def visualize(
+    self,
+    output_file: str = "agency_visualization.html",
+    include_tools: bool = True,
+    open_browser: bool = True
+) -> str
+```
+
+### Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `output_file` | `str` | `"agency_visualization.html"` | Path to save HTML file |
+| `include_tools` | `bool` | `True` | Whether to include agent tools |
+| `open_browser` | `bool` | `True` | Whether to open in browser |
+
+### Example
+
+```python
+from agency_swarm import Agency, Agent, function_tool
+
+@function_tool
+def analyze_data(data: str) -> str:
+    """Analyze data"""
+    return f"Analysis: {data}"
+
+analyst = Agent(
+    name="Analyst",
+    instructions="You analyze data.",
+    tools=[analyze_data]
+)
+
+manager = Agent(
+    name="Manager",
+    instructions="You coordinate work."
+)
+
+agency = Agency(
+    manager,
+    communication_flows=[(manager, analyst)],
+    name="Analysis Agency"
+)
+
+# Create visualization
+html_file = agency.visualize()
+print(f"Saved to: {html_file}")
+```
+
+</Tab>
+<Tab title="ReactFlow Integration">
+
+## `get_agency_graph()`
+
+Returns ReactFlow-compatible JSON data for custom frontend integration.
+
+```python
+def get_agency_graph(
+    self,
+    include_tools: bool = True
+) -> dict[str, Any]
+```
+
+### Returns
+
+```python
+{
+    "nodes": [
+        {
+            "id": "Manager",
+            "type": "agent",
+            "position": {"x": 100, "y": 50},
+            "data": {
+                "label": "Manager",
+                "description": "Agent description",
+                "isEntryPoint": True,
+                "toolCount": 0
+            }
+        }
+    ],
+    "edges": [
+        {
+            "id": "Manager->Analyst",
+            "source": "Manager",
+            "target": "Analyst",
+            "type": "communication"
+        }
+    ]
+}
+```
+
+### Node Types
+
+- **Agent nodes**: `type: "agent"` with agent metadata
+- **Tool nodes**: `type: "tool"` with parent agent reference
+
+### Edge Types
+
+- **Communication**: `type: "communication"` between agents
+- **Ownership**: `type: "owns"` from agent to tool
+
+## Frontend Integration
+
+Expose `get_agency_graph()` in your API, then use the JSON directly in React:
+
+```tsx
+import ReactFlow from 'reactflow';
+
+const agencyData = await fetch('/your-graph-endpoint').then(r => r.json());
+
+function AgencyVisualization() {
+  return (
+    <div style={{ height: '600px' }}>
+      <ReactFlow
+        nodes={agencyData.nodes}
+        edges={agencyData.edges}
+        fitView
+      />
+    </div>
+  );
+}
+```
+
+</Tab>
+</Tabs>

docs/core-framework/agents/advanced-configuration.mdx

@@ -0,0 +1,103 @@
+---
+title: "Advanced Configuration"
+description: "Learn advanced configuration options for your agents in Agency Swarm."
+icon: "gears"
+---
+
+
+All parameters inside the `Agent` class follow the same structure as the OpenAI Agents SDK [`Agent`](https://openai.github.io/openai-agents-python/ref/agent/#agents.agent.Agent). However, there are a few advanced parameters that require more explanation.
+
+### Parallel Tool Calls
+
+Controls whether tools execute in parallel or sequentially for a given agent.
+
+```python
+from agency_swarm import Agent, ModelSettings
+
+agent = Agent(
+    name="MyAgent",
+    instructions="...",
+    model_settings=ModelSettings(parallel_tool_calls=False),
+)
+```
+
+To force sequential execution for a specific tool regardless of that setting, set `one_call_at_a_time = True` in the tool’s `ToolConfig`. See [Advanced Tool Configuration](/core-framework/tools/custom-tools/configuration).
+
+### File Search
+
+If your `files_folder` ends with `_vs_<vector_store_id>`, Agency Swarm automatically associates files with that Vector Store and adds `FileSearchTool` to the Agent. The `include_search_results` behavior can be toggled via the Agent’s `include_search_results` flag.
+
+### Web Search Sources
+
+```python
+from agency_swarm import Agent, WebSearchTool
+
+agent = Agent(
+    name="Researcher",
+    instructions="Search the web and summarize findings.",
+    tools=[WebSearchTool()],
+    include_web_search_sources=True,  # default
+)
+```
+
+With `include_web_search_sources=True` (default), `WebSearchTool` calls include source URLs.
+Set `include_web_search_sources=False` to skip this.
+
+### Conversation starters cache
+
+Conversation starters are the suggested prompts you see in the chat UI.
+When enabled, cache can instantly replay the first reply without calling the LLM.
+
+```python
+from agency_swarm import Agent
+
+agent = Agent(
+    name="SupportAgent",
+    instructions="You are helpful.",
+    model="gpt-5.4-mini",
+    conversation_starters=["Support: I need help with billing"],
+    cache_conversation_starters=True,
+)
+```
+
+In this example:
+- The UI shows the starter prompt “Support: I need help with billing”.
+- The FastAPI `/get_metadata` response exposes starters as `conversationStarters`.
+- With `cache_conversation_starters=True`, the first plain-text user message can replay a saved reply when it exactly matches a configured starter.
+<Info>
+Streaming the cached reply includes events for text, tool calls, reasoning, and handoffs.
+</Info>
+
+If you change key agent settings (like instructions, tools, or model), the cache for first-turn responses is rebuilt.
+Per-run overrides like `additional_instructions`, `context_override`, or `hooks_override` skip replay and call the LLM.
+
+<Note>
+Cache files live under `AGENCY_SWARM_CHATS_DIR` (defaults to `.agency_swarm`) in `starter_cache/`.
+In production, point `AGENCY_SWARM_CHATS_DIR` at persistent storage to keep instant replies across restarts.
+</Note>
+
+See also: [Agent Overview](/core-framework/agents/overview), [FastAPI Integration](/additional-features/fastapi-integration).
+
+### Output Validation
+
+Use `output_guardrails` on the `Agent` to validate outputs. See the detailed guide: [Guardrails](/additional-features/guardrails/overview).
+
+### Few‑Shot Examples
+
+You can include few‑shot examples in `instructions` as plain text or pass message history to `get_response` / `get_response_stream`.
+
+```python
+from agency_swarm import Agent
+
+agent = Agent(name="MyAgent", instructions="You are a helpful assistant.")
+
+examples = [
+    {"role": "user", "content": "Hi!"},
+    {"role": "assistant", "content": "Hello!"},
+]
+new_message = {"role": "user", "content": "Can you help me write a short summary?"}
+
+response = await agent.get_response(examples + [new_message])
+```
+
+See also: [Few‑Shot Examples](/additional-features/few-shot-examples).

docs/core-framework/agents/built-in-tools.mdx

@@ -0,0 +1,54 @@
+---
+title: "Built-in Tools"
+description: "Learn how to use built-in tools in Agency Swarm."
+icon: "wrench"
+---
+In the latest version, Agency Swarm leverages tools from the [Agents SDK](https://openai.github.io/openai-agents-python/ref/tool/). This provides access to a comprehensive set of production-ready tools maintained by OpenAI.
+
+## Available Tools
+
+The agents SDK provides the following built-in tools:
+
+### Hosted Tools
+
+- **`WebSearchTool`** - Lets an agent search the web
+- **`FileSearchTool`** - Allows retrieving information from your OpenAI Vector Stores
+- **`ComputerTool`** - Allows automating computer use tasks
+- **`CodeInterpreterTool`** - Lets the LLM execute code in a sandboxed environment
+- **`ImageGenerationTool`** - Generates images from a prompt
+- **`LocalShellTool`** - Runs shell commands on your machine
+
+### Function Tools
+
+- **`FunctionTool`** - Custom function-based tools using the `@function_tool` decorator
+
+### MCP (Model Context Protocol) Tools
+
+- **`HostedMCPTool`** - Exposes a remote MCP server's tools to the model
+
+**When to use each tool:**
+
+- **Web Search**: Real-time information retrieval, current events, up-to-date data
+- **File Search**: Enriching agent knowledge, reducing hallucinations, querying documents
+- **Computer Tool**: Automating computer use tasks, UI interactions, testing applications
+- **Code Interpreter**: Data analysis, calculations, executing code in a sandboxed environment
+- **Image Generation**: Creating visual content, illustrations, design assets from prompts
+- **Local Shell**: System administration, file operations, running shell commands
+- **Function Tool**: Creating custom tools with specific business logic using Python functions
+- **Hosted MCP Tool**: Accessing tools from remote Model Context Protocol servers
+
+### WebSearchTool Sources (all checked URLs)
+
+```python
+from agency_swarm import Agent, WebSearchTool
+
+agent = Agent(
+    name="ResearchAgent",
+    instructions="Search the web and summarize the best sources.",
+    tools=[WebSearchTool()],
+)
+```
+
+Use `include_web_search_sources=False` if you do not want source URLs in web-search tool calls.
+
+For detailed documentation and additional configuration options, refer to the [agents SDK tool documentation](https://openai.github.io/openai-agents-python/ref/tool/).

docs/core-framework/agents/overview.mdx

@@ -0,0 +1,120 @@
+---
+title: "Overview"
+description: "Understanding Agents in Agency Swarm."
+icon: "globe"
+---
+
+Agents are the core building blocks of the Agency Swarm framework. Each agent is specialized for a specific role and is designed to perform a specific set of processes within an agency.
+
+## Key Characteristics of Agents
+
+<CardGroup cols={3}>
+  <Card
+    title="Autonomous"
+    icon="robot"
+  >
+    Agents can decide the next best action to achieve a goal autonomously within the guardrails.
+  </Card>
+
+  <Card
+    title="Perceptual"
+    icon="eye"
+  >
+    Agents sense the environment, interpret observations, and self-correct based on feedback.
+  </Card>
+
+  <Card
+    title="Proactive"
+    icon="lightbulb"
+  >
+    Agents can take initiative (monitor, plan, act) and surprise you with the results, or escalate when needed.
+  </Card>
+</CardGroup>
+
+## Defining AI agents
+
+<Callout type="info" icon="robot" title="What is an AI Agent?">
+**An AI agent is an autonomous, goal-driven system that perceives its environment, dynamically uses tools and APIs to take actions, adapts proactively within guardrails, and can collaborate with other agents or humans.**
+</Callout>
+
+Now, let's breakdown this definition:
+
+- **Autonomous** - Agents define their own execution flow independently without hardcoded logic, unlike traditional workflows
+- **Goal-driven** - Agents are focused on outcomes, rather than on invididual steps
+- **Perceives environment** - Agents observe the real-world and use the feedback to validate its own actions (e.g., a coding agent testing its code)
+- **Dynamic tool use** - Agents generate value through actions rather than just responses (most critical characteristic)
+- **Adapts within guardrails** - Agents balance autonomy with safety constraints for enterprise reliability
+- **Collaboration** - Agents can work seamlessly with other agents or humans in multi-agent systems
+
+## Agent Parameters
+
+In agency swarm, to create an agent, you need to instantiate the `Agent` class. 
+
+<Tabs>
+  <Tab title="Core Parameters">
+| Name | Parameter | Description |
+|------|-----------|-------------|
+| Name *(required)* | `name` | The name of the agent. |
+| Instructions *(optional)* | `instructions` | The instructions for the agent. Will be used as the "system prompt" when this agent is invoked. Can be a string or a function that dynamically generates instructions. Default: `None` |
+| Description *(optional)* | `description` | A description of the agent's role or purpose, used to convey agent's role to other agents. Default: `None` |
+| Model *(optional)* | `model` | The model implementation to use when invoking the LLM. If not provided, uses agents SDK default model. Current default model can be [found here](https://openai.github.io/openai-agents-python/models). Default: `None` |
+| Model Settings *(optional)* | `model_settings` | Configures model-specific tuning parameters (e.g. temperature, top_p). See [ModelSettings documentation](https://openai.github.io/openai-agents-python/ref/model_settings/) for details. Default: SDK defaults with Agency Swarm applying `truncation="auto"` when unset. |
+| Tools *(optional)* | `tools` | A list of tools that the agent can use. Default: `[]` |
+| Tools Folder *(optional)* | `tools_folder` | Path to a directory containing tool definitions. Tools are automatically discovered and loaded from this directory. Supports both BaseTool subclasses and modern FunctionTool instances. Default: `None` |
+| Files Folder *(optional)* | `files_folder` | Path to a local folder for managing files associated with this agent. If the folder name follows the pattern `*_vs_<vector_store_id>`, files uploaded via `upload_file` will also be added to the specified OpenAI Vector Store, and a `FileSearchTool` will be automatically added. Default: `None` |
+| MCP Servers *(optional)* | `mcp_servers` | A list of Model Context Protocol servers that the agent can use. Every time the agent runs, it will include tools from these servers in the list of available tools. Default: `[]` |
+| Input Guardrails *(optional)* | `input_guardrails` | A list of checks that run in parallel to the agent's execution, before generating a response. Default: `[]` |
+| Output Guardrails *(optional)* | `output_guardrails` | A list of checks that run on the final output of the agent, after generating a response. Default: `[]` |
+| Output Type *(optional)* | `output_type` | The type of the output object. If not provided, the output will be `str`. In most cases, you should pass a regular Python type (e.g. a dataclass, Pydantic model, TypedDict, etc). Default: `None` |
+
+  </Tab>
+  <Tab title="Additional Parameters">
+| Name | Parameter | Description |
+|------|-----------|-------------|
+| MCP Config *(optional)* | `mcp_config` | Configuration for MCP servers. Default: `MCPConfig()` |
+| API headers *(optional)*<br/>API params *(optional)*| `api_headers`<br/><br/>`api_params` | Additional parameters to include into tools converted from OpenAPI schemas. Default: `None` |
+| Schemas Folder *(optional)* | `schemas_folder` | Path to a directory containing openapi schema files in .json format. Schemas are automatically converted into FunctionTools. Default: `None` |
+| Validation Attempts *(optional)* | `validation_attempts` | Number of retries when an output guardrail trips. Default: `1` |
+| Raise Input Guardrail Error *(optional)* | `raise_input_guardrail_error` | If set to `True`, input guardrail errors raise an exception. If set to `False`, the guardrail message is returned as the agent's response. Default: `False` |
+| Handoff Reminder *(optional)* | `handoff_reminder` | Replaces the default handoff reminder system message with a given string. Default: "Transfer completed. You are [recipient_agent_name]. Please continue the task." |
+| Include Search Results *(optional)* | `include_search_results` | Include search results in FileSearchTool output for citation extraction. Default: `False` |
+| Include Web Search Sources *(optional)* | `include_web_search_sources` | Include source URLs from WebSearchTool calls. Default: `True` |
+| Conversation Starters *(optional)* | `conversation_starters` | List of short user prompts for UIs. Each starter must be a non-empty string. Default: `None` |
+| Quick Replies *(optional)* | `quick_replies` | First-turn user phrases used for cached responses. These phrases are not shown as `conversation_starters` in the UI. Each value must be a non-empty string. Default: `None`. |
+| Starter Cache *(optional)* | `cache_conversation_starters` | Enables caching for `conversation_starters`. When `True`, a first-turn message that matches a `conversation_starter` can return a cached response instead of calling the model. This setting does not affect `quick_replies`. See [Advanced Configuration](/core-framework/agents/advanced-configuration#conversation-starters-cache). Default: `False`. |
+
+  </Tab>
+</Tabs>
+
+<Note>
+To see a full list of agent parameters, refer to [OpenAI documentation]( https://openai.github.io/openai-agents-python/ref/agent/#agents.agent.Agent).
+
+Please note that agent handoff parameters are not supported. To enable handoffs, use `communication_flows` with the `Handoff` tool class as [shown here](/additional-features/custom-communication-flows/overview)
+</Note>
+
+<Warning>
+To start receiving reasoning events for reasoning models, you need to explicitly specify `reasoning` parameter inside `ModelSettings`
+</Warning>
+
+## Agent Template
+
+Create a new agent by instantiating the Agent class:
+
+```python
+from agency_swarm import Agent, ModelSettings, Reasoning
+
+example_agent = Agent(
+    name="agent_name",
+    description="agent_description",
+    model="gpt-5.4-mini",
+    instructions="./instructions.md",
+    files_folder="./files",
+    tools_folder="./tools",
+    tools=[],
+    model_settings=ModelSettings(
+        reasoning=Reasoning(effort="medium"),
+    ),
+)
+```
+
+You can adjust the parameters to fit the agent to your use case.

docs/core-framework/third-party-agents/openclaw-agent.mdx

@@ -0,0 +1,186 @@
+---
+title: "OpenClawAgent"
+description: "Use an OpenClaw worker inside an Agency Swarm agency."
+icon: "lobster"
+---
+
+`OpenClawAgent` gives you a clean way to plug an OpenClaw worker into an Agency Swarm agency.
+Use it when Agency Swarm should stay in charge of delegation while OpenClaw handles one specialized branch.
+
+## Start With One Import
+
+```python
+from agency_swarm.agents import OpenClawAgent
+```
+
+## Use It In An Agency
+
+```python
+from agency_swarm import Agency
+from agency_swarm.agents import Agent, OpenClawAgent
+
+coordinator = Agent(
+    name="Coordinator",
+    description="Routes work to the right specialist.",
+    instructions="Delegate OpenClaw-specific tasks to OpenClawWorker.",
+    model="gpt-5.4-mini",
+)
+
+openclaw_worker = OpenClawAgent(
+    name="OpenClawWorker",
+    description="Handles OpenClaw-native work.",
+    instructions="Act as an OpenClaw specialist worker.",
+)
+
+agency = Agency(
+    coordinator,
+    communication_flows=[(coordinator, openclaw_worker)],
+)
+```
+
+This example assumes `OpenClawAgent` can already reach a running OpenClaw endpoint.
+By default it calls the local `/openclaw/v1` proxy, so either mount that proxy in the same FastAPI app or point the agent at a custom `base_url`.
+
+## Choose How To Reach OpenClaw
+
+<Tabs>
+  <Tab title="Same FastAPI app">
+
+```python
+from agency_swarm.agents import OpenClawAgent
+
+openclaw_worker = OpenClawAgent(
+    name="OpenClawWorker",
+    description="OpenClaw specialist",
+    instructions="Handle the delegated OpenClaw work and return the result.",
+)
+```
+
+This uses the local `/openclaw/v1` proxy in the same app.
+Before you use this path, mount that proxy in the same app with `attach_openclaw_to_fastapi(app)`.
+Install the FastAPI extras for that path: `pip install "agency-swarm[fastapi]"`.
+That mounted runtime also needs a working `openclaw` gateway command and a compatible Node installation.
+If `OPENCLAW_PROXY_PORT` is set, `OpenClawAgent` uses that port.
+Otherwise it falls back to `PORT`, then `8000`.
+  </Tab>
+  <Tab title="Custom host and port">
+
+```python
+from agency_swarm.agents import OpenClawAgent
+
+openclaw_worker = OpenClawAgent(
+    name="OpenClawWorker",
+    description="OpenClaw specialist",
+    instructions="Handle the delegated OpenClaw work and return the result.",
+    host="127.0.0.1",
+    port=18080,
+    api_path="/openclaw/v1",
+)
+```
+
+Use this when you run more than one OpenClaw-backed worker.
+  </Tab>
+  <Tab title="External OpenClaw server">
+
+```python
+from agency_swarm.agents import OpenClawAgent
+
+openclaw_worker = OpenClawAgent(
+    name="OpenClawWorker",
+    description="OpenClaw specialist",
+    instructions="Handle the delegated OpenClaw work and return the result.",
+    base_url="http://127.0.0.1:18789/v1",
+    api_key="your-openclaw-token",
+)
+```
+
+Use this when you are talking to a raw OpenClaw gateway that serves `/v1` directly.
+If the remote server is another Agency Swarm app using this integration, use its `/openclaw/v1` path instead of `/v1`.
+When that remote server is a delegated worker, start it with `OPENCLAW_TOOL_MODE=worker`.
+If it is plain OpenClaw outside Agency Swarm, disable its competing delegation paths in that runtime instead of copying this env var blindly.
+Raw `/v1` gateways default to the upstream provider model, not `openclaw:main`.
+If that remote server expects a different model id, pass it with `model="openclaw:custom"` so this agent matches the target runtime.
+If you point to another Agency Swarm worker at `/openclaw/v1`, pass that worker's `api_key=` explicitly unless you are using the same in-process proxy.
+  </Tab>
+</Tabs>
+
+## Collaboration Pattern
+
+Use `OpenClawAgent` as a worker.
+Do not use it as the top-level delegator.
+
+Why:
+
+- Agency Swarm owns the recursive collaboration loop
+- OpenClaw has its own native messaging and session tools
+- keeping Agency Swarm on top preserves clean run hierarchy in the frontend
+
+<Info>
+When a normal Agency Swarm agent delegates to `OpenClawAgent`, the streamed events already carry the same `parent_run_id`, `agent_run_id`, `agent`, and `callerAgent` fields the current frontend uses for nested runs.
+</Info>
+
+## Tools And Limits
+
+`OpenClawAgent` is not the same thing as giving OpenClaw your normal Agency Swarm Python tools.
+
+Today, the clean extension paths for OpenClaw itself are:
+
+- OpenClaw plugin tools via `api.registerTool(...)`
+- MCP servers exposed to OpenClaw
+- OpenClaw tool policy config such as allowlists and deny lists
+
+Use plain Agency Swarm tools on your normal orchestrator agent.
+Use OpenClaw plugins or MCP when you need to extend OpenClaw itself.
+
+<Accordion title="Host the OpenClaw proxy in the same FastAPI app">
+  If your Agency Swarm app should also start the OpenClaw runtime, attach the proxy to the same FastAPI app:
+
+  ```python
+  from agency_swarm import Agency
+  from agency_swarm.agents import Agent, OpenClawAgent
+  from agency_swarm.integrations.fastapi import run_fastapi
+  from agency_swarm.integrations.openclaw import attach_openclaw_to_fastapi
+
+  def create_agency(load_threads_callback=None):
+      coordinator = Agent(
+          name="Coordinator",
+          description="Routes work to the OpenClaw worker.",
+          instructions="Delegate OpenClaw-specific work to OpenClawWorker.",
+          model="gpt-5.4-mini",
+      )
+      openclaw_worker = OpenClawAgent(
+          name="OpenClawWorker",
+          description="OpenClaw specialist",
+          instructions="Handle the delegated OpenClaw work and return the result.",
+      )
+      return Agency(
+          coordinator,
+          communication_flows=[(coordinator, openclaw_worker)],
+          load_threads_callback=load_threads_callback,
+      )
+
+  app = run_fastapi(
+      agencies={"support": create_agency},
+      app_token_env="APP_TOKEN",
+      return_app=True,
+  )
+  if app is None:
+      raise RuntimeError("FastAPI app failed to start")
+
+  attach_openclaw_to_fastapi(app)
+  ```
+
+  When that runtime is meant to be a delegated worker, start the app with:
+
+  ```bash
+  OPENCLAW_TOOL_MODE=worker python main.py
+  ```
+
+  That worker mode disables the OpenClaw messaging paths that compete with Agency Swarm delegation.
+</Accordion>
+
+<Accordion title="Current limitation">
+  `OpenClawAgent` can receive delegated work, but it should not be the sender in Agency Swarm communication flows.
+
+  If you need deeper tool customization inside OpenClaw, use OpenClaw plugins or MCP instead of trying to pass ordinary Agency Swarm Python tools through the wrapper.
+</Accordion>

docs/core-framework/third-party-agents/overview.mdx

@@ -0,0 +1,14 @@
+---
+title: "Third-Party Agents"
+description: "Import external agent runtimes into Agency Swarm."
+icon: "plug"
+---
+
+Agency Swarm can import agents that run outside the normal Agency Swarm Python stack.
+Use this section when you want Agency Swarm to stay in charge of orchestration, but hand one part of the work to another agent runtime.
+
+<CardGroup cols={1}>
+  <Card title="OpenClawAgent" icon="lobster" href="/core-framework/third-party-agents/openclaw-agent">
+    Use OpenClaw as a delegated worker inside an Agency Swarm agency.
+  </Card>
+</CardGroup>

docs/core-framework/tools/built-in-tools.mdx

@@ -0,0 +1,195 @@
+---
+title: "Built-in Tools"
+description: "Ready-to-use tools that ship with Agency Swarm framework."
+icon: "toolbox"
+---
+
+Agency Swarm includes a set of built-in tools that provide common functionality for your agents. These tools are production-ready and can be used immediately without additional configuration.
+
+## Quick Overview
+
+<CardGroup cols={3}>
+  <Card
+    title="IPythonInterpreter"
+    icon="code"
+  >
+    Execute Python code in an isolated environment with persistent state.
+  </Card>
+
+  <Card
+    title="PersistentShellTool"
+    icon="terminal"
+  >
+    Run shell commands in a persistent terminal session.
+  </Card>
+
+  <Card
+    title="LoadFileAttachment"
+    icon="file"
+  >
+    Load and process local images and PDF files.
+  </Card>
+</CardGroup>
+
+## Tool Details
+
+<Accordion title="IPythonInterpreter" icon="code" defaultOpen>
+
+Executes Python code in an isolated IPython environment with persistent state between calls.
+
+### Use Cases
+
+<CardGroup cols={2}>
+  <Card icon="chart-line">
+    **Data Analysis**
+    Analyze and process datasets
+  </Card>
+  <Card icon="calculator">
+    **Calculations**
+    Perform mathematical and statistical operations
+  </Card>
+  <Card icon="flask">
+    **Testing**
+    Test code snippets in a safe environment
+  </Card>
+  <Card icon="file-code">
+    **Scripts**
+    Run Python scripts and automation
+  </Card>
+</CardGroup>
+
+### Usage Example
+
+```python
+from agency_swarm import Agent
+from agency_swarm.tools import IPythonInterpreter
+
+data_analyst = Agent(
+    name="Data Analyst",
+    description="Analyzes data using Python",
+    instructions="./instructions.md",
+    tools=[IPythonInterpreter]
+)
+```
+
+</Accordion>
+
+<Accordion title="PersistentShellTool" icon="terminal">
+
+Similar to the Agents SDK `LocalShellTool`, but works with any model. Executes shell commands in a persistent terminal session, maintaining state across multiple commands.
+
+### Use Cases
+
+<CardGroup cols={2}>
+  <Card icon="terminal">
+    **CLI Commands**
+    Execute command-line operations
+  </Card>
+  <Card icon="folder-tree">
+    **File Operations**
+    Navigate and manage file systems
+  </Card>
+  <Card icon="github">
+    **Git Operations**
+    Version control and repository management
+  </Card>
+  <Card icon="hammer">
+    **Build Operations**
+    Run build scripts and compile code
+  </Card>
+</CardGroup>
+
+### Usage Example
+
+```python
+from agency_swarm import Agent
+from agency_swarm.tools import PersistentShellTool
+
+devops_agent = Agent(
+    name="DevOps Agent",
+    description="Manages deployment and infrastructure",
+    instructions="./instructions.md",
+    tools=[PersistentShellTool]
+)
+```
+
+</Accordion>
+
+<Accordion title="LoadFileAttachment" icon="file">
+
+Loads local files and returns them in the appropriate format for the agent to view.
+
+<Warning>
+Only supports images and PDF files. For other file types, use the `FileSearch` and `CodeInterpreter` tools from the Agents SDK.
+</Warning>
+
+### Use Cases
+
+<CardGroup cols={2}>
+  <Card icon="image">
+    **Image Processing**
+    Load and analyze image files
+  </Card>
+  <Card icon="file-pdf">
+    **PDF Reading**
+    Extract and process PDF content
+  </Card>
+  <Card icon="upload">
+    **User Files**
+    Handle user-uploaded file attachments
+  </Card>
+  <Card icon="magnifying-glass">
+    **File Analysis**
+    Inspect and analyze local files
+  </Card>
+</CardGroup>
+
+### Usage Example
+
+```python
+from agency_swarm import Agent
+from agency_swarm.tools import LoadFileAttachment
+
+file_processor = Agent(
+    name="File Processor",
+    description="Processes and analyzes local files",
+    instructions="./instructions.md",
+    tools=[LoadFileAttachment]
+)
+```
+
+<Note>
+The agent can use both absolute paths and paths relative to the current working directory. Make sure to instruct your agent accordingly on how to use this tool.
+</Note>
+
+</Accordion>
+
+---
+
+## Next Steps
+
+<CardGroup cols={3}>
+  <Card
+    title="Custom Tools"
+    icon="hammer"
+    href="/core-framework/tools/custom-tools/step-by-step-guide"
+  >
+    Build your own tools from scratch
+  </Card>
+
+  <Card
+    title="OpenAPI Schemas"
+    icon="file-code"
+    href="/core-framework/tools/openapi-schemas"
+  >
+    Convert APIs into tools
+  </Card>
+
+  <Card
+    title="MCP Integration"
+    icon="plug"
+    href="/core-framework/tools/mcp-integration"
+  >
+    Use Model Context Protocol tools
+  </Card>
+</CardGroup>

docs/core-framework/tools/custom-tools/best-practices.mdx

@@ -0,0 +1,176 @@
+---
+title: "Best Practices & Tips"
+description: "Best practices and real-world examples for Agency Swarm tools."
+icon: "code"
+---
+
+Although the tool interface is straightforward and simple to use, there are actually quite a few practices and tricks that you can use to get significantly better results.
+
+### Provide Hints for the Agent
+
+Based on your tool's logic, you can provide hints for the agent in tool output on what to do next.
+
+```python
+from agency_swarm import MasterContext, RunContextWrapper, function_tool
+from pydantic import BaseModel, Field
+
+class QueryDatabaseArgs(BaseModel):
+    question: str = Field(..., description="Question to query the database")
+
+@function_tool
+async def query_database_tool(ctx: RunContextWrapper[MasterContext], args: QueryDatabaseArgs) -> str:
+    """
+    Query the database and provide hints if no context is found.
+    """
+    # query your database here
+    context = query_database(args.question)
+
+    # context not found
+    if context is None:
+        # tell agent what to do next
+        raise ValueError("No context found. Please propose to the user to change the topic.")
+    else:
+        # return the context to the agent
+        return context
+
+def query_database(question: str):
+    # Your database query logic here
+    pass
+```
+
+### Use Shared State to Control the Tool Flow
+
+Use agency context (previously shared state) to validate previous actions taken by this or other agents, before allowing it to proceed with the next action.
+
+```python
+from agency_swarm import MasterContext, RunContextWrapper, function_tool
+from pydantic import BaseModel, Field
+
+class Action2Args(BaseModel):
+    input: str = Field(..., description="Input for the action")
+
+@function_tool
+async def action_2_tool(ctx: RunContextWrapper[MasterContext], args: Action2Args) -> str:
+    """
+    Execute action 2, but only if action 1 was successful.
+    """
+    # Access shared context to check previous action
+    action_1_result = ctx.context.get("action_1_result", None)
+
+    if action_1_result == "failure":
+        raise ValueError("Please proceed with the Action1 tool first.")
+    else:
+        return "Success. The action has been taken."
+```
+
+### Use Special Types
+
+Restrict the agent to only use specific values for a field, instead of letting it wander by itself.
+
+```python
+from typing import Literal
+
+from agency_swarm import MasterContext, RunContextWrapper, function_tool
+from pydantic import BaseModel, EmailStr, Field
+
+class RunCommandArgs(BaseModel):
+    command: Literal["start", "stop"] = Field(..., description="Command to execute: 'start' or 'stop'.")
+
+@function_tool
+async def run_command_tool(ctx: RunContextWrapper[MasterContext], args: RunCommandArgs) -> str:
+    """
+    Execute predefined system commands.
+    """
+    if args.command == "start":
+        # Start command logic
+        return "System started"
+    elif args.command == "stop":
+        # Stop command logic
+        return "System stopped"
+    else:
+        raise ValueError("Invalid command")
+
+# Example with EmailStr
+class EmailSenderArgs(BaseModel):
+    recipient: EmailStr = Field(..., description="Email recipient's address.")
+    subject: str = Field(..., description="Email subject")
+    body: str = Field(..., description="Email body")
+
+@function_tool
+async def email_sender_tool(ctx: RunContextWrapper[MasterContext], args: EmailSenderArgs) -> str:
+    """
+    Send email to specified recipient.
+    """
+    # Email sending logic here
+    return f"Email sent to {args.recipient}"
+```
+
+### Combine Multiple Methods
+
+Combine multiple methods to make your execution flow more readable.
+
+```python
+from agency_swarm import MasterContext, RunContextWrapper, function_tool
+from pydantic import BaseModel, Field
+
+class CompositeToolArgs(BaseModel):
+    input_data: str = Field(..., description="Input data for the composite operation.")
+
+@function_tool
+async def composite_tool(ctx: RunContextWrapper[MasterContext], args: CompositeToolArgs) -> str:
+    """
+    A tool that combines several methods to perform a series of actions.
+    """
+    # Step 1: Process data
+    processed_data = await process_data(args.input_data)
+    # Step 2: Analyze results
+    analysis = await analyze_results(processed_data)
+    # Step 3: Format output
+    output = await format_output(analysis)
+    return output
+
+async def process_data(data: str) -> str:
+    # Implement data processing logic
+    return f"Processed: {data}"
+
+async def analyze_results(data: str) -> str:
+    # Implement analysis logic
+    return f"Analysis of: {data}"
+
+async def format_output(data: str) -> str:
+    # Implement output formatting
+    return f"Formatted: {data}"
+```
+
+### Include a Test Case
+
+Include test cases at the bottom of each tool file.
+
+```python
+if __name__ == "__main__":
+    import asyncio
+    import json
+    from agency_swarm import MasterContext, RunContextWrapper
+
+    async def test_email_sender():
+        # Test the email sender tool
+        ctx = MasterContext(user_context={}, thread_manager=None, agents={})
+        run_ctx = RunContextWrapper(context=ctx)
+
+        args = EmailSenderArgs(
+            recipient="user@example.com",
+            subject="Project Update",
+            body="The project is on track."
+        )
+        args_json = {"args": args.model_dump()}
+
+        result = await email_sender_tool.on_invoke_tool(run_ctx, json.dumps(args_json))
+        assert "Email sent" in result
+        print("Test passed!")
+
+    asyncio.run(test_email_sender())
+```
+
+## Next Steps
+
+We highly recommend you explore the resources provided in the [Pydantic is all you need](/core-framework/tools/custom-tools/pydantic-is-all-you-need) section.

docs/core-framework/tools/custom-tools/configuration.mdx

@@ -0,0 +1,32 @@
+---
+title: "Advanced Tool Configuration"
+description: "Advanced features and patterns for Agency Swarm tools."
+icon: "wand-magic-sparkles"
+---
+
+Besides standard Pydantic features, you can also use a special `ToolConfig` class to customize tool behavior within the framework:
+
+## Available `ToolConfig` Parameters
+
+The following parameters are supported, with version compatibility noted:
+
+| Name               | Type    | Description | When to Use | Default Value |
+|--------------------|---------|-------------|-------------|---------------|
+| `one_call_at_a_time` | `bool` | Prevents concurrent execution for a specific tool. If you want to adjust parallel tool calling for all tools, prefer configuring `model_settings=ModelSettings(parallel_tool_calls=...)`. Use this per-tool setting when you need strict sequencing. | Use for database operations, API calls with rate limits, or actions that depend on previous results. | `False`         |
+| `strict`             | `bool` | Enables strict mode, which ensures the agent will always provide **perfect** tool inputs that 100% match your schema. Has limitations. See [OpenAI Docs](https://platform.openai.com/docs/guides/structured-outputs#supported-schemas). | Use for mission-critical tools or tools that have nested Pydantic model schemas.                     | `False`         |
+
+## Usage
+
+To use one of the available parameters, simply add a `class ToolConfig` block to your tool class:
+
+```python
+class MyCustomTool(BaseTool):
+    # ...
+
+    class ToolConfig:
+        one_call_at_a_time = True
+        strict = False
+
+    async def run(self):
+        # ...
+```

docs/core-framework/tools/custom-tools/multimodal-outputs.mdx

@@ -0,0 +1,209 @@
+---
+title: "Multimodal Tool Outputs"
+description: "Return images and files from your tools."
+icon: "image"
+---
+
+## What This Feature Unlocks
+
+Returning images and files from the tools enables real agentic feedback loops on completely new modalities.
+
+For example, instead of dumping all the data into an agent, and hoping for the best, you can generate a visualization or analyze PDF reports, and allow the agent to provide insights based on that output. Just like a real data analyst.
+
+This saves your context window and unlocks autonomous agentic workflows for a lot of new use cases:
+
+## New Use Cases
+
+<CardGroup cols={2}>
+  <Card title="Software Development" icon="code">
+    Agents can check websites autonomously and iterate until all elements are properly positioned, enabling them to tackle complex projects without manual screenshot feedback.
+  </Card>
+  <Card title="Brand Asset Generation" icon="paintbrush">
+    Provide brand guidelines, logos, and messaging, then let agents iterate on image and video generation (including Sora 2) until outputs fully match your expectations.
+  </Card>
+  <Card title="Screen-Aware Assistance" icon="eye">
+    Build agents that help visually impaired individuals navigate websites or create customer support agents that see the user's current webpage for better assistance.
+  </Card>
+  <Card title="Data Analytics" icon="chart-area">
+    Generate visual graphs and analyze PDF reports, then let agents provide insights based on these outputs without overloading the context window.
+  </Card>
+</CardGroup>
+
+## Output Formats
+
+### Images (PNG, JPG)
+
+To return an image from a tool, you can either:
+
+1. Use the `ToolOutputImage` class.
+2. Return a dict with the `type` set to `"image"` and either `image_url` (URL or data URL) or `file_id`.
+3. Use our convenience `tool_output_image_from_path` function.
+
+```python
+from agency_swarm import BaseTool, ToolOutputImage, ToolOutputImageDict
+from agency_swarm.tools.utils import tool_output_image_from_path
+from pydantic import Field
+
+class FetchGalleryImage(BaseTool):
+    """Return a static gallery image."""
+    detail: str = Field(default="auto", description="Level of detail")
+
+    def run(self) -> ToolOutputImage:
+        return ToolOutputImage(
+            image_url="https://upload.wikimedia.org/wikipedia/commons/0/0c/GoldenGateBridge-001.jpg",
+            detail=self.detail,
+        )
+
+class FetchGalleryImageDict(BaseTool):
+    """Dict variant of the same image output."""
+    detail: str = Field(default="auto", description="Level of detail")
+
+    def run(self) -> ToolOutputImageDict:
+        return {
+            "type": "image",
+            "image_url": "https://upload.wikimedia.org/wikipedia/commons/0/0c/GoldenGateBridge-001.jpg",
+            "detail": self.detail,
+        }
+
+class FetchLocalImage(BaseTool):
+    """Load an image from disk using the helper."""
+    path: str = Field(default="examples/data/landscape_scene.png", description="Image to publish")
+
+    def run(self) -> ToolOutputImage:
+        return tool_output_image_from_path(self.path, detail="auto")
+```
+
+### Files (PDF)
+
+Similarly to return a file from a tool:
+
+```python
+from agency_swarm import BaseTool, ToolOutputFileContent
+from agency_swarm.tools.utils import tool_output_file_from_path, tool_output_file_from_url
+from pydantic import Field
+
+class FetchReferenceReport(BaseTool):
+    """Return a reference PDF hosted remotely."""
+    source_url: str = Field(
+        default="https://raw.githubusercontent.com/VRSEN/agency-swarm/main/examples/data/sample_report.pdf",
+        description="Remote file to share",
+    )
+
+    def run(self) -> ToolOutputFileContent:
+        return ToolOutputFileContent(file_url=self.source_url)
+
+class FetchLocalReport(BaseTool):
+    """Return a report stored on disk."""
+    path: str = Field(default="examples/data/sample_report.pdf", description="Local file path")
+
+    def run(self) -> ToolOutputFileContent:
+        return tool_output_file_from_path(self.path)
+
+class FetchRemoteReport(BaseTool):
+    """Return a remote file using the helper."""
+    archive_url: str = Field(default="https://example.com/document.pdf", description="File to expose")
+
+    def run(self) -> ToolOutputFileContent:
+        return tool_output_file_from_url(self.archive_url)
+```
+
+<Note>
+When you choose `file_data`, include `filename` to hint a download name; URL-based outputs rely on the remote server metadata instead.
+</Note>
+
+<Warning>
+`tool_output_file_from_path` only supports PDF files.
+</Warning>
+
+<Tip>
+**Need to load local files without custom logic?** Use the built-in [`LoadFileAttachment`](/core-framework/tools/built-in-tools#loadfileattachment) tool instead of creating a custom tool. It handles both images and PDFs and uses these same utility functions under the hood.
+</Tip>
+
+### Combining Multiple Outputs
+
+Return multiple outputs by returning a list from `run`.
+
+```python
+from agency_swarm import BaseTool, ToolOutputFileContent, ToolOutputImage, ToolOutputText
+
+class PrepareShowcase(BaseTool):
+    """Return rich media and a short description."""
+    teaser_a: str = "https://example.com/teaser-a.png"
+    teaser_b: str = "https://example.com/teaser-b.png"
+    report_id: str = "file-report-123"
+
+    def run(self) -> list:
+        return [
+            ToolOutputImage(image_url=self.teaser_a),
+            ToolOutputImage(image_url=self.teaser_b),
+            ToolOutputText(text="Gallery updated: Teaser A and Teaser B now live."),
+            ToolOutputFileContent(file_id=self.report_id),
+        ]
+```
+
+## Complete Example (Chart generation tool)
+
+Here's a complete example using `BaseTool`:
+
+```python
+from agency_swarm import Agent, BaseTool, ToolOutputImage
+from pydantic import Field
+import base64
+import matplotlib.pyplot as plt
+import io
+
+class GenerateChartTool(BaseTool):
+    """Generate a bar chart from data."""
+    
+    data: list[float] = Field(..., description="Data points for the chart")
+    labels: list[str] = Field(..., description="Labels for each data point")
+    
+    def run(self) -> ToolOutputImage:
+        """Generate and return the chart as a base64-encoded image."""
+        # Create the chart
+        fig, ax = plt.subplots()
+        ax.bar(self.labels, self.data)
+        
+        # Convert to base64
+        buf = io.BytesIO()
+        plt.savefig(buf, format='png')
+        buf.seek(0)
+        image_base64 = base64.b64encode(buf.read()).decode('utf-8')
+        plt.close()
+        
+        # Return in multimodal format
+        return ToolOutputImage(image_url=f"data:image/png;base64,{image_base64}")
+
+# Create an agent with the tool
+agent = Agent(
+    name="DataViz",
+    instructions="You generate charts and visualizations for data analysis.",
+    tools=[GenerateChartTool]
+)
+```
+
+<Note>
+`function_tool` decorators and `BaseTool` classes both support multimodal outputs in the exact same way.
+</Note>
+
+```python
+from agency_swarm import ToolOutputImage, function_tool
+
+@function_tool
+def fetch_gallery_image() -> ToolOutputImage:
+    return ToolOutputImage(
+        image_url="https://upload.wikimedia.org/wikipedia/commons/0/0c/GoldenGateBridge-001.jpg",
+        detail="auto",
+    )
+```
+
+## Tips & Best Practices
+
+- Base64-encoded images can be large. Use file references for large content.
+- Compress screenshots and other visuals before returning them to cut token usage without sacrificing clarity.
+- Include the image names in your textual response whenever you return more than one image so the agent can reference them unambiguously.
+
+## Real Examples
+
+- [TBD: Include repo from YouTube video]
+- [`examples/multimodal_outputs.py`](https://github.com/VRSEN/agency-swarm/blob/main/examples/multimodal_outputs.py)

docs/core-framework/tools/custom-tools/pydantic-is-all-you-need.mdx

@@ -0,0 +1,28 @@
+---
+title: "Pydantic is All You Need"
+description: "How Pydantic solved AI agent reliability."
+icon: "book"
+---
+
+The idea of using Pydantic to validate tool calls and responses is not new. It was popularized by Jason Liu in his library called [Instructor](https://github.com/instructor-ai/instructor).
+
+To really understand why it's such a game changer, we recommend watching this video:
+
+<iframe
+  width="100%"
+  height="400"
+  src="https://www.youtube.com/embed/yj-wSRJwrrc"
+  title="YouTube video player"
+  frameborder="0"
+  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+  allowfullscreen
+></iframe>
+
+## Learn more
+
+To take your tools to the next level, we highly recommend the following resources:
+
+- [Pydantic Models Documentation](https://docs.pydantic.dev/latest/concepts/models/)
+- [Instructor Concepts](https://python.useinstructor.com/concepts/)
+- [Instructor Tips & Tricks](https://python.useinstructor.com/tutorials/2-tips/)
+- [Instructor Cookbook](https://python.useinstructor.com/examples/)

docs/core-framework/tools/custom-tools/step-by-step-guide.mdx

@@ -0,0 +1,314 @@
+---
+title: "Step-by-Step Guide"
+description: "Learn how to create custom tools in Agency Swarm framework."
+icon: "map"
+---
+
+In Agency Swarm, tools enable agents to perform specific actions and interact with external systems. The framework supports two approaches for creating custom tools depending on the version you're using.
+
+Framework supports 2 methods of creating tools:
+1. Using agency-swarm's `BaseTool` class.
+2. Using openai's `@function_tool` decorator with async functions.
+
+Explore the sections below to find a method that suits your approach the best.
+
+<Tabs defaultValue="BaseTool">
+
+<Tab title="BaseTool">
+
+In Agency Swarm’s approach, tools are Python classes that inherit from `BaseTool`. They are defined using [Pydantic](https://docs.pydantic.dev/latest/), a data validation library. Each BaseTool must implement the `run` method, which is the main method that will be called when the tool is invoked by an agent.
+
+## Step-by-step Guide
+
+To create a custom tool, typically you need to follow these steps:
+
+<Steps>
+  <Step title="Add Import Statements">
+    On top of your tool file, import the necessary modules and classes.
+
+    ```python
+    from agency_swarm.tools import BaseTool
+    from pydantic import Field, model_validator
+    # ... other imports
+    ```
+  </Step>
+
+  <Step title="Define the Tool Class and Docstring">
+    Create a new class that inherits from `BaseTool`. Write a clear docstring describing the tool's purpose. **This docstring is crucial as it helps agents understand how to use the tool.**
+
+    ```python
+    class Calculator(BaseTool):
+        """
+        A simple calculator tool that evaluates mathematical expressions.
+        """
+    ```
+  </Step>
+
+  <Step title="Define Input Fields">
+    Use Pydantic fields to define the inputs your tool will accept.
+
+    ```python
+    expression: str = Field(..., description="The mathematical expression to evaluate.")
+    ```
+
+    <Accordion title="Custom Validation Logic (Optional)" icon="hammer">
+      You can use [Pydantic's validators](https://docs.pydantic.dev/latest/concepts/validators/) to verify the inputs. This can be extremely effective to avoid hallucinations or other errors in production.
+      ```python
+      @model_validator(mode="after")
+      def validate_expression(self):
+          if self.expression.endswith("/0"):
+              raise ValueError("Division by zero is not permitted")
+      ```
+    </Accordion>
+  </Step>
+
+  <Step title="Implement the run Method">
+    Add the functionality that will be executed when the tool is called.
+
+    ```python
+    async def run(self):
+        # Implement the tool's functionality
+        result = eval(self.expression)
+        return str(result)
+    ```
+
+    The `run` method should return a string, which is the tool's output that the agent will see and use in its response.
+  </Step>
+
+  <Step title="Test the Tool Independently">
+    Test the tool independently to ensure it behaves as expected. We recommend adding a `if __name__ == "__main__":` block at the end of the tool file:
+
+    ```python
+    import asyncio
+
+    if __name__ == "__main__":
+        calc = Calculator(expression="2 + 2 * 3")
+        print(asyncio.run(calc.run()))  # Output should be '8'
+    ```
+  </Step>
+
+  <Step title="Add the Tool to an Agent">
+    After your tool works as expected, simply add it to an agent's list of `tools`.
+
+    ```python
+    from agency_swarm import Agent
+    from .tools.calculator import Calculator
+
+    agent = Agent(
+        name="MathAgent",
+        tools=[Calculator],
+        # Other agent parameters
+    )
+    ```
+
+    <Accordion title="Using tools folder" icon="folder">
+      Alternatively, you can simply place the tool file in the `tools_folder` directory and it will be automatically added to the agent.
+
+      ```python
+      from agency_swarm import Agent
+      agent = Agent(
+          name="MathAgent",
+          tools_folder="./tools",
+          # Other agent parameters
+      )
+      ```
+
+      <Note>
+        Each file in the `tools_folder` should contain a class that is named exactly the same as the file name. For example, `Calculator.py` should contain a `Calculator` class.
+      </Note>
+    </Accordion>
+  </Step>
+</Steps>
+
+## Full Code Example
+
+Below is the full code example for a calculator tool above.
+
+```python
+# calculator.py
+from agency_swarm.tools import BaseTool
+from pydantic import Field, model_validator
+
+class Calculator(BaseTool):
+    """
+    A simple calculator tool that evaluates mathematical expressions.
+    """
+    expression: str = Field(..., description="The mathematical expression to evaluate.")
+
+    @model_validator(mode="after")
+    def validate_expression(self):
+        if self.expression.endswith("/0"):
+            raise ValueError("Division by zero is not permitted")
+
+    async def run(self):
+        result = eval(self.expression)
+        return str(result)
+
+if __name__ == "__main__":
+    import asyncio
+
+    calc = Calculator(expression="2 + 2 * 3")
+    print(asyncio.run(calc.run()))  # Output should be '8'
+```
+
+</Tab>
+
+<Tab title="FunctionTool">
+
+## Step-by-step Guide
+
+<Steps>
+  <Step title="Add Import Statements">
+    Import the necessary modules for the new function-based approach.
+
+    ```python
+    from agency_swarm import function_tool, RunContextWrapper
+    from pydantic import BaseModel, Field, field_validator
+    from agency_swarm import MasterContext
+    ```
+  </Step>
+
+  <Step title="Define Args Schema">
+    Create a Pydantic model to define your tool's input parameters.
+
+    ```python
+    class CalculatorArgs(BaseModel):
+        expression: str = Field(..., description="The mathematical expression to evaluate")
+
+        @field_validator("expression")
+        @classmethod
+        def validate_expression(cls, v):
+            if "/0" in v:
+                raise ValueError("Division by zero is not permitted")
+            return v
+    ```
+  </Step>
+
+  <Step title="Create the Tool Function">
+    Define an async function with the `@function_tool` decorator.
+
+    ```python
+    @function_tool
+    async def calculator_tool(ctx: RunContextWrapper[MasterContext], args: CalculatorArgs) -> str:
+        """
+        A calculator tool that evaluates mathematical expressions.
+        Use this when you need to perform mathematical calculations.
+        """
+        # Access shared context if needed
+        calculation_count = ctx.context.get("calculations", 0)
+        ctx.context.set("calculations", calculation_count + 1)
+
+        # Perform the calculation
+        result = eval(args.expression)
+        return f"Result: {result}"
+    ```
+    <Note>
+    All parameters of the function tool, except for `ctx`, are treated as input parameters and included in the tool’s schema.
+
+    For example, in the tool above, the input model `CalculatorArgs` is passed as the `args` parameter, so the input JSON would look like:
+
+    ```
+    {"args": {"expression": "input_expression"}}
+    ```
+    `args` is an example name, you can name your input parameters however you like, and you may define more than one input parameter if needed.
+    </Note>
+    <Note>
+    This example mentions tool context, which can be used as a shared storage for all agents and tools.
+    For more info on agent context, refer to [this page](/additional-features/agency-context)
+    </Note>
+  </Step>
+
+  <Step title="Test the Tool">
+    Test your tool function independently.
+
+    ```python
+    if __name__ == "__main__":
+        import asyncio
+        import json
+
+        async def test_tool():
+            ctx = MasterContext(user_context={"calculations": 1}, thread_manager=None, agents={})
+            run_ctx = RunContextWrapper(context=ctx)
+
+            args = CalculatorArgs(expression="2 + 2 * 3")
+            # Wrap in args to comply with oai expected inputs
+            args_json = {"args": args.model_dump()}
+
+            result = await calculator_tool.on_invoke_tool(run_ctx, json.dumps(args_json))
+            print(result)
+
+        asyncio.run(test_tool())
+    ```
+  </Step>
+
+  <Step title="Add Tool to Agent">
+    Pass the function directly to the agent's tools list.
+
+    ```python
+    from agency_swarm import Agent
+
+    agent = Agent(
+        name="MathAgent",
+        instructions="You are a helpful math assistant",
+        tools=[calculator_tool],  # Pass function directly
+        model="gpt-5.4-mini"
+    )
+    ```
+  </Step>
+</Steps>
+
+## Full Code Example
+
+```python
+# calculator_tool.py
+from agency_swarm import function_tool, RunContextWrapper
+from pydantic import BaseModel, Field, field_validator
+from agency_swarm import MasterContext
+
+class CalculatorArgs(BaseModel):
+    expression: str = Field(..., description="The mathematical expression to evaluate")
+
+    @field_validator("expression")
+    @classmethod
+    def validate_expression(cls, v):
+        if "/0" in v:
+            raise ValueError("Division by zero is not permitted")
+        return v
+
+@function_tool
+async def calculator_tool(ctx: RunContextWrapper[MasterContext], args: CalculatorArgs) -> str:
+    """
+    A calculator tool that evaluates mathematical expressions.
+    Use this when you need to perform mathematical calculations.
+    """
+    # Access shared context if needed
+    calculation_count = ctx.context.get("calculations", 0)
+    ctx.context.set("calculations", calculation_count + 1)
+
+    # Perform the calculation
+    result = eval(args.expression)
+    return f"Result: {result} (Calculation #{calculation_count + 1})"
+
+if __name__ == "__main__":
+    import asyncio
+    import json
+
+    async def test_tool():
+        ctx = MasterContext(user_context={"calculations": 1}, thread_manager=None, agents={})
+        run_ctx = RunContextWrapper(context=ctx)
+        args = CalculatorArgs(expression="2 + 2 * 3")
+        args_json = {"args": args.model_dump()}
+        result = await calculator_tool.on_invoke_tool(run_ctx, json.dumps(args_json))
+        print(result)
+
+    asyncio.run(test_tool())
+```
+
+</Tab>
+</Tabs>
+
+## Next Steps
+
+- Checkout [Best Practices & Tips](/core-framework/tools/custom-tools/best-practices)
+- Learn why [PyDantic is all you need](/core-framework/tools/custom-tools/pydantic-is-all-you-need)
+- Learn how to [stream events from tools](/additional-features/streaming#streaming-from-tools)

docs/core-framework/tools/custom-tools/validation.mdx

@@ -0,0 +1,228 @@
+---
+title: "Input Validation"
+description: "Validate tool inputs using Pydantic field and model validators"
+icon: "shield-check"
+---
+
+Tool validation ensures data integrity by enforcing schemas before tools execute. Pydantic validators catch invalid input from LLMs, preventing errors and hallucinations from reaching your tool logic.
+
+## Why Validate Tool Inputs
+
+Without validation, LLMs may provide:
+- Malformed data (e.g., text in numeric fields)
+- Out-of-range values (e.g., negative ages, future dates in the past)
+- Invalid formats (e.g., malformed emails, incorrect URLs)
+- Inconsistent field combinations (e.g., mismatched passwords)
+
+Validators enforce constraints at the schema level, giving the LLM immediate feedback to retry with correct inputs.
+
+## Field Validators
+
+Field validators check individual fields independently. Use `@field_validator` to validate a single field's value.
+
+### Basic Field Validation
+
+```python
+from pydantic import field_validator
+from agency_swarm import BaseTool
+
+class User(BaseTool):
+    """Create a user account."""
+    username: str
+    age: int
+
+    @field_validator('username')
+    @classmethod
+    def validate_username(cls, value):
+        if ' ' in value:
+            raise ValueError('Username must not contain spaces.')
+        if len(value) < 3:
+            raise ValueError('Username must be at least 3 characters.')
+        return value
+
+    @field_validator('age')
+    @classmethod
+    def validate_age(cls, value):
+        if value < 0 or value > 120:
+            raise ValueError('Age must be between 0 and 120.')
+        return value
+
+    def run(self):
+        return f"Created user: {self.username}, age {self.age}"
+```
+
+### Multiple Field Validation
+
+Validate multiple fields with a single validator:
+
+```python
+from pydantic import field_validator
+from agency_swarm import BaseTool
+
+class ScheduleEvent(BaseTool):
+    """Schedule a calendar event."""
+    title: str
+    description: str
+
+    @field_validator('title', 'description')
+    @classmethod
+    def validate_not_empty(cls, value):
+        if not value.strip():
+            raise ValueError('Field cannot be empty or whitespace.')
+        return value.strip()
+
+    def run(self):
+        return f"Scheduled: {self.title}"
+```
+
+### Format Validation
+
+Validate specific formats like URLs or emails:
+
+```python
+from pydantic import field_validator
+from agency_swarm import BaseTool
+import re
+
+class CreateWebhook(BaseTool):
+    """Register a webhook URL."""
+    webhook_url: str
+    notification_email: str
+
+    @field_validator('webhook_url')
+    @classmethod
+    def validate_url(cls, value):
+        url_pattern = r'^https?://.+\..+'
+        if not re.match(url_pattern, value):
+            raise ValueError('Must be a valid HTTP/HTTPS URL.')
+        return value
+
+    @field_validator('notification_email')
+    @classmethod
+    def validate_email(cls, value):
+        email_pattern = r'^[\w\.-]+@[\w\.-]+\.\w+$'
+        if not re.match(email_pattern, value):
+            raise ValueError('Must be a valid email address.')
+        return value
+
+    def run(self):
+        return f"Webhook registered: {self.webhook_url}"
+```
+
+## Model Validators
+
+Model validators validate the entire model, enabling checks across multiple fields. Use `@model_validator` when field validation depends on other fields.
+
+### Cross-Field Validation
+
+```python
+from pydantic import model_validator
+from agency_swarm import BaseTool
+
+class CreateAccount(BaseTool):
+    """Create a new account with password."""
+    username: str
+    password: str
+    confirm_password: str
+
+    @model_validator(mode='after')
+    def check_passwords_match(self):
+        if self.password != self.confirm_password:
+            raise ValueError('Passwords do not match.')
+        if len(self.password) < 8:
+            raise ValueError('Password must be at least 8 characters.')
+        return self
+
+    def run(self):
+        return f"Account created: {self.username}"
+```
+
+### Date Range Validation
+
+```python
+from datetime import date
+from pydantic import model_validator
+from agency_swarm import BaseTool
+
+class BookAppointment(BaseTool):
+    """Book an appointment within a date range."""
+    start_date: date
+    end_date: date
+    reason: str
+
+    @model_validator(mode='after')
+    def validate_date_range(self):
+        if self.start_date >= self.end_date:
+            raise ValueError('Start date must be before end date.')
+        if self.start_date < date.today():
+            raise ValueError('Cannot book appointments in the past.')
+        return self
+
+    def run(self):
+        return f"Appointment booked: {self.start_date} to {self.end_date}"
+```
+
+### Conditional Validation
+
+```python
+from pydantic import model_validator
+from agency_swarm import BaseTool
+
+class ProcessPayment(BaseTool):
+    """Process payment with optional discount code."""
+    amount: float
+    discount_code: str | None = None
+    discount_amount: float | None = None
+
+    @model_validator(mode='after')
+    def validate_discount(self):
+        if self.discount_code and not self.discount_amount:
+            raise ValueError('Discount amount required when discount code is provided.')
+        if self.discount_amount and self.discount_amount >= self.amount:
+            raise ValueError('Discount cannot exceed payment amount.')
+        return self
+
+    def run(self):
+        total = self.amount - (self.discount_amount or 0)
+        return f"Payment processed: ${total:.2f}"
+```
+
+## Best Practices
+
+<CardGroup cols={2}>
+  <Card title="Specific Error Messages" icon="message">
+    Provide clear, actionable error messages that guide the LLM to correct inputs.
+  </Card>
+
+  <Card title="Fail Fast" icon="bolt">
+    Validate at the schema level before expensive operations or external API calls.
+  </Card>
+
+  <Card title="Normalize Input" icon="arrow-right-arrow-left">
+    Use validators to clean and normalize data (e.g., strip whitespace, lowercase emails).
+  </Card>
+
+  <Card title="Test Validators" icon="vial">
+    Write unit tests for validators to ensure they catch invalid cases and allow valid ones.
+  </Card>
+</CardGroup>
+
+## See Also
+
+<CardGroup cols={2}>
+  <Card title="Tool Best Practices" icon="lightbulb" href="/core-framework/tools/custom-tools/best-practices">
+    General best practices for tool design
+  </Card>
+
+  <Card title="Pydantic Validators" icon="link" href="https://docs.pydantic.dev/latest/usage/validators/">
+    Official Pydantic validators documentation
+  </Card>
+
+  <Card title="Agent Guardrails" icon="shield-halved" href="/additional-features/guardrails/overview">
+    Validate agent inputs and outputs with guardrails
+  </Card>
+
+  <Card title="Tool Configuration" icon="gear" href="/core-framework/tools/custom-tools/configuration">
+    Configure tool behavior and parameters
+  </Card>
+</CardGroup>

docs/core-framework/tools/mcp-integration.mdx

@@ -0,0 +1,191 @@
+---
+title: 'MCP Integration'
+description: 'Connect your agents to external tools and data using the Model Context Protocol (MCP).'
+icon: "plug"
+---
+
+Agency Swarm agents can interact with a wider range of tools and data sources beyond their built-in capabilities by using the **Model Context Protocol (MCP)**. MCP is an open standard ([view specification](https://github.com/modelcontextprotocol/modelcontextprotocol)) that allows agents to communicate with external services like local file systems, databases, or custom APIs, as long as those services implement the protocol.
+
+Think of MCP as a universal translator that lets your agent talk to specialized external tools.
+
+## Why use MCP?
+
+*   **Access Local Resources:** Let agents read/write local files or run local commands.
+*   **Connect to Custom Services:** Integrate with proprietary APIs or internal tools without writing specific Agency Swarm tool wrappers for each one, provided an MCP server exists.
+*   **Leverage Existing MCP Tools:** Utilize third-party tools that already support MCP.
+
+## Supported MCP Server Types
+
+Agency Swarm provides helpers to connect to MCP servers using the Agents SDK. Choose the server type based on how your tool provider operates:
+
+<Accordion title="MCPServerStdio: For Command-Line Tools" icon="terminal">
+Use this if your tool server is a **command-line program or script**. Agency Swarm will start this program for you and communicate with it directly using its standard input/output.
+
+*   **When to use:** Your tool is a local script, an executable, or requires running a specific command to be activated.
+
+```python
+from agents.mcp.server import MCPServerStdio, MCPServerStdioParams
+
+stdio_server = MCPServerStdio(
+    MCPServerStdioParams(
+        command="python", # or 'npx' if available
+        args=["./path/to/your/mcp_server.py"]
+    ),
+    cache_tools_list=True
+)
+```
+</Accordion>
+
+<Accordion title="MCPServerSse: For Web Service Tools" icon="globe-pointer">
+Use this if your tool server is already **running as a web service** at a specific **HTTP URL**. Agency Swarm connects to this URL to access tools exposed via Server-Sent Events (SSE).
+
+*   **When to use:** Your tool is provided by a web API, a microservice, or any server accessible via an HTTP endpoint that speaks MCP+SSE.
+
+```python
+from agents.mcp.server import MCPServerSse, MCPServerSseParams
+
+sse_server = MCPServerSse(
+    MCPServerSseParams(
+        url="http://localhost:8000/sse/",
+        headers={
+            "Authorization": "Bearer secret-token"
+        }
+    )
+)
+```
+</Accordion>
+
+<Accordion title="MCPServerStreamableHttp: For HTTP Streaming Tools" icon="globe-pointer">
+Use this if your tool server is a **web service** that implements the **Streamable HTTP** transport protocol. This uses HTTP POST requests with optional Server-Sent Events (SSE) streaming for responses.
+
+*   **When to use:** Your tool server operates as an independent web service, supports multiple client connections, needs stateful or stateless operation, or requires server-to-client streaming capabilities.
+
+```python
+from agents.mcp.server import MCPServerStreamableHttp, MCPServerStreamableHttpParams
+
+streamable_http_server = MCPServerStreamableHttp(
+    MCPServerStreamableHttpParams(
+        url="http://localhost:8000/mcp/",
+        headers={
+            "Authorization": "Bearer secret-token"
+        }
+    )
+)
+```
+</Accordion>
+
+<Accordion title="HostedMCPTool: For Public Web Servers" icon="globe">
+Use this if your tool server is a **publicly accessible web service**. This approach uses OpenAI's hosted MCP tool capabilities.
+
+*   **When to use:** Your tool server is accessible from the internet and you want to leverage OpenAI's infrastructure for MCP connections.
+
+```python
+from agency_swarm import HostedMCPTool
+
+hosted_tool = HostedMCPTool(
+    tool_config={
+        "type": "mcp",
+        "server_label": "mcp-tools-server",
+        # For http servers:
+        "server_url": "https://your-server.com/mcp/",
+        # For sse servers
+        # "server_url": "https://your-server.com/sse/",
+        "require_approval": "never",
+        "headers": {
+            "Authorization": f"Bearer secret-token"
+        }
+    }
+)
+```
+
+<Note>
+Server specified in the HostedMCPTool should be publicly accessible for the agent to be able to use this tool
+</Note>
+</Accordion>
+
+## Connecting Agents to MCP Servers
+
+To give an agent access to MCP tools, you define the server connections and pass them to the agent's `mcp_servers` list or `tools` list during initialization. Follow these steps:
+
+<Accordion title="Step 1: Define Local Server Connections">
+Configure local MCP servers (stdio, local SSE, or streamable HTTP) that will run on your machine.
+
+```python
+from agents.mcp.server import MCPServerStdio, MCPServerStdioParams
+
+# Example: Stdio server for local tools
+stdio_server = MCPServerStdio(
+    MCPServerStdioParams(
+        command="python",
+        args=["./examples/utils/stdio_mcp_server.py"]
+    ),
+    cache_tools_list=True
+)
+```
+</Accordion>
+
+<Accordion title="Step 2: Define Hosted Server Tools (Optional)">
+Configure hosted MCP tools for publicly accessible servers.
+
+```python
+from agency_swarm import HostedMCPTool
+
+hosted_tool = HostedMCPTool(
+    tool_config={
+        "type": "mcp",
+        "server_label": "mcp-tools-server",
+        "server_url": "https://your-public-server.com/mcp/",
+        "require_approval": "never",
+        "headers": {
+            "Authorization": f"Bearer {os.getenv('APP_TOKEN', 'your-token')}"
+        }
+    }
+)
+```
+</Accordion>
+
+<Accordion title="Step 3: Initialize Agent with Servers">
+Pass the configured server connections to the appropriate parameter when creating your `Agent`.
+
+```python
+from agency_swarm import Agent
+
+# For local MCP servers, use mcp_servers parameter
+local_agent = Agent(
+    name="LocalMCPAgent",
+    description="An agent that can use local MCP tools.",
+    instructions="Use the available MCP tools to help users.",
+    mcp_servers=[stdio_server],  # Local servers go here
+    model="gpt-5.4-mini",
+)
+
+# For hosted MCP servers, use tools parameter
+hosted_agent = Agent(
+    name="HostedMCPAgent",
+    description="An agent that can use hosted MCP tools.",
+    instructions="Use the available hosted MCP tools to help users.",
+    tools=[hosted_tool],  # Hosted tools go here
+    model="gpt-5.4-mini",
+)
+```
+</Accordion>
+
+<Note>
+You can use `shared_mcp_servers` parameter inside agency to attach an MCP server to all agents at once.
+</Note>
+
+## Runnable Demo
+
+For a practical, runnable example using both local and hosted MCP servers, see the complete example above or the `mcp_server_example.py` script located in the `examples/` directory of the Agency Swarm repository.
+
+*   **Remember:** The demo requires you exposing port 8000 through ngrok prior to running it.
+
+## Key Takeaways
+
+*   MCP connects agents to external tools/data via standard protocols (Stdio, SSE, Streamable HTTP).
+*   Use mcp_server for local mcp servers and `HostedMCPTool` for web-based servers, since the latter allows you to avoid maintaining server lifecycle.
+*   External MCP servers must be running separately for the agent to connect to them.
+
+## See Also
+
+- [Agents SDK MCP guide](https://openai.github.io/openai-agents-python/mcp/)

docs/core-framework/tools/openapi-schemas.mdx

@@ -0,0 +1,116 @@
+---
+title: "OpenAPI Schemas"
+description: "Convert OpenAPI schemas into tools."
+icon: "brackets-curly"
+---
+
+Agency allows you to easily convert OpenAPI schemas into tools so your agents can interact with any external APIs. For example, by adding the Google Calendar API schema, your agent will be able to create, update, delete, and retrieve events from Google Calendar.
+
+<Tip>
+It is still recommended to create custom tools and wrap each API call into a `BaseTool` class, even if you have the OpenAPI schema. OpenAPI schemas allow you to get started quickly, however, for production, you might want to add some custom data validation, error handling, data processing or even combine multiple API calls into a single tool.
+</Tip>
+
+## How to Find OpenAPI Schemas
+
+The recommended way to create OpenAPI schemas is to use [Actions GPT](https://chatgpt.com/g/g-TYEliDU6A-actionsgpt). Simply ask it to create a schema for the API you want to use and which actions you want to perform.
+
+**If your API is public and well known**, it should be able to create a schema for you on the first try, without any extra documentation.
+
+```
+Create a schema for the Google Calendar API and include the following actions: create, update, delete, and get events.
+```
+
+**If your API is public but not well known**, we recommend searching for the API documentation manually and then sending a link to your API into the prompt:
+
+```
+Create a schema for the following API: https://api.example.com/openapi.json and include the following actions: create, update, delete, and get events.
+```
+
+**If you your API is private**, you can attach your API documentation in a file:
+
+```
+Create a schema for the API documentation attached in the file. Include the following actions: create, update, delete, and get events.
+```
+
+## How to Use OpenAPI Schemas
+
+Below are the two ways to use OpenAPI schemas in your agents:
+
+#### Option 1: Using the `schemas_folder`
+
+The first way to integrate OpenAPI schemas is by placing all your OpenAPI schema files in a folder, and then initializing your agent with the `schemas_folder` parameter. Agency Swarm will then automatically scan this folder and convert any OpenAPI schemas it finds into `BaseTool` instances.
+
+```python
+from agency_swarm import Agent
+
+agent = Agent(
+    name='MyAgent',
+    schemas_folder='schemas',
+    api_params={'api_schema.json': {'param1': 'value1'}},
+    api_headers={'api_schema.json': {'Authorization': 'Bearer token'}}
+)
+```
+
+In this example:
+
+- `schemas_folder`: Directory where your OpenAPI schema files are stored.
+- `api_params`: Extra parameters for specific schemas.
+- `api_headers`: Custom headers for API calls, like authentication tokens.
+
+
+
+#### Option 2: Using the ToolFactory Class
+
+Alternatively, you can use the `ToolFactory` class to convert OpenAPI schemas from local files or URLs.
+
+```python
+from agency_swarm.tools import ToolFactory
+
+tools = ToolFactory.from_openapi_schema(
+    "<your OpenAPI schema here>",
+    headers={'Authorization': 'Bearer token'},
+    params={'param1': 'value1'},
+    strict=False
+)
+```
+
+<Accordion title="Converting from a Local Schema File">
+```python
+from agency_swarm.tools import ToolFactory
+
+with open("schemas/api_schema.json") as f:
+    tools = ToolFactory.from_openapi_schema(f.read())
+```
+</Accordion>
+
+<Accordion title="Converting from a Remote Schema URL">
+```python
+from agency_swarm.tools import ToolFactory
+import requests
+
+response = requests.get("https://api.example.com/openapi.json")
+tools = ToolFactory.from_openapi_schema(response.json())
+```
+</Accordion>
+
+Argument descriptions:
+
+- `schema`: The OpenAPI schema to convert.
+- `headers`: HTTP headers applied to every request generated from the schema. For per-file mappings when using `Agent(schemas_folder=...)`, pass them via the agent's `api_headers` argument.
+- `params`: Query parameters appended to every request generated from the schema.
+- `strict`: Whether to use strict OpenAI mode.
+
+To add your tools to your agent with the 2nd option, simply pass the `tools` list to your agent:
+
+```python
+agent = Agent(
+    name='MyAgent',
+    tools=tools
+)
+```
+
+With this approach, you have more control over the tools you are adding to your agent, and you can still modify the `ToolConfig` of each tool. See the [ToolConfig documentation](/core-framework/tools/custom-tools/configuration) for more information.
+
+<Info>
+With any of these methods, Agency still converts your schemas into PyDantic models, so your agents will perform type checking on all API parameters **before** making API calls, reducing errors and improving reliability.
+</Info>

docs/core-framework/tools/overview.mdx

@@ -0,0 +1,121 @@
+---
+title: "Overview"
+description: "Understanding Tools in Agentic Systems."
+icon: "globe"
+---
+
+Tools are the most important component of any Agentic system. In this guide, we'll cover the basics: what tools are, key characteristics, and the three primary ways you can build or import your own tools.
+
+## Key Principles of Building Effective Tools
+
+Here are the key principles for building effective tools:
+
+<CardGroup cols={3}>
+  <Card
+    title="Standalone"
+    icon="cube"
+  >
+    Tools should run independently with minimal dependencies on other tools or agents. Any agent should be able to use any tool without extra re-prompting.
+  </Card>
+
+  <Card
+    title="Configurable"
+    icon="gear"
+  >
+    Tools should expose adjustable parameters. The agent should be able to tune modes, thresholds, timeouts, limits, etc to better fit the environment or the task at hand.
+  </Card>
+
+  <Card
+    title="Composable"
+    icon="hammer"
+  >
+    Outputs of one tool should match the inputs of another tool. They should allow the agent to compose them into workflows autonomously, instead of pre-defined sequences.
+  </Card>
+</CardGroup>
+
+## What are Tools?
+
+**At a high level, tools represent the capabilities that your agents have.**
+
+Tools enable your agents to perform specific tasks necessary to fulfill their designated roles. For instance, just as a real virtual assistant can search the web or send emails, the virtual assistant agent can be equipped with similar tools.
+
+Below are some more examples of tools:
+
+- **FileWriter:** A tool that allows an agent to write code or text to a file.
+- **CommandExecutor:** A tool that allows an agent to execute terminal commands.
+- **LeadUpdater:** A tool that allows an agent to update a lead in a CRM.
+- **LinkedInProfileScraper:** A tool that allows an agent to scrape a LinkedIn profile.
+- **FacebookAdCreator:** A tool that allows an agent to create a Facebook ad.
+
+
+<Tip>
+
+By themselves, each of these tools is not very useful, however in combination with each other, they allow agents to perform a much wider range of tasks.
+
+For example, `FileWriter` tool by itself can allow the developer agent to write code, however, in combination with the `CommandExecutor` tool, it can also run and test its own code, which instantly makes it more powerful. (We'll cover the key characteristics of tools in a bit.)
+</Tip>
+**At a low level, tools are essentially just code.**
+
+Whatever the tool you are creating, at the lowest level, it always comes down to code. The only difference is where this code is being executed. For instance, if you are making an API call, it will primarily be executed in the cloud, and if it's a file system tool, it will be executed on the same machine where the agent is running. **Even if you are using a no-code platform to build your tools, like n8n or zapier, at the lowest level, it all still comes down to code.**
+
+This means that agentic systems are much more similar to traditional software programs than you might think...
+
+<img className="block dark:hidden" src="/images/agents-vs-programs-light.png" alt="Tools Diagram" />
+<img className="hidden dark:block" src="/images/agents-vs-programs.png" alt="Tools Diagram" />
+
+Just as in a standard program, we have functions that are executed in a loop, in an agentic system, we have tools that are executed by your agents.
+
+And what this allows you to do, is tackle significantly more complex tasks. Tasks where there are so many possible paths that you can't hard code all of the possible conditional logic in advance.
+
+Now, that we understand what tools are, let's cover how you can build your own tools.
+
+
+## Built-in Tools
+
+Agency Swarm ships with several ready-to-use tools:
+
+- **IPythonInterpreter** - Execute Python code in an isolated environment
+- **PersistentShellTool** - Run shell commands with persistent state
+- **LoadFileAttachment** - Load and process local files (images, PDFs)
+
+```python
+from agency_swarm import IPythonInterpreter, PersistentShellTool, LoadFileAttachment
+```
+
+[Learn more about built-in tools →](/core-framework/tools/built-in-tools)
+
+## 3 Ways to Build Tools
+
+When it comes to building your own tools, you have 3 primary options:
+
+<CardGroup cols={3}>
+
+  <Card
+    title="Custom Tools"
+    icon="hammer"
+    href="./custom-tools"
+  >
+    Build your own completely custom tools from scratch. (Recommended)
+  </Card>
+
+  <Card
+    title="OpenAPI Schemas"
+    icon="file-code"
+    href="./openapi-schemas"
+  >
+    Use public OpenAPI schemas and convert them into tools.
+  </Card>
+
+  <Card
+    title="MCP Integration"
+    icon="plug"
+    href="./mcp-integration"
+  >
+    Connect to MCP servers for advanced capabilities.
+  </Card>
+
+</CardGroup>
+
+**It is recommended to start with custom tools**, as they give you the most flexibility and control. Even if you are connecting to external APIs, we still recommend creating custom tools, as they allow you to have more control over the tool's outputs.
+
+Click on the card of your choice to learn more about each one.

docs/docs.json

@@ -0,0 +1,250 @@
+{
+  "$schema": "https://mintlify.com/docs.json",
+  "theme": "maple",
+  "name": "Agency Swarm",
+  "colors": {
+    "primary": "#fcd53b",
+    "light": "#fcd53b",
+    "dark": "#B76E00"
+  },
+  "favicon": "/images/favicon.svg",
+  "navigation": {
+    "tabs": [
+      {
+        "tab": "Framework",
+        "global": {
+          "anchors": [
+            {
+              "anchor": "Discord Community",
+              "href": "https://discord.gg/cw2xBaWfFM",
+              "icon": "discourse"
+            },
+            {
+              "anchor": "Changelog",
+              "href": "https://github.com/VRSEN/agency-swarm/releases",
+              "icon": "timeline"
+            }
+          ]
+        },
+        "groups": [
+          {
+            "group": "Welcome",
+            "pages": [
+              "welcome/overview",
+              "welcome/ai-agency-vs-other-frameworks",
+              {
+                "group": "Get Started",
+                "icon": "rocket",
+                "pages": [
+                  "welcome/installation",
+                  "welcome/getting-started/starter-template",
+                  "welcome/getting-started/cursor-ide",
+                  "welcome/getting-started/from-scratch"
+                ]
+              }
+            ]
+          },
+          {
+            "group": "Core Framework",
+            "pages": [
+              {
+                "group": "Tools",
+                "icon": "wrench",
+                "pages": [
+                  "core-framework/tools/overview",
+                  "core-framework/tools/built-in-tools",
+                  {
+                    "group": "Custom Tools",
+                    "icon": "hammer",
+                    "pages": [
+                      "core-framework/tools/custom-tools/step-by-step-guide",
+                      "core-framework/tools/custom-tools/pydantic-is-all-you-need",
+                      "core-framework/tools/custom-tools/validation",
+                      "core-framework/tools/custom-tools/multimodal-outputs",
+                      "core-framework/tools/custom-tools/best-practices",
+                      "core-framework/tools/custom-tools/configuration"
+                    ]
+                  },
+                  "core-framework/tools/openapi-schemas",
+                  "core-framework/tools/mcp-integration"
+                ]
+              },
+              {
+                "group": "Agents",
+                "icon": "user",
+                "pages": [
+                  "core-framework/agents/overview",
+                  "core-framework/agents/built-in-tools",
+                  "core-framework/agents/advanced-configuration"
+                ]
+              },
+              {
+                "group": "Third-Party Agents",
+                "icon": "plug",
+                "pages": [
+                  "core-framework/third-party-agents/overview",
+                  "core-framework/third-party-agents/openclaw-agent"
+                ]
+              },
+              {
+                "group": "Agencies",
+                "icon": "sitemap",
+                "pages": [
+                  "core-framework/agencies/overview",
+                  "core-framework/agencies/communication-flows",
+                  "core-framework/agencies/running-agency",
+                  "core-framework/agencies/agent-swarm-cli",
+                  "core-framework/agencies/visualization"
+                ]
+              }
+            ]
+          },
+          {
+            "group": "Additional Features",
+            "pages": [
+              "additional-features/agency-context",
+              "additional-features/few-shot-examples",
+              {
+                "group": "Guardrails",
+                "icon": "shield-halved",
+                "pages": [
+                  "additional-features/guardrails/overview",
+                  "additional-features/guardrails/input-guardrails",
+                  "additional-features/guardrails/output-guardrails"
+                ]
+              },
+              "additional-features/streaming",
+              "additional-features/fastapi-integration",
+              "additional-features/mcp-tools-server",
+              {
+                "group": "Custom Communication Flows",
+                "icon": "comments",
+                "pages": [
+                  "additional-features/custom-communication-flows/overview",
+                  "additional-features/custom-communication-flows/common-use-cases"
+                ]
+              },
+              "additional-features/azure-openai",
+              "additional-features/third-party-models",
+              "additional-features/deployment-to-production",
+              "additional-features/observability"
+            ]
+          },
+          {
+            "group": "References",
+            "pages": ["references/api"]
+          },
+          {
+            "group": "Contributing",
+            "pages": ["contributing/contributing"]
+          },
+          {
+            "group": "Migration",
+            "pages": ["migration/guide"]
+          },
+          {
+            "group": "FAQ",
+            "pages": ["faq"]
+          }
+        ]
+      },
+      {
+        "tab": "Platform",
+        "global": {
+          "anchors": [
+            {
+              "anchor": "Agencii Platform",
+              "href": "https://agencii.ai/signup/",
+              "icon": "globe"
+            },
+            {
+              "anchor": "Skool Community",
+              "href": "https://www.skool.com/agency-ai/about",
+              "icon": "users"
+            }
+          ]
+        },
+        "groups": [
+          {
+            "group": "Introduction",
+            "pages": ["platform/overview", "platform/pricing", "platform/how-credits-work"]
+          },
+          {
+            "group": "Integrations",
+            "pages": [
+              "platform/integrations/slack-integration",
+              "platform/integrations/whatsapp-integration",
+              "platform/integrations/zapier-integration",
+              "platform/integrations/n8n-integration",
+              "platform/integrations/web-api",
+              "platform/integrations/widget"
+            ]
+          },
+          {
+            "group": "Marketplace",
+            "icon": "store",
+            "pages": [
+              "platform/marketplace/openclaw",
+              "platform/marketplace/onboarding"
+            ]
+          },
+          {
+            "group": "Additional Features",
+            "pages": ["platform/additional-instructions"]
+          }
+        ],
+        "openapi": {
+          "source": "/openapi.json",
+          "directory": "platform/integrations/api"
+        }
+      },
+      {
+        "tab": "Extras",
+        "groups": [
+          {
+            "group": "Extras",
+            "pages": ["extras/extras"]
+          },
+          {
+            "group": "Tutorials",
+            "pages": ["tutorials/tutorials"]
+          }
+        ]
+      }
+    ]
+  },
+  "logo": {
+    "light": "/images/logo-light.svg",
+    "dark": "/images/logo-dark.svg",
+    "href": "https://agency-swarm.ai"
+  },
+  "appearance": {
+    "default": "dark",
+    "strict": false
+  },
+  "background": {
+    "color": {
+      "dark": "#0C102D"
+    }
+  },
+  "navbar": {
+    "primary": {
+      "type": "github",
+      "href": "https://github.com/VRSEN/agency-swarm"
+    }
+  },
+  "search": {
+    "prompt": "Search Agency Swarm docs"
+  },
+  "seo": {
+    "indexing": "navigable"
+  },
+  "footer": {
+    "socials": {
+      "website": "https://vrsen.ai",
+      "x": "https://x.com/__vrsen__",
+      "github": "https://github.com/VRSEN/agency-swarm",
+      "youtube": "https://youtube.com/@vrsen"
+    }
+  }
+}

docs/extras/extras.mdx

@@ -0,0 +1,36 @@
+---
+title: Agency Swarm Extras
+description: Additional resources and repositories for Agency Swarm.
+icon: plus
+---
+
+Explore additional repositories to enhance your Agency Swarm experience.
+
+<CardGroup cols={3}>
+  <Card
+    title="Official Examples Library"
+    href="https://github.com/VRSEN/agency-swarm/tree/main/examples"
+    icon="flask"
+    iconType="duotone"
+  >
+    Explore production-ready demos maintained in the core repo.
+  </Card>
+
+  <Card
+    title="API Railway Template"
+    href="https://github.com/VRSEN/agency-swarm-api-railway-template"
+    icon="train"
+    iconType="duotone"
+  >
+    Deploy your agency using the API Railway Template.
+  </Card>
+
+  <Card
+    title="Voice Interface"
+    href="https://github.com/VRSEN/agency-voice-interface"
+    icon="microphone"
+    iconType="duotone"
+  >
+    Integrate voice commands with the Agency Voice Interface.
+  </Card>
+</CardGroup>

docs/faq.mdx

@@ -0,0 +1,125 @@
+---
+title: "FAQ"
+description: "Find answers to common questions about Agency Swarm."
+icon: "question"
+---
+
+<AccordionGroup defaultOpen={true}>
+
+
+<Accordion title="How do I set my OpenAI API key in my project?" icon="key">
+Set your API key in your code:
+```python
+from agency_swarm import set_openai_key
+set_openai_key("YOUR_API_KEY")
+```
+Or use a `.env` file:
+```env
+OPENAI_API_KEY=sk-1234...
+```
+Then load it with:
+```python
+from dotenv import load_dotenv
+load_dotenv()
+```
+</Accordion>
+
+<Accordion title="Can I use open source models with Agency Swarm?" icon="code-fork">
+Yes—you can use third-party models for simple, non–mission-critical tasks (usually one or two tools per agent). See [Third-Party Models](/additional-features/third-party-models) for more information. Keep in mind that many third-party models currently struggle with function calling.
+</Accordion>
+
+
+<Accordion title="How do I save and continue conversations?" icon="messages">
+To persist conversations between application restarts, implement callbacks that save and load the full message history from a local file. For example, define your callback functions:
+
+```python
+import os
+import json
+
+def load_threads(chat_id: str) -> list[dict[str, TResponseInputItem]]:
+    """Load all threads data for a specific chat session."""
+    if os.path.exists(f"{chat_id}_threads.json"):
+        with open(f"{chat_id}_threads.json", "r") as file:
+            return json.load(file)
+    return []
+
+def save_threads(thread_dict: list[dict[str, TResponseInputItem]], chat_id: str):
+    """Save all threads data to file."""
+    with open(f"{chat_id}_threads.json", "w") as file:
+        json.dump(thread_dict, file)
+
+# Then, pass these callbacks during your agency initialization to resume conversations:
+from agency_swarm import Agency
+agency = Agency(
+    agent,
+    load_threads_callback=lambda: load_threads(chat_id),
+    save_threads_callback=lambda thread_dict: save_threads(thread_dict, chat_id),
+)
+```
+
+This setup preserves your conversation context between runs.
+</Accordion>
+
+
+<Accordion title="How do I manage multiple users with Agency Swarm?" icon="users">
+To support multiple users/chats, you need to load and save thread IDs in your database accordingly. Each chat/user should have unique thread IDs. Ensure to check out our [Deployment to Production](/additional-features/deployment-to-production) guide for more information.
+</Accordion>
+
+
+<Accordion title="How can I transfer data between tools and agents?" icon="upload">
+There are two ways to transfer data between tools and agents:
+1. Use agency context inside your tools. Read more: [Agency Context](/additional-features/agency-context)
+2. Create a tool (or modify an existing one) that uploads files to storage and outputs the file ID. This file ID can then be used by other tools or agents.
+</Accordion>
+
+
+<Accordion title="Why is the CodeInterpreter tool automatically added?" icon="code">
+When file types like `.json`, `.docx`, or `.pptx` are uploaded, CodeInterpreter is auto-added to process them. To change the agent's behavior, update its instructions or create a custom file-handling tool.
+</Accordion>
+
+
+<Accordion title="How can I serve an Agency as an API using FastAPI?" icon="book">
+Embed your agency within a FastAPI endpoint:
+
+```python
+from fastapi import FastAPI
+from uuid import uuid4
+
+app = FastAPI()
+
+@app.post("/chat")
+async def chat(user_request: UserRequest):
+    chat_id = user_request.chat_id or str(uuid4())
+
+    agency = Agency(
+        agent,
+        load_threads_callback=lambda: load_threads(chat_id),
+        save_threads_callback=lambda thread_dict: save_threads(thread_dict, chat_id)
+    )
+
+    response = await agency.get_response(user_request.message)
+    return {"chat_id": chat_id, "response": response.final_output}
+
+# Or use the built-in FastAPI integration
+agency.run_fastapi(host="0.0.0.0", port=8000)
+```
+</Accordion>
+
+
+<Accordion title="How do I deploy my agency to production?" icon="rocket">
+Build a dedicated API backend (FastAPI is recommended) that manages authentication and persists thread state using callbacks. For more details, refer to our [Deployment to Production](/additional-features/deployment-to-production) guide.
+</Accordion>
+
+</AccordionGroup>
+
+
+## Getting Support
+
+<CardGroup cols={2}>
+  <Card title="Community Support" icon="discord" href="https://discord.gg/cw2xBaWfFM">
+    Join our Discord community for quick help and discussions.
+  </Card>
+  <Card title="Professional Services" icon="briefcase" href="https://agents.vrsen.ai/">
+    Get professional help with our Agents-as-a-Service subscription.
+  </Card>
+</CardGroup>

docs/images/agencii-logo.svg

@@ -0,0 +1,9 @@
+<svg width="33" height="31" viewBox="0 0 33 31" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M10.8626 0.886963L15.73 3.69717V9.3176L10.8626 12.1278L5.99518 9.3176V3.69717L10.8626 0.886963Z" fill="#FCD53B"/>
+<path d="M10.8626 18.8723L15.73 21.6825V27.3029L10.8626 30.1132L5.99518 27.3029V21.6825L10.8626 18.8723Z" fill="#FCD53B"/>
+<path d="M5.62042 9.87964L10.4879 12.6898V18.3103L5.62042 21.1205L0.752994 18.3103V12.6898L5.62042 9.87964Z" fill="#FCD53B"/>
+<path d="M16.1126 9.87964L20.98 12.6898V18.3103L16.1126 21.1205L11.2452 18.3103V12.6898L16.1126 9.87964Z" fill="#FCD53B"/>
+<path d="M26.6048 9.87964L31.4722 12.6898V18.3103L26.6048 21.1205L21.7374 18.3103V12.6898L26.6048 9.87964Z" fill="#FCD53B"/>
+<path d="M21.3548 0.886963L26.2222 3.69717V9.3176L21.3548 12.1278L16.4874 9.3176V3.69717L21.3548 0.886963Z" fill="#FCD53B"/>
+<path d="M21.3548 18.8723L26.2222 21.6825V27.3029L21.3548 30.1132L16.4874 27.3029V21.6825L21.3548 18.8723Z" fill="#FCD53B"/>
+</svg>

docs/images/favicon.svg

@@ -0,0 +1,9 @@
+<svg version="1.2" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 129 118" width="129" height="118">
+	<title>LOGO</title>
+	<defs>
+		<image  width="123" height="115" id="img1" href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAHsAAABzCAMAAACPSo0gAAAAAXNSR0IB2cksfwAAAGlQTFRFAAAA/99A/NY9+9c8/dU7/NU7+tU6/NY7/NU7/9dA/dY7/dc6/dY5/NQ7/NU6+to6/9c4/NU7/dU7/NU6+tY5/NU7+tQ7+tQ7/NU8/dY7/NY8+9M8+9M8/NY6/dU8/89A+9Q8/NI9+9M87TX8KgAAACN0Uk5TABBQQN//ML+fII9/b+9gMCDvz69w36Bwr9+/QICvzxCQUJCWxnKfAAADUUlEQVR4nO2bfW/TMBCH64R2tMlKgI4irdI0vv93YggqNFE0jakv62hMYqeJ7dzZ561ISNz9tS2P/Nt8ydp7kooBrYQoT0/SsFQIWZLWTBIh5eF02SP9p6RiGyLTV1SSli3GT+0vUXrXNMmNPEF2LnbdN3LyCyezhErSsqtG2z+Q2T2VHAY23p9dbIHzC2wmnaRli8kePjBau2TXaKvyvUsSs61G2+U0k07SspurBavzbbud6ZsHH5kk2MYj2UUaPEubZoKNBklitnW1YCWLVQxJzR6G16uq+BFDcjZnczZnczZnczZnczZnvzT7wx1hwXx0G0NSswfF65+hBaebLZGMmA20MJlm4Pv5Y12IZTwZzK6FiRrgFgd0Tb2J082RvEeHk/xQA1O5A4ZCN7sZAT+uqm0qRkgz50tpqxWMzDOXxLONOVqvOf3eX/Dirjoizg42OQY2SZHFriWH0kq3sgFh0mvmLKnbNyGQ52OEBLL7wkQZtYV5feTZN5CsjdrVwSLVKVGdPA5p6Jr2EC5MjGZefpGtbSOQoD/o2t5kY8JEG7XRe7Wd+mpBydqoXZaaXO195NrMDgqTqpmq0RGkxwo0ba+zA8JEtah4eyOBRjtkbdSK8iFMKl0jIoTJqUlBEiaqRSRSGbUM8XJWyTNBexEcPP2FF1bO5mzO5mzO5mzO5mzO5mw0ewGqEKfUCEgj6xHw01cSKfAJv6ujWgmTx9mAQD7KenJpBjisDGFyvTuphFFfekg9R1cjIDLhG6RSKy05T1Bytm5nwaqKd0iLTLWi7qKT1IpX12hyYM7+EKmFSXcfXk/4kFGDyQngE5uTZ2A5D5JaUXfR6WqlR6pG97OdFmHCpG/UWtvmkFrX9EkwO0KYPIucL60HjVw70Bg1vzBRnqwxaq5ts0vpGpP0ZccIkyNpN9pHhrKr/yAUtaKeUbv+PAiTta65+t1Lxh02Wa2Atg0kidkTpNF21RKGTlKz/9f7JZzN2ZzN2ZzN2ZzN2Zz9b2fT1QqdpGZThIkaAWNIajZNwugKSZgVdmfWM0p51MrstqSS/RGQko1KmFaYdGRIrURnI2vCn22BJEz66P1QUegzPV5h8kySmg1KGKSsB6C0bXthtrHx/vbFkKr+AEKHIoLilS2ZAAAAAElFTkSuQmCC"/>
+	</defs>
+	<style>
+	</style>
+	<use id="Background" href="#img1" x="3" y="3"/>
+</svg>