# https://github.com/VRSEN/agency-swarm 项目说明书
生成时间：2026-05-15 11:07:28 UTC
## 目录
- [Introduction to Agency Swarm](#page-introduction)
- [Installation and Setup](#page-installation)
- [Getting Started Guide](#page-getting-started)
- [Core Architecture](#page-core-architecture)
- [Agent Internals](#page-agent-internal)
- [Tools System](#page-tools-system)
- [Communication Flows](#page-communication-flows)
- [Context Management](#page-context-management)
- [Messaging System](#page-messaging-system)
- [File Management](#page-file-management)
## Introduction to Agency Swarm
### 相关页面
相关主题：[Installation and Setup](#page-installation), [Getting Started Guide](#page-getting-started), [Core Architecture](#page-core-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)
- [examples/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)
- [examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)
- [src/agency_swarm/agent/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)
- [src/agency_swarm/utils/create_agent_template.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/utils/create_agent_template.py)
- [CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)
- [src/agency_swarm/integrations/README.md](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/integrations/README.md)
# Introduction to Agency Swarm
Agency Swarm is a multi-agent orchestration framework designed for building autonomous AI agent systems that can collaborate, communicate, and delegate tasks between specialized agents. The framework enables developers to create complex workflows where multiple AI agents work together to accomplish tasks that require diverse capabilities.
## Overview
Agency Swarm provides a structured approach to building multi-agent systems with the following core capabilities:
- **Agent Definition**: Create specialized agents with specific roles, instructions, and tools
- **Inter-Agent Communication**: Enable agents to communicate and transfer control via handoffs
- **Tool Integration**: Support for custom tools, OpenAPI schema conversion, and built-in capabilities
- **Agency Management**: Orchestrate multiple agents within an agency context
- **User Interfaces**: Multiple UI options including Terminal UI (TUI), Copilot UI, and visualization
资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)
## Architecture Overview
The framework is built around two primary concepts: **Agents** and **Agencies**. Agents represent individual AI workers with specific responsibilities, while Agencies coordinate multiple agents to accomplish complex tasks.
```mermaid
graph TD
A[User] --> B[Agency]
B --> C[CEO Agent]
C --> D[Developer Agent]
C --> E[Support Agent]
D --> F[Custom Tools]
E --> G[WebSearch Tool]
D --> H[File Management]
E --> D
```
资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)
### Core Components
| Component | Description | Location |
|-----------|-------------|----------|
| Agent | Base class for all agents with core execution methods | `src/agency_swarm/agent/core.py` |
| Agency | Orchestrates multiple agents and their communication | Main orchestration layer |
| Tool | Base class for custom tools and decorators | Tool infrastructure |
| ModelSettings | Configuration for model parameters | Configuration layer |
## Creating Agents
Agents are the fundamental building blocks of Agency Swarm. Each agent has a name, description, instructions, tools, and model configuration.
### Agent Folder Structure
```
AgentName/
├── files/ # Files to upload to OpenAI
├── schemas/ # OpenAPI schemas for tool generation
├── tools/ # Agent-specific tools
├── AgentName.py # Main agent class
├── __init__.py # Package initialization
└── instructions.md # Agent instruction document
```
资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)
### Agent Implementation Example
```python
from agency_swarm import Agent, ModelSettings
from agency_swarm.tools.example import ExampleTool
class SupportAgent(Agent):
def __init__(self):
super().__init__(
name="SupportAgent",
description="Handles customer support requests",
instructions="./instructions.md",
files_folder="./files",
tools=[ExampleTool],
model="gpt-5.4-mini",
model_settings=ModelSettings(
temperature=0.3,
max_tokens=25000,
),
)
```
资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)
### Agent Core Methods
The `Agent` class provides several core execution methods for handling interactions:
| Method | Description |
|--------|-------------|
| `get_response()` | Async method for running agent turns in conversation loop |
| `get_response_sync()` | Synchronous wrapper for `get_response()` |
| `upload_file()` | Upload files using the agent's file manager |
资料来源：[src/agency_swarm/agent/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)
## Tools System
Agency Swarm supports multiple tool definition patterns to give agents capabilities beyond plain text generation.
### Tool Definition Patterns
| Pattern | Description | Use Case |
|---------|-------------|----------|
| `@function_tool` decorator | Lightweight function-based tool | Quick tool definitions |
| `BaseTool` subclass | Full Pydantic-based tool | Complex tools with validation |
| `ToolFactory` | OpenAPI schema conversion | API integration |
### BaseTool Implementation
```python
from agency_swarm.tools import BaseTool
from pydantic import Field
class MyCustomTool(BaseTool):
example_field: str = Field(
..., description="Description of the example field"
)
def run(self):
return f"Result: {self.example_field}"
```
资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)
### OpenAPI Schema Conversion
```python
from agency_swarm.tools import ToolFactory
with open("schemas/your_schema.json") as f:
tools = ToolFactory.from_openapi_schema(f.read())
```
资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)
## Agency Structure
The Agency class orchestrates multiple agents and defines how they communicate with each other.
### Defining an Agency
```python
from agency_swarm import Agency, Agent
ceo = Agent(name="CEO", ...)
developer = Agent(name="Developer", ...)
support = Agent(name="Support", ...)
agency = Agency(
ceo,
developer,
support,
communication_flows=[
(ceo, developer), # CEO can delegate to Developer
(ceo, support), # CEO can delegate to Support
(support, developer), # Support can handoff to Developer
],
shared_instructions="Agency-wide guidelines",
)
```
### Communication Flows
Communication flows define the allowed message paths between agents. The framework supports two primary communication patterns:
| Pattern | Description |
|---------|-------------|
| `SendMessage` | Direct message passing between agents |
| `Handoff` | Transfer of control to another agent |
资料来源：[examples/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)
## User Interfaces
Agency Swarm provides multiple UI options for interacting with agencies.
### Available UIs
| UI Type | Description | Location |
|---------|-------------|----------|
| Terminal UI (TUI) | Command-line chat interface | `examples/interactive/tui.py` |
| Copilot UI | Next.js-based copilot interface | `src/agency_swarm/ui/demos/copilot/` |
| Visualization | HTML-based agency visualization | `src/agency_swarm/ui/templates/` |
| FastAPI | REST API integration | `src/agency_swarm/integrations/` |
### Terminal UI Example
```python
if __name__ == "__main__":
create_demo_agency().tui(show_reasoning=True)
```
资料来源：[examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)
## Running the Agency
### Synchronous Execution
```python
agency = Agency(ceo, developer, support)
response = agency.get_response_sync("Create a project skeleton")
```
### Asynchronous Execution
```python
import asyncio
async def main():
resp = await agency.get_response("Create a project skeleton")
print(resp.final_output)
asyncio.run(main())
```
资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)
## Model Configuration
Agents can be configured with specific model settings for fine-tuned control over generation behavior.
### ModelSettings Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `temperature` | float | 0.3 | Sampling temperature (0-2) |
| `max_tokens` | int | None | Maximum tokens in response |
| `top_p` | float | None | Nucleus sampling parameter |
| `reasoning` | Reasoning | None | Reasoning effort for reasoning models |
### Reasoning Models
For reasoning models (like o1 series), the framework automatically handles compatibility:
- Temperature parameter is disabled for reasoning models
- Reasoning effort can be configured via `ModelSettings(reasoning=Reasoning(effort="low"))`
资料来源：[src/agency_swarm/utils/create_agent_template.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/utils/create_agent_template.py)
## Integration with External Services
Agency Swarm supports integration with external frameworks like FastAPI and OpenClaw.
### FastAPI Integration
```python
from agency_swarm.integrations.fastapi import run_fastapi
app = run_fastapi(
agencies={"my_agency": create_agency},
app_token_env="APP_TOKEN",
return_app=True,
)
```
资料来源：[src/agency_swarm/integrations/README.md](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/integrations/README.md)
## Example Workflow
```mermaid
sequenceDiagram
participant User
participant Agency
participant CEO
participant Developer
participant Support
User->>Agency: Initial Request
Agency->>CEO: Process Request
CEO->>Support: Route to Support
Support->>CEO: Needs Development
CEO->>Developer: Delegate Task
Developer-->>CEO: Task Complete
CEO-->>Agency: Final Response
Agency-->>User: Response
```
## Key Features Summary
| Feature | Description |
|---------|-------------|
| Multi-Agent Orchestration | Coordinate multiple specialized agents |
| Inter-Agent Communication | Built-in message passing and handoffs |
| Tool System | Custom tools, OpenAPI conversion, built-in tools |
| Model Flexibility | Support for various OpenAI models |
| UI Options | TUI, Copilot, Visualization, FastAPI |
| File Management | Vector stores and file search capabilities |
| Streaming | Real-time response streaming |
| Guardrails | Input and output validation |
资料来源：[examples/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)
## Getting Started
1. Install Agency Swarm: `pip install agency-swarm`
2. Create your first agent with the CLI: `agency-swarm create-agent`
3. Define tools and instructions
4. Compose agents into an agency
5. Run the agency with `get_response_sync()` or async `get_response()`
---
## Installation and Setup
### 相关页面
相关主题：[Introduction to Agency Swarm](#page-introduction), [Getting Started Guide](#page-getting-started)
相关源码文件
以下源码文件用于生成本页说明：
- [CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)
- [src/agency_swarm/cli/main.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/cli/main.py)
- [src/agency_swarm/utils/create_agent_template.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/utils/create_agent_template.py)
- [examples/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)
- [README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)
# Installation and Setup
This guide covers how to install Agency Swarm, configure your development environment, and set up your first multi-agent project.
## Prerequisites
Before installing Agency Swarm, ensure you have the following:
| Requirement | Version | Notes |
|-------------|---------|-------|
| Python | 3.10+ | Required for async/await support |
| pip / uv | Latest | Package manager |
| OpenAI API Key | - | Set as environment variable |
| Git | - | For cloning and version control |
## Installation Methods
### From PyPI (Recommended)
```bash
pip install agency-swarm
```
### From Source
```bash
git clone https://github.com/VRSEN/agency-swarm.git
cd agency-swarm
pip install -e .
```
### Development Installation
For contributors working on Agency Swarm itself:
```bash
git clone https://github.com/VRSEN/agency-swarm.git
cd agency-swarm
pip install -e ".[dev]"
```
资料来源：[CONTRIBUTING.md:1-20]()
## Environment Configuration
### Required Environment Variables
| Variable | Description | Required |
|----------|-------------|----------|
| `OPENAI_API_KEY` | Your OpenAI API key | Yes |
```bash
export OPENAI_API_KEY="sk-your-key-here"
```
For persistent configuration, add this to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.).
### Optional Configuration
| Variable | Default | Description |
|----------|---------|-------------|
| `OPENAI_BASE_URL` | OpenAI default | Custom API endpoint |
| `AGENCY_SWARM_LOG_LEVEL` | `INFO` | Logging verbosity |
## CLI Installation and Setup
Agency Swarm provides a command-line interface for agent creation and management.
### Verify CLI Installation
```bash
agency-swarm --version
```
### CLI Command Reference
资料来源：[src/agency_swarm/cli/main.py:1-50]()
| Command | Description |
|---------|-------------|
| `agency-swarm create-agent` | Scaffold a new agent template |
| `agency-swarm migrate-agent` | Generate agent from Assistants API settings.json |
| `agency-swarm import-tool` | Import built-in tools into project |
#### Create Agent Command Options
```bash
agency-swarm create-agent [AGENT_NAME] [options]
```
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `--model` | string | `gpt-5.4` | Model identifier |
| `--reasoning` | string | - | Reasoning effort level |
| `--max-tokens` | int | - | Maximum completion tokens |
| `--temperature` | float | `0.3` | Sampling temperature (non-reasoning models only) |
| `--instructions` | string | - | Custom instructions for agent |
| `--use-txt` | flag | False | Use .txt instead of .md for instructions |
| `--path` | string | `./` | Output directory for agent template |
资料来源：[src/agency_swarm/utils/create_agent_template.py:1-40]()
#### Migrate Agent Command
```bash
agency-swarm migrate-agent path_to_settings.json [--output-dir DIR]
```
This converts an OpenAI Assistant configuration into an Agency Swarm agent definition.
资料来源：[src/agency_swarm/cli/main.py:80-95]()
## Project Structure Setup
When creating a new agent using the CLI, the following structure is generated:
```
agency_swarm/agents/AgentName/
├── AgentName/
│ ├── files/ # Files uploaded to OpenAI
│ ├── tools/ # Agent-specific tools
│ ├── schemas/ # OpenAPI schemas
│ ├── AgentName.py # Main agent class
│ ├── __init__.py # Package initialization
│ └── instructions.md # Agent instructions
```
资料来源：[CONTRIBUTING.md:60-75]()
### Agent Template Example
```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],
)
```
资料来源：[CONTRIBUTING.md:1-15]()
## Tool Installation
Agency Swarm provides pre-built tools that can be imported into your project.
### List Available Tools
```bash
agency-swarm import-tool --list
```
### Import a Tool
```bash
agency-swarm import-tool ToolName [--directory ./tools]
```
Tools are organized by category in the `agency_swarm/tools/` directory:
```
agency_swarm/tools/{category}/
├── YourNewTool.py
└── __init__.py
```
资料来源：[CONTRIBUTING.md:40-55]()
## Development Dependencies
### Install Dev Dependencies
```bash
make sync
```
### Run Test Suite
```bash
make coverage
```
The `make coverage` command runs the test suite with coverage reporting.
资料来源：[CONTRIBUTING.md:25-35]()
## Quick Start: Your First Agency
```mermaid
graph TD
A[Install agency-swarm] --> B[Set OPENAI_API_KEY]
B --> C[Create Agent Templates]
C --> D[Define Communication Flows]
D --> E[Initialize Agency]
E --> F[Run get_response]
```
### Complete Example
```python
from agency_swarm import Agency, Agent
from agency_swarm.tools import WebSearchTool
# Create agents
support = Agent(
name="SupportAgent",
description="Handles user inquiries",
instructions="You are a helpful support agent.",
tools=[WebSearchTool()],
model="gpt-5.4-mini",
)
# Initialize agency
agency = Agency(support)
# Run
result = agency.get_response_sync("Hello!")
```
资料来源：[examples/README.md:1-20]()
## Troubleshooting
### Common Installation Issues
| Issue | Solution |
|-------|----------|
| `ModuleNotFoundError` | Reinstall: `pip install agency-swarm` |
| Python version error | Ensure Python 3.10+ with `python --version` |
| API key not found | Verify `OPENAI_API_KEY` environment variable |
### Verify Installation
```python
import agency_swarm
print(agency_swarm.__version__)
```
### Running Examples
Examples are located in the `examples/` directory. Each can be run directly:
```bash
cd examples
python multi_agent_workflow.py
```
资料来源：[examples/README.md:1-30]()
## Next Steps
After installation, explore:
- [Getting Started Guide](/docs/getting-started/from-scratch.mdx) - Build your first agency
- [Agent Communication](/docs/features/communication.mdx) - Configure agent-to-agent messaging
- [Tool Development](/docs/features/tools.mdx) - Create custom tools
- [FastAPI Integration](/docs/additional-features/fastapi-integration.mdx) - Deploy as API service
---
## Getting Started Guide
### 相关页面
相关主题：[Introduction to Agency Swarm](#page-introduction), [Installation and Setup](#page-installation), [Core Architecture](#page-core-architecture), [Tools System](#page-tools-system)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)
- [examples/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)
- [CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)
- [examples/tools.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/tools.py)
- [examples/multi_agent_workflow.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/multi_agent_workflow.py)
- [examples/agency_visualization.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_visualization.py)
- [examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)
- [src/agency_swarm/utils/create_agent_template.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/utils/create_agent_template.py)
# Getting Started Guide
Welcome to the Agency Swarm Getting Started Guide. This guide provides comprehensive instructions for setting up your development environment, understanding the project structure, and building your first multi-agent application using the Agency Swarm framework.
## Overview
Agency Swarm is a framework for building multi-agent systems that enables multiple AI agents to collaborate through defined communication flows. The framework provides tools for creating agents, defining their capabilities through tools, establishing communication patterns between agents, and visualizing agent hierarchies.
This guide covers the essential steps from initial environment setup to running your first multi-agent workflow, with practical examples drawn from the repository's example implementations.
## Prerequisites
Before beginning with Agency Swarm, ensure your development environment meets the following requirements:
| Requirement | Minimum Version | Notes |
|-------------|-----------------|-------|
| Python | 3.10+ | Required for type hints and async features |
| pip | Latest | For dependency management |
| Git | Any recent version | For cloning the repository |
| OpenAI API Key | Valid key | Required for agent execution |
## Environment Setup
### Cloning the Repository
Begin by cloning the Agency Swarm repository to your local machine:
```bash
git clone https://github.com/VRSEN/agency-swarm.git
cd agency-swarm
```
资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)
### Creating a Virtual Environment
Creating an isolated Python environment is recommended to avoid dependency conflicts:
```bash
python3 -m venv venv
source venv/bin/activate # On Windows use `venv\Scripts\activate`
```
资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)
### Installing Dependencies
Agency Swarm uses a Makefile for dependency management. Install all required packages with the sync command:
```bash
make sync
```
This command installs both runtime and development dependencies, including pre-commit hooks for code quality checks. To also install pre-commit hooks manually:
```bash
pip install pre-commit
pre-commit install
```
资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)
## Project Structure
Understanding the Agency Swarm directory structure is essential for effective development:
```mermaid
graph TD
A[agency-swarm Root] --> B[examples/]
A --> C[src/agency_swarm/]
A --> D[agency_swarm/]
B --> B1[Core Examples]
B --> B2[interactive/]
B --> B3[fastapi_integration/]
C --> C1[agent/]
C --> C2[tools/]
C --> C3[cli/]
C --> C4[ui/]
D --> D1[agents/]
D --> D2[tools/]
```
### Key Directories
| Directory | Purpose |
|-----------|---------|
| `examples/` | Runnable example scripts demonstrating various features |
| `examples/interactive/` | Interactive UI demos including TUI and copilot interfaces |
| `examples/fastapi_integration/` | FastAPI server and client examples |
| `src/agency_swarm/` | Core framework source code |
| `agency_swarm/` | User-defined agents and custom tools |
### Recommended Agent Folder Structure
Each agent should follow a consistent folder structure:
```
AgentName/
├── files/ # Files to be uploaded to OpenAI
├── schemas/ # OpenAPI schemas for tool generation
├── tools/ # Agent-specific tool definitions
├── AgentName.py # Main agent class
├── __init__.py # Package initialization
└── instructions.md # Agent instruction document
```
资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)
## Creating Your First Agent
### Using the CLI Template Generator
Agency Swarm provides a CLI command to scaffold agent templates automatically:
```bash
agency-swarm create-agent AgentName --model gpt-5.4-mini
```
The CLI supports the following parameters:
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `--name` | string | (prompt) | Name of the agent |
| `--description` | string | (prompt) | Agent description |
| `--model` | string | gpt-5.4 | Model to use |
| `--temperature` | float | 0.3 | Sampling temperature (not for reasoning models) |
| `--reasoning` | string | null | Reasoning effort for reasoning models |
| `--instructions` | string | null | Custom instructions |
| `--path` | string | ./ | Output directory |
资料来源：[src/agency_swarm/cli/main.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/cli/main.py)
### Manual Agent Definition
Alternatively, define agents programmatically using the Agent class:
```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.",
files_folder="./files",
schemas_folder="./schemas",
tools=[my_custom_tool],
model="gpt-5.4-mini",
model_settings=ModelSettings(
max_tokens=25000,
),
)
```
资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)
## Defining Tools
Agency Swarm supports multiple tool definition patterns.
### Function Tool with Decorator
The simplest approach uses the `@function_tool` decorator:
```python
from agency_swarm import function_tool
@function_tool
def calculate(a: int, b: int) -> int:
"""A brief description of what the custom tool does."""
return a + b
```
资料来源：[examples/tools.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/tools.py)
### BaseTool Class
For more complex tools with validation, use the `BaseTool` class:
```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.
"""
example_field: str = Field(
..., description="Description of the example field"
)
def run(self):
return "Result of MyCustomTool operation"
```
资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)
### OpenAPI Schema to Tools
Convert existing OpenAPI schemas into Agency Swarm tools:
```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 remote URL
import requests
tools = ToolFactory.from_openapi_schema(
requests.get("https://api.example.com/openapi.json").json()
)
```
资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)
## Building Multi-Agent Workflows
### Defining Communication Flows
Agents communicate through defined flows using `SendMessage` and `Handoff`:
```python
from agency_swarm import Agency, Agent, SendMessage, Handoff
ceo = Agent(name="CEO", ...)
developer = Agent(name="Developer", ...)
manager = Agent(name="Manager", ...)
agency = Agency(
ceo, # Entry point agent
communication_flows=[
(ceo > developer, SendMessage), # CEO sends to Developer
(developer < manager), # Bidirectional with handoff
(developer > ceo, Handoff), # Developer hands off to CEO
]
)
```
资料来源：[examples/multi_agent_workflow.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/multi_agent_workflow.py)
### Communication Flow Syntax
| Syntax | Meaning |
|--------|---------|
| `(agent_a > agent_b)` | A sends to B with default SendMessage |
| `(agent_a > agent_b, SendMessage)` | Explicit SendMessage tool |
| `(agent_a < agent_b)` | Bidirectional communication |
| `(agent_a < agent_b, Handoff)` | Bidirectional with handoff |
| `(a < b > c)` | Multi-agent pattern |
### Running the Agency
Execute the agency asynchronously:
```python
import asyncio
async def main():
resp = await agency.get_response("Create a project skeleton.")
print(resp.final_output)
asyncio.run(main())
```
For synchronous execution:
```python
resp = agency.get_response_sync("Create a project skeleton.")
```
资料来源：[README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)
## Running Examples
The repository includes numerous runnable examples demonstrating key features:
### Available Example Scripts
| Example | Purpose |
|---------|---------|
| `multi_agent_workflow.py` | Multi-agent collaboration with validation |
| `agency_context.py` | Data sharing between agents |
| `streaming.py` | Real-time streaming responses |
| `guardrails.py` | Input and output validation |
| `tools.py` | Tool patterns with BaseTool and @function_tool |
| `agent_file_storage.py` | Vector store and FileSearch tool usage |
| `message_attachments.py` | File processing in messages |
| `custom_send_message.py` | Custom SendMessage configurations |
资料来源：[examples/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)
### Running an Example
Navigate to the examples directory and run any example script:
```bash
cd examples
python multi_agent_workflow.py
```
## Interactive Interfaces
Agency Swarm provides multiple interactive UI options.
### Terminal UI
The terminal UI provides a chat interface in the terminal:
```python
from agency_swarm import Agency
agency = create_demo_agency()
agency.tui(show_reasoning=True)
```
资料来源：[examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)
### Agency Visualization
Generate interactive HTML visualizations of your agency structure:
```python
from agency_swarm import Agency
agency = create_demo_agency()
html_file = agency.visualize(
output_file="agency.html",
include_tools=True,
open_browser=True,
)
```
资料来源：[examples/agency_visualization.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_visualization.py)
## Testing
Run the test suite to ensure your implementation works correctly:
```bash
make coverage
```
The coverage command runs pytest with coverage reporting. Review the output to ensure adequate test coverage for your changes.
资料来源：[CONTRIBUTING.md](https://github.com/VRSEN/agency-swarm/blob/main/CONTRIBUTING.md)
## Additional Resources
### Cursor IDE Integration
For enhanced development with AI coding assistants, use the `.cursorrules` file at the repository root. See the Cursor IDE guide at https://agency-swarm.ai/welcome/getting-started/cursor-ide for detailed setup instructions.
### FastAPI Integration
Agency Swarm supports FastAPI integration for serving agents as REST endpoints:
```bash
cd examples/fastapi_integration
python server.py
```
This exposes endpoints for streaming responses and agency metadata. See the `examples/fastapi_integration/README.md` for complete documentation.
### CLI Commands Reference
| Command | Description |
|---------|-------------|
| `agency-swarm create-agent` | Create a new agent template |
| `agency-swarm migrate-agent` | Generate agent from OpenAI settings.json |
| `agency-swarm import-tool` | Import built-in tools into your project |
资料来源：[src/agency_swarm/cli/main.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/cli/main.py)
## Next Steps
After completing this guide, consider exploring:
1. **Advanced Communication Patterns** - Study `examples/interactive/hybrid_communication_flows.py` for complex agent interaction patterns
2. **Custom Tool Development** - Create domain-specific tools following the patterns in `examples/tools.py`
3. **Persistence** - Implement chat history persistence using `examples/custom_persistence.py`
4. **Guardrails** - Add input/output validation as demonstrated in `examples/guardrails.py`
For comprehensive documentation, visit https://agency-swarm.ai/welcome/getting-started/from-scratch for the full tutorial.
---
## Core Architecture
### 相关页面
相关主题：[Introduction to Agency Swarm](#page-introduction), [Agent Internals](#page-agent-internal), [Communication Flows](#page-communication-flows)
相关源码文件
以下源码文件用于生成本页说明：
- [src/agency_swarm/agency/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agency/core.py)
- [src/agency_swarm/agent/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)
- [src/agency_swarm/agent/agent_flow.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/agent_flow.py)
- [examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)
- [src/agency_swarm/utils/create_agent_template.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/utils/create_agent_template.py)
- [examples/README.md](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)
- [src/agency_swarm/cli/utils/generate-agent-from-settings.ts](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/cli/utils/generate-agent-from-settings.ts)
# Core Architecture
Agency Swarm is a multi-agent framework built on OpenAI's Agents SDK that enables the creation of collaborative AI agent systems. The core architecture comprises three fundamental layers: the **Agency Layer**, the **Agent Layer**, and the **Communication Layer**. This document provides an in-depth analysis of how these components interact to form a cohesive multi-agent system.
## Architecture Overview
The framework follows a hierarchical design where the Agency serves as the top-level orchestrator, managing multiple Agents that collaborate through well-defined communication channels.
```mermaid
graph TB
subgraph Agency["Agency Layer"]
A[Agency]
AC[AgencyContext]
AF[Communication Flows]
end
subgraph Agent["Agent Layer"]
AG1[Agent Instance]
AG2[Agent Instance]
AGn[Agent Instance]
end
subgraph Tools["Tool Layer"]
BT[BaseTool]
FT[FunctionTool]
TF[ToolFactory]
end
subgraph Model["Model Layer"]
MS[ModelSettings]
RM[Reasoning Models]
end
A --> AG1
A --> AG2
A --> AGn
A --> AC
A --> AF
AG1 --> BT
AG2 --> FT
AGn --> TF
AG1 --> MS
AG2 --> RM
```
## The Agency Layer
### Purpose and Role
The Agency acts as the central coordinator for all agents within the system. It manages agent initialization, communication routing, shared context distribution, and the overall execution flow.
**资料来源:** [examples/README.md:1-30](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)
### Agency Initialization
The Agency is initialized with a collection of agents and optional communication flows:
```python
from agency_swarm import Agency, Agent
support = Agent(name="SupportAgent", ...)
math = Agent(name="MathAgent", ...)
agency = Agency(
support,
math,
communication_flows=[(support, math, Handoff)],
shared_instructions="Demonstrate reasoning, web search, file search, and handoffs.",
name="DemoAgency"
)
```
**资料来源:** [examples/interactive/tui.py:40-68](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)
### Key Agency Components
| Component | Description |
|-----------|-------------|
| `agents` | Dictionary of initialized Agent instances |
| `communication_flows` | Defines allowed communication paths between agents |
| `shared_instructions` | Common instructions for all agents |
| `agency_context` | Shared data store accessible by all agents |
## The Agent Layer
### Agent Class Structure
The `Agent` class is the fundamental building block of Agency Swarm. Each agent encapsulates a specific role, set of tools, instructions, and model configuration.
**资料来源:** [src/agency_swarm/agent/core.py:1-100](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)
### Agent Initialization Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | `str` | Yes | Unique identifier for the agent |
| `description` | `str` | Yes | Role description for the agent |
| `instructions` | `str` | Yes | Instructions or path to instructions file |
| `tools` | `list[BaseTool]` | No | List of tool instances |
| `files_folder` | `str` | No | Path to files for vector store |
| `schemas_folder` | `str` | No | Path to OpenAPI schemas |
| `model` | `str` | No | Model identifier (default: "gpt-5.4") |
| `model_settings` | `ModelSettings` | No | Model configuration |
| `output_type` | `type` | No | Output schema for structured responses |
**资料来源:** [src/agency_swarm/agent/core.py:50-150](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)
### Tool Loading Mechanism
Agents support three distinct tool loading mechanisms:
```python
def _load_tools_from_folder(self) -> None:
"""Load tools defined in ``tools_folder`` and add them to the agent.
Supports both ``BaseTool`` subclasses and ``FunctionTool``
instances created via the ``@function_tool`` decorator.
"""
load_tools_from_folder(self)
```
**资料来源:** [src/agency_swarm/agent/core.py:120-130](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)
### OpenAPI Schema Parsing
Agents can automatically convert OpenAPI schemas into usable tools:
```python
def _parse_schemas(self):
"""Parse OpenAPI schemas from the schemas folder and create tools."""
parse_schemas(self)
```
**资料来源:** [src/agency_swarm/agent/core.py:135-140](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)
## Communication Architecture
### Agent-to-Agent Communication
Agents communicate through two primary mechanisms:
1. **Direct Messaging** (`SendMessage`)
2. **Handoffs** - Transfer of control between agents
```python
from agency_swarm import Handoff
agency = Agency(
support,
math,
communication_flows=[(support, math, Handoff)],
)
```
**资料来源:** [examples/interactive/tui.py:55-57](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)
### Communication Flow Definition
Communication flows are defined as a list of tuples specifying source agent, target agent, and the communication type:
```python
communication_flows=[
(agent_a, agent_b, Handoff),
(agent_b, agent_c, SendMessage),
]
```
## Execution Flow
### The get_response Method
The primary method for agent execution is `get_response`, which handles both user and agent-to-agent interactions:
```python
async def get_response(
self,
message: str | list[TResponseInputItem],
sender_name: str | None = None,
context_override: dict[str, Any] | None = None,
hooks_override: RunHooks | None = None,
run_config_override: RunConfig | None = None,
file_ids: list[str] | None = None,
additional_instructions: str | None = None,
agency_context: AgencyContext | None = None,
**kwargs: Any,
) -> RunResult:
```
**资料来源:** [src/agency_swarm/agent/core.py:150-200](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)
### Synchronous Execution
For synchronous use cases, `get_response_sync` provides a blocking interface:
```python
resp = agency.get_response_sync("What's your name?")
```
### Streaming Responses
The framework supports real-time streaming for interactive applications:
```python
# See streaming.py in examples
```
**资料来源:** [examples/README.md:8](https://github.com/VRSEN/agency-swarm/blob/main/examples/README.md)
## Model Configuration
### ModelSettings
Model configuration is handled through the `ModelSettings` class:
```python
from agency_swarm import ModelSettings, Reasoning
model_settings=ModelSettings(
temperature=0.3,
top_p=0.9,
max_tokens=25000,
reasoning=Reasoning(effort="high", summary="auto")
)
```
**资料来源:** [src/agency_swarm/cli/utils/generate-agent-from-settings.ts:50-80](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/cli/utils/generate-agent-from-settings.ts)
### Reasoning Models
The framework supports OpenAI's reasoning models with special configuration:
```python
def is_reasoning_model(model: str) -> bool:
"""Check if the model is a reasoning model."""
# Reasoning models do not support temperature parameter
```
**资料来源:** [src/agency_swarm/utils/create_agent_template.py:10-25](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/utils/create_agent_template.py)
### ModelSettings Parameters
| Parameter | Type | Description | Reasoning Model Compatible |
|-----------|------|-------------|---------------------------|
| `temperature` | `float` | Sampling temperature | No |
| `top_p` | `float` | Nucleus sampling | No |
| `max_tokens` | `int` | Maximum tokens in response | Yes |
| `reasoning` | `Reasoning` | Reasoning effort configuration | Yes |
## File Management
### Vector Store Integration
Agents can upload files to OpenAI's vector stores for semantic search:
```python
def upload_file(self, file_path: str, include_in_vector_store: bool = True) -> str:
"""Upload a file using the agent's file manager."""
if self.file_manager:
return self.file_manager.upload_file(file_path, include_in_vector_store)
raise RuntimeError(f"Agent {self.name} has no file manager configured")
```
**资料来源:** [src/agency_swarm/agent/core.py:145-152](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)
### File Search Tool Configuration
The `FileSearchTool` can be configured with vector store IDs:
```python
toolImports.push("FileSearchTool");
configParts.push(`vector_store_ids=[${vectorStoreIds}]`);
```
**资料来源:** [src/agency_swarm/cli/utils/generate-agent-from-settings.ts:100-120](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/cli/utils/generate-agent-from-settings.ts)
## Tool System Architecture
### Tool Types
| Tool Type | Description | Base Class |
|-----------|-------------|------------|
| `BaseTool` | Pydantic-based tool definition | `BaseTool` |
| `FunctionTool` | Decorator-based tool creation | `@function_tool` |
| `ToolFactory` | OpenAPI schema conversion | `ToolFactory.from_openapi_schema()` |
### BaseTool Implementation
```python
from agency_swarm.tools import BaseTool
from pydantic import Field
class MyCustomTool(BaseTool):
example_field: str = Field(
..., description="Description of the example field"
)
def run(self):
return f"Result: {self.example_field}"
```
**资料来源:** [README.md:100-130](https://github.com/VRSEN/agency-swarm/blob/main/README.md)
### ToolFactory for OpenAPI Schemas
```python
from agency_swarm.tools import ToolFactory
tools = ToolFactory.from_openapi_schema(
openapi_schema_json # Can be dict or loaded from file
)
```
## Agent Flow State Machine
The `agent_flow.py` module manages the state transitions within an agent's execution cycle:
```mermaid
graph LR
A[Init] --> B[Process Input]
B --> C{Tool Call?}
C -->|Yes| D[Execute Tool]
D --> B
C -->|No| E[Generate Response]
E --> F[Check Handoff]
F -->|Yes| G[Transfer Control]
G --> H[End]
F -->|No| I[Final Output]
I --> H
```
**资料来源:** [src/agency_swarm/agent/agent_flow.py:1-50](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/agent_flow.py)
## CLI and Template Generation
### Agent Template Creation
The CLI provides utilities for generating agent templates with validation:
```python
def create_agent_template(
agent_name=None,
agent_description=None,
model="gpt-5.4",
reasoning=None,
max_tokens=None,
temperature=None,
path="./",
instructions=None,
use_txt=False,
include_example_tool=True,
) -> bool:
```
**资料来源:** [src/agency_swarm/utils/create_agent_template.py:15-40](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/utils/create_agent_template.py)
### Input Validation
The framework validates agent names and parameters:
```python
def _validate_agent_name(agent_name):
"""Validate agent name follows CamelCase convention."""
def _validate_temperature(temperature):
"""Validate temperature is within valid range (0-2)."""
```
**资料来源:** [src/agency_swarm/utils/create_agent_template.py:40-70](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/utils/create_agent_template.py)
## Recommended Folder Structure
```
agency_project/
├── agency_manifesto.md # Agency's guiding principles
└── AgentName/
├── files/ # Files for vector store upload
├── schemas/ # OpenAPI schemas for tools
├── tools/ # Custom tool modules
├── AgentName.py # Agent class definition
├── __init__.py # Package initialization
└── instructions.md # Agent instructions
```
**资料来源:** [README.md:60-80](https://github.com/VRSEN/agency-swarm/blob/main/README.md)
## Programmatic Usage Patterns
### Async Execution
```python
import asyncio
async def main():
resp = await agency.get_response("Create a project skeleton.")
print(resp.final_output)
asyncio.run(main())
```
### Sync Execution
```python
resp = agency.get_response_sync("What's your name?")
```
## Summary
The Agency Swarm core architecture consists of three interdependent layers:
1. **Agency Layer**: Orchestrates multiple agents, manages communication flows, and maintains shared context
2. **Agent Layer**: Encapsulates individual agent capabilities including tools, instructions, and model configurations
3. **Communication Layer**: Enables agent-to-agent messaging and handoff mechanisms
The architecture follows a modular design pattern where tools, models, and communication mechanisms can be independently configured and composed to create complex multi-agent workflows.
---
## Agent Internals
### 相关页面
相关主题：[Core Architecture](#page-core-architecture), [Tools System](#page-tools-system)
Relevant Source Files
以下源码文件用于生成本页说明：
- [src/agency_swarm/agent/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)
- [src/agency_swarm/agent/initialization.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/initialization.py)
- [src/agency_swarm/agent/tools.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/tools.py)
- [src/agency_swarm/agent/execution.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/execution.py)
- [src/agency_swarm/agent/execution_guardrails.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/execution_guardrails.py)
# Agent Internals
## Overview
The Agent is the fundamental execution unit in Agency Swarm. It represents an autonomous entity capable of processing messages, executing tools, and communicating with other agents within an agency. Agents are built on OpenAI's Responses API and encapsulate configuration for model selection, tool definitions, file management, and communication protocols.
Agents serve as the building blocks for multi-agent systems, enabling complex workflows where specialized agents collaborate through defined communication flows. Each agent maintains its own state, toolset, and instruction set while participating in the broader agency ecosystem.
资料来源：[src/agency_swarm/agent/core.py:1-50]()
## Architecture Overview
The Agent module is organized into several interconnected components that handle different aspects of agent behavior:
```mermaid
graph TD
A[Agent] --> B[Initialization]
A --> C[Core Execution]
A --> D[Tools Management]
A --> E[Guardrails]
B --> B1[__init__]
B --> B2[_init_files]
B --> B3[_load_tools_from_folder]
B --> B4[_parse_schemas]
C --> C1[get_response]
C --> C2[Run Hooks]
C --> C3[Run Config]
D --> D1[BaseTool]
D --> D2[FunctionTool]
D --> D3[ToolFactory]
E --> E1[Input Guardrails]
E --> E2[Output Guardrails]
```
### Core Components
| Component | File | Purpose |
|-----------|------|---------|
| `core.py` | Main Agent class | Primary interface for agent operations |
| `initialization.py` | Agent setup | Initialization logic and factory methods |
| `tools.py` | Tool management | Tool loading, parsing, and factory utilities |
| `execution.py` | Runtime execution | Response processing and hooks |
| `execution_guardrails.py` | Validation | Input/output validation pipelines |
资料来源：[src/agency_swarm/agent/core.py:1-30]()
## Agent Initialization
### Constructor Parameters
The Agent class accepts the following core parameters during initialization:
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `name` | `str` | Yes | - | Unique identifier for the agent |
| `description` | `str` | Yes | - | Human-readable description of agent's role |
| `instructions` | `str` | Yes | - | Instructions file path or inline text |
| `files_folder` | `str` | No | `None` | Path to files for vector store upload |
| `schemas_folder` | `str` | No | `None` | Path to OpenAPI schema files |
| `tools` | `list[Tool]` | No | `[]` | List of tool instances to attach |
| `tools_folder` | `str` | No | `None` | Directory to auto-load tools from |
| `model` | `str` | No | `"gpt-5.4"` | OpenAI model identifier |
| `model_settings` | `ModelSettings` | No | `None` | Configuration for temperature, max_tokens, etc. |
| `response_format` | `ResponseFormat` | No | `None` | Output format specification |
资料来源：[src/agency_swarm/agent/core.py:50-120]()
### Initialization Flow
```mermaid
sequenceDiagram
participant User
participant Agent
participant FileManager
participant ToolLoader
participant SchemaParser
User->>Agent: __init__(params)
Agent->>Agent: _validate_params()
Agent->>FileManager: _init_files()
Agent->>ToolLoader: _load_tools_from_folder()
Agent->>SchemaParser: _parse_schemas()
Agent-->>User: Agent instance
```
The initialization process follows these steps:
1. **Parameter Validation**: All required parameters are validated
2. **File Manager Setup**: Files in `files_folder` are prepared for upload
3. **Tool Loading**: Tools are loaded from both the `tools` parameter and `tools_folder`
4. **Schema Parsing**: OpenAPI schemas in `schemas_folder` are converted to tools
资料来源：[src/agency_swarm/agent/initialization.py:1-80]()
### Model Configuration
Agents support various OpenAI models with appropriate default settings:
```python
# Reasoning models (e.g., o3, o4-mini) - no temperature
model="gpt-5.4"
model_settings=ModelSettings(
reasoning=Reasoning(effort="medium")
)
# Non-reasoning models - temperature defaults to 0.3
model="gpt-4o"
model_settings=ModelSettings(
temperature=0.3,
max_tokens=25000
)
```
资料来源：[src/agency_swarm/utils/create_agent_template.py:40-70]()
## Tools Management
### Tool Types
The framework supports two primary tool paradigms:
| Type | Base Class | Use Case |
|------|------------|----------|
| `BaseTool` | Abstract class | Complex tools with custom state and validation |
| `FunctionTool` | Decorator-based | Simple functions wrapped as tools |
### BaseTool Implementation
`BaseTool` subclasses must implement the following interface:
```python
from agency_swarm.tools import BaseTool
class MyTool(BaseTool):
name: str = "my_tool"
description: str = "Description of what the tool does"
def run(self) -> str:
"""Execute the tool's primary function."""
return "result"
```
资料来源：[src/agency_swarm/agent/tools.py:1-50]()
### FunctionTool Decorator
For simpler use cases, the `@function_tool` decorator wraps regular Python functions:
```python
from agency_swarm import function_tool
@function_tool
def calculate(expression: str) -> str:
"""Evaluate a mathematical expression."""
return str(eval(expression))
```
### Tool Loading from Folder
The `_load_tools_from_folder()` method dynamically imports tools from a directory structure:
```
AgentName/tools/
├── __init__.py
├── MyTool.py
└── AnotherTool.py
```
The loader:
- Scans the folder for Python files
- Imports classes inheriting from `BaseTool`
- Includes `FunctionTool` instances defined in `__init__.py`
- Adds all discovered tools to the agent's toolset
资料来源：[src/agency_swarm/agent/core.py:100-120]()
### OpenAPI Schema Parsing
Agents can automatically convert OpenAPI schemas into callable tools:
```python
from agency_swarm.tools import ToolFactory
# From file
tools = ToolFactory.from_openapi_schema(
openapi_schema=json.load(open("schema.json"))
)
# From URL
tools = ToolFactory.from_openapi_schema(
requests.get("https://api.example.com/openapi.json").json()
)
```
The `_parse_schemas()` method processes schemas from `schemas_folder` and creates corresponding tools.
资料来源：[README.md:50-80]()
## Execution Flow
### Core Execution Method
The `get_response()` method is the primary interface for agent execution:
```mermaid
graph LR
A[Message Input] --> B[Context Override]
B --> C[Run Hooks]
C --> D[OpenAI API Call]
D --> E[Tool Execution]
E --> D
D --> F[Output Processing]
F --> G[Response Format]
G --> H[RunResult]
```
### Method Signature
```python
async def get_response(
self,
message: str | list[TResponseInputItem],
sender_name: str | None = None,
context_override: dict[str, Any] | None = None,
hooks_override: RunHooks | None = None,
run_config_override: RunConfig | None = None,
file_ids: list[str] | None = None,
additional_instructions: str | None = None,
agency_context: AgencyContext | None = None,
**kwargs: Any,
) -> RunResult
```
### Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `message` | `str \| list[TResponseInputItem]` | Input message or list of message items |
| `sender_name` | `str \| None` | Name of the sending agent (for agent-to-agent) |
| `context_override` | `dict \| None` | Override agency context values |
| `hooks_override` | `RunHooks \| None` | Custom hooks for this execution |
| `run_config_override` | `RunConfig \| None` | Custom run configuration |
| `file_ids` | `list[str] \| None` | Pre-uploaded file IDs to include |
| `additional_instructions` | `str \| None` | Extra instructions appended to agent prompt |
| `agency_context` | `AgencyContext \| None` | Context from parent agency |
资料来源：[src/agency_swarm/agent/core.py:150-200]()
### Run Result
The execution returns a `RunResult` object containing:
- `messages`: Conversation history
- `final_output`: Text response from the model
- `tool_calls`: List of tool invocations made
- `usage`: Token and cost information
## Execution Guardrails
Guardrails provide validation hooks at the input and output boundaries of agent execution.
### Guardrail Interface
```python
class BaseExecutionGuardrail(ABC):
@abstractmethod
async def validate(
self,
agent: Agent,
messages: list[Message],
) -> tuple[bool, str | None]:
"""Validate input or output. Returns (passed, error_message)."""
pass
```
### Guardrail Pipeline
```mermaid
graph TD
A[Input Messages] --> B[Input Guardrails]
B -->|pass| C[Execute Agent]
B -->|fail| D[Return Error]
C --> E[Output Processing]
E --> F[Output Guardrails]
F -->|pass| G[Return Result]
F -->|fail| D
style D fill:#ff6b6b
style G fill:#51cf66
```
### Configuration
Guardrails are configured per-agent:
```python
from agency_swarm.agent import Agent, InputGuardrail, OutputGuardrail
agent = Agent(
name="SecureAgent",
instructions="...",
input_guardrails=[MyInputGuardrail()],
output_guardrails=[MyOutputGuardrail()],
)
```
资料来源：[src/agency_swarm/agent/execution_guardrails.py:1-60]()
## File Handling
### File Manager Integration
Agents can manage files for upload to OpenAI's vector stores:
```python
agent = Agent(
name="Researcher",
instructions="...",
files_folder="./files",
)
```
### Upload Method
```python
def upload_file(
self,
file_path: str,
include_in_vector_store: bool = True
) -> str:
"""Upload a file using the agent's file manager.
Returns:
str: The uploaded file ID
"""
if self.file_manager:
return self.file_manager.upload_file(
file_path,
include_in_vector_store
)
raise RuntimeError(f"Agent {self.name} has no file manager configured")
```
资料来源：[src/agency_swarm/agent/core.py:130-145]()
## Communication Patterns
### Agent-to-Agent Messaging
Agents communicate through defined flows using specialized message tools:
```python
from agency_swarm import Agency, Agent, SendMessage, Handoff
ceo = Agent(name="CEO", ...)
developer = Agent(name="Developer", ...)
agency = Agency(
ceo,
developer,
communication_flows=[
(ceo > developer, SendMessage), # CEO sends to Developer
(developer > ceo, Handoff), # Developer returns to CEO
]
)
```
### Message Types
| Type | Purpose |
|------|---------|
| `SendMessage` | Direct message with optional context |
| `SendMessageWithContext` | Message preserving agency context |
| `Handoff` | Transfer control back to calling agent |
## Model Settings
The `ModelSettings` class configures LLM behavior:
```python
from agency_swarm import Agent, ModelSettings, Reasoning
agent = Agent(
name="Analyzer",
model="gpt-5.4-mini",
model_settings=ModelSettings(
temperature=0.3,
max_tokens=25000,
reasoning=Reasoning(effort="high", summary="auto"),
top_p=0.9,
),
)
```
### Settings Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `temperature` | `float` | `0.3` | Sampling temperature (0-2) |
| `max_tokens` | `int` | varies | Maximum completion tokens |
| `top_p` | `float` | `None` | Nucleus sampling threshold |
| `reasoning` | `Reasoning` | `None` | Reasoning effort configuration |
| `response_include` | `list` | `None` | Include additional metadata |
资料来源：[src/agency_swarm/cli/utils/generate-agent-from-settings.ts:60-100]()
## State Management
### Agency Context
Agents can share state through the `AgencyContext`:
```python
async def get_response(
self,
message: str,
context_override: dict[str, Any] | None = None,
agency_context: AgencyContext | None = None,
...
) -> RunResult:
# Access shared context
if agency_context:
shared_data = agency_context.get("key")
```
### Message History
Agents maintain conversation history through `RunResult`:
```python
result = await agent.get_response("Hello")
for message in result.messages:
print(f"{message.role}: {message.content}")
```
## CLI Integration
### Agent Template Creation
The CLI provides utilities for generating agent templates:
```bash
agency-swarm create-agent-template "Data Analyst" \
--description "Performs data analysis" \
--model "gpt-5.4-mini" \
--reasoning "medium" \
--temperature 0.3
```
This generates the standard folder structure:
```
DataAnalyst/
├── DataAnalyst.py
├── __init__.py
├── instructions.md
├── files/
├── schemas/
└── tools/
```
资料来源：[src/agency_swarm/cli/main.py:30-80]()
## Summary
The Agent Internals architecture demonstrates a modular design where:
1. **Initialization** handles setup of files, tools, and schemas
2. **Tools Management** provides flexible tool creation and loading
3. **Execution** manages the runtime loop with hooks and guardrails
4. **Communication** enables multi-agent collaboration through defined flows
5. **Configuration** supports various models with appropriate defaults
This architecture allows agents to serve as self-contained, configurable units that can participate in complex multi-agent workflows while maintaining clear separation of concerns.
---
## Tools System
### 相关页面
相关主题：[Getting Started Guide](#page-getting-started), [Agent Internals](#page-agent-internal), [Communication Flows](#page-communication-flows)
相关源码文件
以下源码文件用于生成本页说明：
- [src/agency_swarm/tools/base_tool.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/base_tool.py)
- [src/agency_swarm/tools/__init__.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/__init__.py)
- [src/agency_swarm/tools/tool_factory.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/tool_factory.py)
- [src/agency_swarm/tools/built_in/IPythonInterpreter.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/built_in/IPythonInterpreter.py)
- [src/agency_swarm/tools/built_in/PersistentShellTool.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/built_in/PersistentShellTool.py)
# Tools System
## Overview
The Tools System in Agency Swarm provides a flexible mechanism for extending agent capabilities through custom tool implementations. Agents can use tools to interact with external services, execute code, run shell commands, search the web, and perform various other tasks that extend beyond natural language processing.
Tools in Agency Swarm serve as the primary interface between agents and external functionality. They enable agents to:
- Execute Python code in isolated environments
- Run persistent shell commands
- Search the web for information
- Process and analyze files
- Interact with external APIs via OpenAPI schemas
The system supports two primary tool creation patterns: inheriting from `BaseTool` class and using the `@function_tool` decorator. Additionally, tools can be auto-generated from OpenAPI schemas using `ToolFactory`.
## Architecture
```mermaid
graph TD
A[Agent] --> B[Tools System]
B --> C[BaseTool Subclass]
B --> D[@function_tool Decorator]
B --> E[ToolFactory]
C --> F[IPythonInterpreter]
C --> G[PersistentShellTool]
C --> H[Custom Tool]
E --> I[OpenAPI Schema]
F --> J[Code Execution Environment]
G --> K[Shell Session]
```
## Core Components
### BaseTool Class
The `BaseTool` class is the foundation for all tools in Agency Swarm. It provides a standardized interface for tool definition and execution.
**File:** `src/agency_swarm/tools/base_tool.py`
**Key Responsibilities:**
- Define tool schema for OpenAI API compatibility
- Validate input parameters using Pydantic
- Execute the tool's core functionality via `run()` method
- Support async execution when needed
**Structure:**
| Component | Description |
|-----------|-------------|
| `ToolConfig` | Pydantic model defining tool metadata (name, description, parameters) |
| `BaseTool` | Abstract base class for all tools |
| `run()` | Abstract method for tool execution |
| `get_schema()` | Returns OpenAI-compatible tool schema |
### ToolFactory
The `ToolFactory` class enables automatic generation of tools from OpenAPI schemas. This allows integration with existing REST APIs without manual tool implementation.
**File:** `src/agency_swarm/tools/tool_factory.py`
**Usage Pattern:**
```python
from agency_swarm.tools import ToolFactory
# From local file
with open("schemas/your_schema.json") as f:
tools = ToolFactory.from_openapi_schema(f.read())
# From remote URL
import requests
tools = ToolFactory.from_openapi_schema(
requests.get("https://api.example.com/openapi.json").json()
)
```
### Built-in Tools
Agency Swarm includes several pre-built tools for common use cases.
#### IPythonInterpreter
**File:** `src/agency_swarm/tools/built_in/IPythonInterpreter.py`
Provides Python code execution capabilities within an agency. Key features:
- Executes Python code in a persistent environment
- Maintains state between executions
- Supports file operations and data processing
- Integrates with agent workflows for data analysis tasks
**Configuration Parameters:**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `timeout` | int | 60 | Maximum execution time in seconds |
| `working_directory` | str | None | Directory for file operations |
#### PersistentShellTool
**File:** `src/agency_swarm/tools/built_in/PersistentShellTool.py`
Provides persistent shell command execution. Unlike one-off command runners, this tool maintains an active shell session across multiple tool calls.
**Features:**
- Persistent shell state between commands
- Environment variable preservation
- Working directory consistency
- Command history tracking
### Function Tool Decorator
The `@function_tool` decorator provides a lightweight alternative to `BaseTool` subclassing. It's ideal for simpler tools that don't require extensive configuration.
**Pattern:**
```python
from agency_swarm.tools import function_tool
from pydantic import Field
@function_tool
def calculate(a: float, b: float, operation: str = Field(
description="Operation to perform: add, subtract, multiply, divide"
)) -> str:
"""Perform basic arithmetic operations."""
if operation == "add":
return str(a + b)
elif operation == "subtract":
return str(a - b)
elif operation == "multiply":
return str(a * b)
elif operation == "divide":
if b == 0:
return "Error: Division by zero"
return str(a / b)
return "Unknown operation"
```
## Creating Custom Tools
### Method 1: Using BaseTool Class
For complex tools requiring detailed configuration:
```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 is used by the agent to determine when to use this tool.
"""
# Define fields with descriptions using Pydantic Field
example_field: str = Field(
..., description="Description of the example field explaining its purpose"
)
def run(self):
"""
The implementation of the run method.
"""
# Tool logic here
return f"Result: {self.example_field}"
```
### Method 2: Using @function_tool Decorator
For simpler tools:
```python
from agency_swarm.tools import function_tool
@function_tool
def my_simple_tool(input_text: str) -> str:
"""Process input text and return result."""
return input_text.upper()
```
### Method 3: From OpenAPI Schema
For API integration:
```python
from agency_swarm.tools import ToolFactory
# Generate tools from OpenAPI specification
tools = ToolFactory.from_openapi_schema(openapi_schema_dict)
# tools is a list of BaseTool instances
for tool in tools:
print(tool.name, tool.description)
```
## Tool Integration with Agents
### Adding Tools to Agents
Tools are passed to agents via the `tools` parameter during initialization:
```python
from agency_swarm import Agent
from agency_swarm.tools import BaseTool, function_tool
# Custom tool class
class DataProcessor(BaseTool):
name: str = "DataProcessor"
description: str = "Processes data according to specified rules"
data: str = Field(description="Data to process")
rule: str = Field(description="Processing rule to apply")
def run(self):
return f"Processed {self.data} with rule {self.rule}"
# Function tool
@function_tool
def calculator(a: float, b: float) -> float:
return a + b
# Create agent with tools
agent = Agent(
name="DataAgent",
description="Handles data processing tasks",
tools=[DataProcessor, calculator]
)
```
### Tool Discovery from Folders
Agents can automatically discover and load tools from a specified directory:
```python
agent = Agent(
name="FileAgent",
description="Handles file operations",
tools_folder="./tools" # Auto-loads all tools from this directory
)
```
This approach scans the specified folder for tool definitions and makes them available to the agent without explicit listing.
## Tool Schema Generation
Each tool automatically generates an OpenAI-compatible schema used for function calling:
```mermaid
graph LR
A[Tool Definition] --> B[Schema Generator]
B --> C[OpenAI Tool Schema]
C --> D[Agent System Prompt]
D --> E[Model Function Calling]
```
**Schema Structure:**
```json
{
"type": "function",
"function": {
"name": "tool_name",
"description": "Tool description",
"parameters": {
"type": "object",
"properties": {...},
"required": [...]
}
}
}
```
## Tool Execution Flow
```mermaid
sequenceDiagram
participant Agent
participant Tool as Tool Instance
participant Runtime as Tool Runtime
Agent->>Tool: Calls tool with parameters
Tool->>Tool: Validate parameters (Pydantic)
Tool->>Runtime: Execute run() method
Runtime-->>Tool: Return result
Tool-->>Agent: Return tool result
Note over Agent,Tool: Tool can be sync or async
```
## Testing Tools
Tools should include comprehensive test coverage. Tests are located in `agency_swarm/tests/test_tools.py`.
**Test Template:**
```python
def test_my_tool_example():
tool = MyCustomTool(example_field="test value")
result = tool.run()
assert "expected output" in result
```
**Running Tool Tests:**
```bash
make coverage
```
## CLI Tool Import
Agency Swarm CLI provides built-in tool import functionality:
```bash
# List available built-in tools
agency-swarm import-tool --list
# Import a specific tool
agency-swarm import-tool IPythonInterpreter --directory ./my_tools
```
This command copies the selected tool's source files into the specified directory, allowing for customization.
## Best Practices
1. **Clear Descriptions**: Use descriptive docstrings that explain when and why the agent should use the tool
2. **Field Documentation**: Every parameter field should have a clear `description` for agent understanding
3. **Error Handling**: Implement proper error handling in the `run()` method
4. **Type Safety**: Use Pydantic models for all parameters to ensure validation
5. **Idempotency**: Design tools to be safely re-executable when possible
6. **Resource Management**: Clean up resources (files, connections) after execution
## File Structure
```
agency_swarm/tools/
├── __init__.py # Public exports
├── base_tool.py # BaseTool class definition
├── tool_factory.py # ToolFactory for OpenAPI schemas
├── function_tool.py # @function_tool decorator
└── built_in/ # Pre-built tool implementations
├── IPythonInterpreter.py
├── PersistentShellTool.py
└── ...
```
## Summary
The Tools System provides a comprehensive framework for extending agent capabilities in Agency Swarm. With support for custom tool creation, OpenAPI schema integration, and built-in tools for common tasks, developers can flexibly enhance their agents' functionality. The system leverages Pydantic for robust parameter validation and follows consistent patterns that make tool development straightforward and maintainable.
---
## Communication Flows
### 相关页面
相关主题：[Core Architecture](#page-core-architecture), [Tools System](#page-tools-system), [Messaging System](#page-messaging-system)
相关源码文件
以下源码文件用于生成本页说明：
- [src/agency_swarm/agency/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agency/core.py)
- [src/agency_swarm/tools/send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/tools/send_message.py)
- [src/agency_swarm/agent/agent_flow.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/agent_flow.py)
- [examples/custom_send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/custom_send_message.py)
- [examples/agency_visualization.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_visualization.py)
- [examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)
# Communication Flows
## Overview
Communication Flows define how agents interact with each other within an Agency. They establish the rules and pathways for agent-to-agent messaging, control transfers, and collaborative workflows. This system enables multi-agent collaboration by specifying which agents can communicate, through what mechanisms, and in what directions.
Communication Flows are a core architectural component of agency-swarm that transforms a collection of individual agents into a coordinated multi-agent system. Without explicit communication flows, agents cannot interact with each other—they can only respond to direct user input.
## Core Concepts
### Agent Communication Patterns
Agency-swarm supports two primary communication mechanisms:
| Pattern | Purpose | Use Case |
|---------|---------|----------|
| **SendMessage** | Direct message passing with optional context | Coordinated workflows, task delegation |
| **Handoff** | Transfer of conversational control | Escalation, specialized handling, task completion |
### Flow Directionality
Communication flows are directional, meaning you can specify asymmetric communication patterns:
- **Unidirectional**: Agent A can send messages to Agent B, but not vice versa
- **Bidirectional**: Agents can communicate in both directions
- **Broadcast-capable**: Certain patterns allow multi-recipient messaging
## Architecture
### Flow Processing Pipeline
```mermaid
graph TD
A[User Input] --> B[Entry Point Agent]
B --> C{Communication Flow Check}
C -->|SendMessage| D[SendMessage Tool Execution]
C -->|Handoff| E[Handoff Tool Execution]
D --> F[Recipient Agent Processing]
E --> G[Control Transfer to Recipient]
F --> H{More Flows?}
G --> H
H -->|Yes| C
H -->|No| I[Final Response]
```
### Flow Definition in Agency Class
The `Agency` class in `src/agency_swarm/agency/core.py` manages communication flows through the `communication_flows` parameter:
```python
Agency(
agents,
communication_flows=[...],
shared_instructions="...",
send_message_tool_class=SendMessage
)
```
资料来源：[examples/agency_visualization.py:25-35]()
### Flow Tuple Structure
Communication flows are defined as tuples with the following structure:
```python
communication_flows=[
(agent_a > agent_b), # Simple unidirectional
(agent_c < agent_d), # Reverse direction
(agent_e > agent_f, Handoff), # With specific tool class
(agent_g < agent_h > agent_i), # Multi-agent chain
]
```
## Configuration Options
### Basic Flow Definition
Simple directional flows use the default `SendMessage` tool:
```python
from agency_swarm import Agent, Agency
ceo = Agent(name="CEO", instructions="Manage the workflow")
developer = Agent(name="Developer", instructions="Write code")
agency = Agency(
ceo,
developer,
communication_flows=[
(ceo > developer), # CEO can delegate to Developer
(developer > ceo), # Developer can report back to CEO
]
)
```
### Handoff-Based Flows
Handoffs transfer conversational control to another agent:
```python
from agency_swarm.tools import Handoff
support = Agent(name="Support", instructions="Handle basic queries")
specialist = Agent(name="Specialist", instructions="Handle complex issues")
agency = Agency(
support,
specialist,
communication_flows=[
(support > specialist, Handoff), # Support escalates to Specialist
]
)
```
资料来源：[examples/interactive/tui.py:48-52]()
### Custom SendMessage Classes
For flows requiring additional context passing, use custom SendMessage classes:
```python
from agency_swarm.tools import SendMessage
from agency_swarm import Agent, Agency
class SendMessageWithContext(SendMessage):
"""Custom SendMessage that includes context about key decisions."""
pass
coordinator = Agent(name="Coordinator", instructions="Coordinate tasks")
specialist = Agent(name="Specialist", instructions="Execute specialized tasks")
agency = Agency(
coordinator,
specialist,
communication_flows=[
(coordinator > specialist, SendMessageWithContext),
(specialist > coordinator, Handoff),
],
shared_instructions="Use key decisions to guide analysis tool selection.",
send_message_tool_class=SendMessageWithContext,
)
```
资料来源：[examples/custom_send_message.py:20-32]()
### Multi-Agent Communication Chains
Complex workflows can involve multiple agents in a single flow definition:
```python
dev = Agent(name="Developer", instructions="Write code")
qa = Agent(name="QA", instructions="Test code")
pm = Agent(name="PM", instructions="Manage project")
agency = Agency(
dev,
qa,
pm,
communication_flows=[
(dev < ceo > pm > dev), # Multi-agent chain with CEO
(dev > qa, Handoff), # Developer can hand off to QA
]
)
```
资料来源：[examples/agency_visualization.py:25-35]()
## Flow Visualization
The Agency class provides visualization capabilities for communication flows:
```python
html_file = agency.visualize(
output_file="agency_interactive_demo.html",
include_tools=True,
open_browser=True,
)
```
This generates an interactive HTML visualization showing:
- Agent nodes and their connections
- Communication flow directions
- Tool availability per agent
- Entry point indicators
## SendMessage Tool Reference
### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `recipient` | Agent | Yes | Target agent for the message |
| `message` | str | Yes | Content to send |
| `images` | list | No | Image attachments |
| `files` | list | No | File attachments |
### Configuration via Agency
Set default behavior for all flows:
```python
agency = Agency(
agent_a,
agent_b,
communication_flows=[agent_a > agent_b],
send_message_tool_class=CustomSendMessage, # Default for all flows
)
```
资料来源：[src/agency_swarm/tools/send_message.py]()
## Handoff Tool Reference
### Behavior
When an agent executes a Handoff:
1. Current agent's response is terminated
2. Control transfers to the target agent
3. Original message context is preserved
4. Target agent receives the conversation state
### Use Cases
| Scenario | Benefit |
|----------|---------|
| Escalation | Route to specialized agents |
| Task completion | Transfer to confirmation agent |
| Parallel processing | Split work across specialists |
## Shared Instructions
Communication flows can leverage shared instructions for consistent behavior:
```python
agency = Agency(
coordinator,
specialist,
communication_flows=[coordinator > specialist],
shared_instructions="All agents should use key decisions to guide their actions.",
)
```
Shared instructions are available to all agents in the agency and provide context for communication decisions.
## Best Practices
### Flow Design Principles
1. **Explicit Over Implicit**: Always define flows explicitly rather than relying on defaults
2. **Minimal Paths**: Only create necessary communication pathways
3. **Directional Clarity**: Design flows with clear escalation paths
4. **Context Preservation**: Use custom SendMessage classes when context matters
### Security Considerations
- Limit communication flows to only necessary agent pairs
- Use shared instructions to establish boundaries
- Review flow visualizations for unintended pathways
### Performance
- Avoid circular flows without exit conditions
- Limit the depth of multi-agent chains
- Consider async patterns for long-running workflows
## Example: Complete Multi-Agent Workflow
```python
from agency_swarm import Agent, Agency
from agency_swarm.tools import SendMessage, Handoff
# Define agents
ceo = Agent(
name="CEO",
instructions="You manage the overall workflow and delegate tasks."
)
coordinator = Agent(
name="Coordinator",
instructions="Coordinate between teams and track progress."
)
developer = Agent(
name="Developer",
instructions="Implement technical solutions."
)
qa = Agent(
name="QA",
instructions="Test and validate deliverables."
)
# Create agency with communication flows
agency = Agency(
ceo, # Entry point (positional argument)
coordinator,
developer,
qa,
communication_flows=[
(ceo > coordinator), # CEO delegates to Coordinator
(coordinator > developer), # Coordinator assigns to Developer
(coordinator > qa), # Coordinator assigns to QA
(developer > qa, Handoff), # Developer hands off to QA for testing
(qa > coordinator), # QA reports back to Coordinator
(coordinator > ceo), # Coordinator reports to CEO
],
shared_instructions="Follow the standard workflow: develop, test, then report."
)
# Execute workflow
async def main():
result = await agency.get_response("Start the Q4 optimization project.")
print(result.final_output)
```
## See Also
- [Agent Documentation](agents) - Individual agent configuration
- [Tools Reference](tools) - SendMessage and Handoff tools
- [Agency Visualization](visualization) - Interactive flow visualization
- [FastAPI Integration](fastapi-integration) - Deploying agencies with communication flows
---
## Context Management
### 相关页面
相关主题：[Core Architecture](#page-core-architecture), [Agent Internals](#page-agent-internal), [Messaging System](#page-messaging-system)
Relevant Source Files
以下源码文件用于生成本页说明：
- [src/agency_swarm/agent/core.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)
- [examples/agency_context.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_context.py)
- [examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)
- [examples/custom_send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/custom_send_message.py)
- [README.md](https://github.com/VRSEN/agency-swarm/blob/main/README.md)
- [examples/agency_visualization.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_visualization.py)
# Context Management
## Overview
Context Management in Agency Swarm refers to the mechanisms by which state, instructions, and runtime data are shared and propagated across agents within an agency. This system enables multi-agent collaboration by allowing agents to access shared information, communicate effectively, and maintain coherent workflows across complex task execution pipelines.
The context management architecture supports multiple layers of data sharing:
1. **Agency-level shared instructions** that apply to all agents
2. **Per-agent instructions** for role-specific guidance
3. **Runtime context propagation** through the `AgencyContext` type
4. **Message context** for passing additional data through communication flows
资料来源：[examples/agency_context.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_context.py)
资料来源：[examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)
---
## Core Context Types
### AgencyContext
The `AgencyContext` type serves as the runtime container for contextual data passed between agents during execution. It flows through the agency hierarchy and is available to all agents during their turn in the conversation loop.
```python
async def get_response(
self,
message: str | list[TResponseInputItem],
sender_name: str | None = None,
context_override: dict[str, Any] | None = None,
hooks_override: RunHooks | None = None,
run_config_override: RunConfig | None = None,
file_ids: list[str] | None = None,
additional_instructions: str | None = None,
agency_context: AgencyContext | None = None, # Context from agency, or None for standalone
**kwargs: Any,
) -> RunResult:
```
**Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `message` | `str \| list[TResponseInputItem]` | The input message or list of message items |
| `sender_name` | `str \| None` | Identifier of the sending agent or user |
| `context_override` | `dict[str, Any] \| None` | Override values merged into context |
| `agency_context` | `AgencyContext \| None` | Context from agency, or None for standalone agents |
资料来源：[src/agency_swarm/agent/core.py:35-54](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)
---
## Shared Instructions
### Purpose and Scope
Shared instructions are a foundational context mechanism that applies uniform behavioral guidance across all agents within an agency. When an agent is instantiated as part of an agency, these instructions are prepended to the agent's individual instructions.
```python
return Agency(
support,
math,
communication_flows=[(support, math, Handoff)],
shared_instructions="Demonstrate reasoning, web search, file search, and handoffs.",
name="TuiDemoAgency",
)
```
### Behavior
- **Precedence**: Individual agent instructions take precedence, but shared instructions provide foundational context
- **Propagation**: Shared instructions are visible to all agents in the agency
- **Use Cases**: Agency-wide policies, common procedures, general guidelines for all agents
资料来源：[examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)
---
## Context Propagation Flow
```mermaid
graph TD
A[User Input / Agent Message] --> B{Agency.get_response}
B --> C[Initialize AgencyContext]
C --> D[Load Shared Instructions]
D --> E[Load Agent-specific Instructions]
E --> F[Merge context_override if provided]
F --> G[Execute Agent Turn]
G --> H[Run Tools if needed]
H --> I[Communicate via SendMessage]
I --> J{Communication Flow defined?}
J -->|Yes| K[Pass AgencyContext to target agent]
J -->|No| L[Return RunResult]
K --> G
L --> M[Final Output]
style C fill:#e1f5fe
style D fill:#fff3e0
style F fill:#e8f5e9
```
---
## Communication Flows and Context
### SendMessageWithContext
When agents communicate through defined flows, they can pass additional contextual data using `SendMessageWithContext`. This allows the sending agent to inject specific data into the recipient's context before processing.
```python
agency = Agency(
coordinator,
specialist,
communication_flows=[
(coordinator > specialist, SendMessageWithContext),
(specialist > coordinator, Handoff),
],
shared_instructions="Use key decisions to guide analysis tool selection.",
)
```
### Key Communication Patterns
| Pattern | Class | Context Behavior |
|---------|-------|------------------|
| Direct Message | `SendMessage` | Basic message passing |
| Message with Context | `SendMessageWithContext` | Includes additional context data |
| Agent Handoff | `Handoff` | Transfers full control to another agent |
资料来源：[examples/custom_send_message.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/custom_send_message.py)
---
## Context Override Mechanism
The `context_override` parameter allows runtime modification of the context dictionary. This is particularly useful when specific values need to be injected into an agent's execution context without modifying the core agency configuration.
```python
context_override: dict[str, Any] | None = None
```
**Use Cases:**
1. Injecting user-specific data for a particular interaction
2. Providing one-time instructions for a specific task
3. Overriding default values based on runtime conditions
资料来源：[src/agency_swarm/agent/core.py:40](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/core.py)
---
## Context in Multi-Agent Workflows
### Agency-Level Context Example
The following demonstrates a complete context management pattern in a multi-agent setup:
```python
def create_demo_agency():
support = Agent(
name="SupportAgent",
description="Handles user support requests with file search and web search.",
instructions=(
"You are a helpful support agent. Use your tools to assist users. "
"You can analyze files and search the web to find answers. "
"You can also use the calculate tool for math. "
"When the user asks about something you don't know, use the web search tool to "
"inspect them before answering."
),
include_search_results=True,
tools=[WebSearchTool()],
model="gpt-5.4-mini",
model_settings=ModelSettings(reasoning=Reasoning(effort="low", summary="auto")),
conversation_starters=[
"Tell me about daily_revenue_report.pdf.",
"Search the web for the latest Bun release notes.",
"What is 345 * 18?",
"Compare research_report.txt with daily_revenue_report.pdf.",
],
)
math = Agent(
name="MathAgent",
description="Handles arithmetic and calculation-heavy requests.",
instructions="You are MathAgent. Use the calculate tool for arithmetic questions.",
tools=[calculate],
model="gpt-5.4-mini",
model_settings=ModelSettings(reasoning=Reasoning(effort="high", summary="auto")),
)
return Agency(
support,
math,
communication_flows=[(support, math, Handoff)],
shared_instructions="Demonstrate reasoning, web search, file search, and handoffs.",
name="TuiDemoAgency",
)
```
**Context Flow in This Example:**
1. **Shared Instructions**: "Demonstrate reasoning, web search, file search, and handoffs." applies to both agents
2. **Communication Flow**: SupportAgent can hand off to MathAgent for calculation tasks
3. **Agent-Specific Instructions**: Each agent has its own detailed instructions
4. **Tool Context**: Each agent has access to specific tools with their own execution contexts
资料来源：[examples/interactive/tui.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/interactive/tui.py)
---
## Context and Visualization
The agency visualization feature can display communication flows and context relationships:
```python
agency = create_demo_agency()
# Generate interactive HTML visualization
html_file = agency.visualize(
output_file="agency_interactive_demo.html",
include_tools=True,
open_browser=True,
)
```
This visualization shows:
- How context flows between agents
- Communication flow definitions
- Entry points where context originates
- Tool relationships within the context
资料来源：[examples/agency_visualization.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agency_visualization.py)
---
## Summary Table: Context Management Components
| Component | Type | Scope | Purpose |
|-----------|------|-------|---------|
| `AgencyContext` | Class | Runtime | Container for runtime contextual data |
| `shared_instructions` | Parameter | Agency-wide | Instructions applying to all agents |
| `context_override` | Parameter | Per-call | Runtime injection of context values |
| `additional_instructions` | Parameter | Per-call | Supplemental instructions for single execution |
| `SendMessageWithContext` | Class | Communication | Pass context through agent messaging |
---
## Best Practices
1. **Use Shared Instructions Sparingly**: Keep shared instructions concise and universally applicable
2. **Leverage context_override for One-time Data**: Avoid modifying core configuration for transient data
3. **Define Clear Communication Flows**: Explicit flows ensure predictable context propagation
4. **Document Agent Instructions**: Clear instructions reduce ambiguity in context interpretation
5. **Use Handoffs for Complete Transfers**: When full control should pass to another agent, use Handoff instead of basic messaging
---
## Messaging System
### 相关页面
相关主题：[Communication Flows](#page-communication-flows), [Context Management](#page-context-management)
相关源码文件
以下源码文件用于生成本页说明：
- [src/agency_swarm/messages/__init__.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/messages/__init__.py)
- [src/agency_swarm/messages/message_formatter.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/messages/message_formatter.py)
- [src/agency_swarm/messages/message_filter.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/messages/message_filter.py)
- [src/agency_swarm/messages/response_input_sanitizer.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/messages/response_input_sanitizer.py)
- [src/agency_swarm/agent/execution_streaming.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/execution_streaming.py)
# Messaging System
The Messaging System in Agency Swarm is a foundational layer responsible for handling all communication between agents, users, and external systems. It manages message formatting, filtering, sanitization, streaming, and conversion to ensure reliable and secure inter-agent communication.
## Architecture Overview
The messaging system consists of several interconnected modules that process messages at different stages of agent execution.
```mermaid
graph TD
A[User/Agent Input] --> B[Message Filter]
B --> C[Response Input Sanitizer]
C --> D[Message Formatter]
D --> E[Agent Core]
E --> F[Execution Streaming]
F --> G[Output Messages]
H[Tool Calls] --> D
I[Guardrails] --> D
```
### Core Components
| Component | File | Purpose |
|-----------|------|---------|
| `__init__.py` | `messages/__init__.py` | Module exports and public API |
| `message_formatter.py` | `messages/message_formatter.py` | Formats messages for different contexts |
| `message_filter.py` | `messages/message_filter.py` | Filters and validates incoming messages |
| `response_input_sanitizer.py` | `messages/response_input_sanitizer.py` | Sanitizes input for security |
| `execution_streaming.py` | `agent/execution_streaming.py` | Handles streaming responses |
## Message Flow Pipeline
Messages traverse a multi-stage pipeline before reaching their destination. Each stage performs specific transformations or validations.
```mermaid
graph LR
subgraph Input_Processing
F1[Filter] --> F2[Sanitize] --> F3[Format]
end
subgraph Core_Processing
F3 --> F4[Agent Execution]
end
subgraph Output_Processing
F4 --> F5[Streaming Output]
end
```
### Stage 1: Message Filtering
The `MessageFilter` class provides initial validation and filtering capabilities for incoming messages. It ensures that messages meet basic structural requirements before further processing.
资料来源：[src/agency_swarm/messages/message_filter.py:1-50]()
### Stage 2: Input Sanitization
The `ResponseInputSanitizer` module sanitizes user input to prevent injection attacks and ensure compatibility with the OpenAI API response format requirements.
```python
# Sanitization removes or escapes potentially harmful content
sanitized_input = ResponseInputSanitizer.sanitize(raw_message)
```
资料来源：[src/agency_swarm/messages/response_input_sanitizer.py:1-30]()
### Stage 3: Message Formatting
The `MessageFormatter` handles the final transformation of messages, adapting them for different contexts such as agent-to-agent communication, tool execution, or user display.
资料来源：[src/agency_swarm/messages/message_formatter.py:1-40]()
## Streaming Execution
The streaming system provides real-time message delivery during agent execution, enabling responsive user experiences.
### Streaming Architecture
```mermaid
graph TD
A[get_response_stream] --> B[StreamingRunResponse]
B --> C[Event Stream]
C --> D[text/event-stream]
D --> E[Client Application]
F[RunResult] --> G[new_items]
G --> H[message_history]
H --> I[Final Output]
```
### Streaming Methods
| Method | Return Type | Purpose |
|--------|-------------|---------|
| `get_response_stream()` | `StreamingRunResponse` | Initiates streaming execution |
| `get_response()` | `RunResult` | Returns complete result after execution |
资料来源：[src/agency_swarm/agent/core.py:100-130]()
### Streaming Configuration
The streaming system integrates with the execution layer to provide real-time updates:
```python
def get_response_stream(
self,
message: str | list[TResponseInputItem],
sender_name: str | None = None,
context_override: dict[str, Any] | None = None,
hooks_override: RunHooks | None = None,
run_config_override: RunConfig | None = None,
file_ids: list[str] | None = None,
additional_instructions: str | None = None,
agency_context: AgencyContext | None = None,
**kwargs: Any,
) -> StreamingRunResponse:
```
资料来源：[src/agency_swarm/agent/core.py:130-160]()
## Message Conversion
The system includes utilities for converting between different message formats, particularly between internal `RunItem` objects and OpenAI-compatible `TResponseInputItem` format.
### RunItem to TResponseInputItem Conversion
```mermaid
graph TD
A[RunItem] --> B[run_item_to_tresponse_input_item]
B --> C{TResponseInputItem}
C --> D[message]
C --> E[image_url]
C --> F[tool_call]
C --> E[tool_result]
```
The conversion function uses the SDK's built-in conversion method:
```python
def run_item_to_tresponse_input_item(item: RunItem) -> TResponseInputItem | None:
try:
converted_item = item.to_input_item()
return converted_item
except Exception as e:
logger.warning(f"Failed to convert {type(item).__name__}")
return None
```
资料来源：[src/agency_swarm/agent/execution_helpers.py:80-100]()
## Message Types and Structures
### TResponseInputItem Format
The system uses `TResponseInputItem` for message representation, supporting multiple content types:
| Field | Type | Description |
|-------|------|-------------|
| `role` | `str` | Message role (user, assistant, system) |
| `content` | `str` | Text content |
| `name` | `str` | Sender name |
| `tool_calls` | `list` | Tool call requests |
| `tool_call_id` | `str` | Tool result identifier |
### RunResult Structure
| Field | Type | Description |
|-------|------|-------------|
| `input` | `list` | Original input messages |
| `new_items` | `list[RunItem]` | New items generated during run |
| `raw_responses` | `list` | Raw API responses |
| `final_output` | `Any` | Processed final output |
| `input_guardrail_results` | `list` | Input validation results |
| `output_guardrail_results` | `list` | Output validation results |
资料来源：[src/agency_swarm/agent/execution_helpers.py:50-75]()
## Context Management
### AgencyContext
The `AgencyContext` provides shared context for message processing across agents:
```mermaid
graph TD
A[AgencyContext] --> B[Shared State]
A --> C[Agent Registry]
A --> D[Communication Flows]
A --> E[Message History]
```
Context is automatically created for standalone agent usage:
```python
if agency_context is None:
agency_context = self._create_minimal_context()
```
资料来源：[src/agency_swarm/agent/core.py:85-95]()
## Integration with Agent Execution
### Execution Flow
```mermaid
sequenceDiagram
participant User
participant Agent
participant MessageSystem
participant OpenAI_API
User->>Agent: get_response(message)
Agent->>MessageSystem: Filter & Sanitize
MessageSystem->>MessageSystem: Format
Agent->>OpenAI_API: Run Request
OpenAI_API-->>Agent: Streaming Events
Agent->>MessageSystem: Convert RunItem
MessageSystem->>User: Final Output
```
### Method Signatures
**Async Response Method:**
```python
async def get_response(
self,
message: str | list[TResponseInputItem],
sender_name: str | None = None,
context_override: dict[str, Any] | None = None,
hooks_override: RunHooks | None = None,
run_config_override: RunConfig | None = None,
file_ids: list[str] | None = None,
additional_instructions: str | None = None,
agency_context: AgencyContext | None = None,
**kwargs: Any,
) -> RunResult:
```
**Streaming Response Method:**
```python
def get_response_stream(
self,
message: str | list[TResponseInputItem],
sender_name: str | None = None,
context_override: dict[str, Any] | None = None,
hooks_override: RunHooks | None = None,
run_config_override: RunConfig | None = None,
file_ids: list[str] | None = None,
additional_instructions: str | None = None,
agency_context: AgencyContext | None = None,
**kwargs: Any,
) -> StreamingRunResponse:
```
资料来源：[src/agency_swarm/agent/core.py:95-160]()
## Configuration Options
### RunConfig Parameters
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `temperature` | `float` | `None` | Sampling temperature |
| `top_p` | `float` | `None` | Nucleus sampling threshold |
| `reasoning` | `Reasoning` | `None` | Reasoning configuration |
| `max_tokens` | `int` | `None` | Maximum output tokens |
### Message Filtering Options
| Option | Description |
|--------|-------------|
| `strict_mode` | Enable strict validation |
| `allowed_roles` | Restrict message roles |
| `max_length` | Maximum message length |
## Error Handling
The messaging system implements comprehensive error handling:
```python
try:
converted_item = item.to_input_item()
logger.debug(f"Converting {type(item).__name__} using SDK to_input_item()")
return converted_item
except Exception as e:
logger.warning(f"Failed to convert {type(item).__name__}")
return None
```
资料来源：[src/agency_swarm/agent/execution_helpers.py:85-95]()
## Usage Examples
### Basic Message Flow
```python
from agency_swarm import Agent
agent = Agent(name="Assistant")
# Synchronous message
result = await agent.get_response("Hello, how are you?")
print(result.final_output)
# Streaming message
stream = agent.get_response_stream("Tell me a story")
for event in stream:
print(event, end="", flush=True)
```
### Tool Message Handling
```python
# Tool results are automatically converted to message format
tool_result = {
"tool_call_id": "call_abc123",
"output": "File content here"
}
# Converted to TResponseInputItem automatically
```
## Best Practices
1. **Always provide `agency_context`** when agents communicate within an agency
2. **Use streaming** for long-running operations to improve responsiveness
3. **Implement guardrails** for input/output validation at the message level
4. **Monitor message size** to prevent token limit issues
5. **Handle conversion errors** gracefully with fallback mechanisms
---
## File Management
### 相关页面
相关主题：[Agent Internals](#page-agent-internal), [Tools System](#page-tools-system)
相关源码文件
以下源码文件用于生成本页说明：
- [src/agency_swarm/agent/file_manager.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/file_manager.py)
- [src/agency_swarm/agent/file_sync.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/file_sync.py)
- [src/agency_swarm/agent/attachment_manager.py](https://github.com/VRSEN/agency-swarm/blob/main/src/agency_swarm/agent/attachment_manager.py)
- [examples/agent_file_storage.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/agent_file_storage.py)
- [examples/message_attachments.py](https://github.com/VRSEN/agency-swarm/blob/main/examples/message_attachments.py)
# File Management
## Overview
File Management in Agency Swarm provides a comprehensive system for handling file uploads, vector store creation, file search capabilities, and message attachments across multi-agent workflows. The system enables agents to work with persistent file storage, search through uploaded documents, and exchange files as part of their communication protocols.
The file management architecture consists of three primary components that work together to provide seamless file handling: `FileManager`, `FileSync`, and `AttachmentManager`. Each serves a distinct role in the file lifecycle from upload through search and message integration.
资料来源：[examples/README.md]()
## Core Components
### FileManager
The `FileManager` class handles the core file operations for an agent, including uploading files to OpenAI's vector stores and managing file associations. It provides the primary interface for agents to work with persistent file storage.
**Key Responsibilities:**
- Upload files to OpenAI vector stores
- Associate files with specific agents
- Enable file search capabilities through vector store integration
- Manage file lifecycle within agent contexts
**API Reference:**
| Method | Parameters | Return Type | Description |
|--------|------------|-------------|-------------|
| `upload_file` | `file_path: str`, `include_in_vector_store: bool = True` | `str` | Upload a file and optionally add to vector store |
| `create_vector_store` | Various configuration params | `VectorStore` | Create a new vector store for the agent |
资料来源：[src/agency_swarm/agent/core.py:68-73]()
### FileSync
`FileSync` manages the synchronization of files across agent instances, ensuring that file references remain consistent when agents share context or communicate. It handles the transfer and validation of file metadata between agents in an agency.
### AttachmentManager
The `AttachmentManager` handles file attachments in messages, enabling agents to include files in their communications. This component supports multimodal outputs and file references within the message protocol.
资料来源：[examples/message_attachments.py]()
## Architecture
```mermaid
graph TD
subgraph "File Management Architecture"
FM[FileManager] --> VS[Vector Store]
FM --> A[Agent Instance]
FS[FileSync] --> FM
FS --> A2[Other Agents]
AM[AttachmentManager] --> M[Messages]
M --> A
VS --> FSR[File Search Results]
end
subgraph "External Services"
OpenAI[OpenAI API]
OpenAI --> VS
OpenAI --> M
end
```
## File Upload Workflow
Files can be uploaded to an agent's context using the `upload_file` method. The workflow follows a sequential process:
1. File is validated for existence and accessibility
2. File is uploaded to OpenAI's storage system
3. Optionally, file is indexed in a vector store for search
4. File reference is associated with the agent's session
```python
# From agent instance
agent = Agent(name="DocumentProcessor", ...)
# Upload file and include in vector store for search
file_id = agent.upload_file(
file_path="documents/report.pdf",
include_in_vector_store=True
)
```
资料来源：[src/agency_swarm/agent/core.py:68-73]()
## Vector Store Integration
Agency Swarm integrates with OpenAI's File Search tool through vector store creation. This enables agents to semantic search through uploaded documents.
```python
from agency_swarm import Agent
from agency_swarm.tools import FileSearchTool
agent = Agent(
name="ResearchAgent",
description="Processes and searches through research documents",
tools=[FileSearchTool], # Enables semantic file search
files_folder="./research_papers",
)
```
资料来源：[examples/agent_file_storage.py]()
资料来源：[examples/README.md]()
## File Handling in Messages
The AttachmentManager enables files to be included in agent messages, supporting multimodal interactions where agents can reference, process, and respond to file contents.
**Supported File Types:**
- Documents (PDF, TXT, MD)
- Images (PNG, JPG, GIF)
- Data files (CSV, JSON)
- Code files
**Output Types:**
| Type | Description | Use Case |
|------|-------------|----------|
| `ToolOutputImage` | Image outputs from tools | Visualization, charts |
| `ToolOutputFileContent` | File attachments in responses | Reports, generated documents |
| `ToolOutputFileFromUrl` | Remote file serving | PDF reports, external data |
资料来源：[examples/multimodal_outputs.py]()
## Agent Folder Structure
Agents that handle files should follow a specific folder structure:
```
AgentName/
├── files/ # Files uploaded to OpenAI
├── schemas/ # OpenAPI schemas for tool generation
├── tools/ # Custom tool implementations
├── AgentName.py # Main agent class
├── __init__.py # Package initialization
└── instructions.md # Agent instructions
```
资料来源：[CONTRIBUTING.md]()
资料来源：[README.md]()
## Configuration Options
### Agent File Configuration
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `files_folder` | `str` | `None` | Path to folder containing files to upload |
| `include_search_results` | `bool` | `False` | Include search results in responses |
| `schemas_folder` | `str` | `None` | Path to OpenAPI schema files |
### Model Settings for File Processing
When processing files, consider adjusting model settings for better performance:
```python
from agency_swarm import Agent, ModelSettings
from agency_swarm.util.builtins import Reasoning
agent = Agent(
name="FileAnalyzer",
model="gpt-5.4-mini",
model_settings=ModelSettings(
reasoning=Reasoning(effort="high", summary="auto")
),
)
```
资料来源：[examples/interactive/tui.py]()
## Examples
### Vector Store Creation and File Search
```python
# Complete example from agent_file_storage.py
from agency_swarm import Agent, Agency
# Create agent with file search capability
document_agent = Agent(
name="DocumentAgent",
description="Handles document storage and search",
tools=[FileSearchTool], # Built-in tool for semantic search
)
# Agency with document handling
agency = Agency([document_agent])
# Upload documents for search
response = agency.get_response_sync(
"Please analyze the quarterly_reports folder"
)
```
### Message Attachments
```python
# Example from message_attachments.py
from agency_swarm.tools.utils import (
tool_output_file_from_url,
tool_output_image_from_path
)
class GenerateReportTool(BaseTool):
def run(self) -> ToolOutputFileContent:
return tool_output_file_from_url(
"https://example.com/report.pdf"
)
```
资料来源：[examples/agent_file_storage.py]()
资料来源：[examples/message_attachments.py]()
## Best Practices
1. **File Organization**: Maintain clean `files/` directories per agent to avoid confusion in multi-agent setups
2. **Vector Store Management**: Only include files that need semantic search in vector stores to optimize costs and performance
3. **File Size Limits**: Be mindful of OpenAI's file size limits (512 MB maximum per file)
4. **Persistent Sessions**: Use `CustomizableChatHistory` for maintaining file context across sessions
5. **Tool Output Efficiency**: Use `tool_output_file_from_url` for remote files instead of downloading and re-uploading
资料来源：[examples/README.md]()
资料来源：[examples/custom_persistence.py]()
## Related Components
| Component | File Path | Purpose |
|-----------|-----------|---------|
| BaseTool | `src/agency_swarm/tools/` | Custom tool creation with file outputs |
| ToolFactory | `src/agency_swarm/tools/` | OpenAPI schema to tools conversion |
| FileSearchTool | `src/agency_swarm/tools/` | Built-in semantic search capability |
| OpenAI Integrations | `src/agency_swarm/integrations/` | External service file handling |
## Summary
The File Management system in Agency Swarm provides a robust foundation for handling file operations across multi-agent workflows. By leveraging `FileManager` for core operations, `FileSync` for cross-agent synchronization, and `AttachmentManager` for message integration, developers can build sophisticated agentic systems that process, search, and communicate with files seamlessly.
---
---
## Doramagic 踩坑日志
项目：VRSEN/agency-swarm
摘要：发现 23 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Chart Library tool for financial pattern analysis in agent swarms。
## 1. 安装坑 · 来源证据：Chart Library tool for financial pattern analysis in agent swarms
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Chart Library tool for financial pattern analysis in agent swarms
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_736c9d770ee34419ad2476f2a973e433 | https://github.com/VRSEN/agency-swarm/issues/596 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 2. 安装坑 · 来源证据：Feature request: native advisor/executor consult flow for stronger-model escalation
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature request: native advisor/executor consult flow for stronger-model escalation
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_1b01977e66ac46caa8a8b860da5bdafe | https://github.com/VRSEN/agency-swarm/issues/598 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 3. 安装坑 · 来源证据：Proposal: ClawMem adapter for thread persistence across sessions
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Proposal: ClawMem adapter for thread persistence across sessions
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_3bb24559ba48467ab0c8d43d3069d7f1 | https://github.com/VRSEN/agency-swarm/issues/594 | 来源类型 github_issue 暴露的待验证使用条件。
## 4. 安装坑 · 来源证据：CI-level governance checks for swarm agent code
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：CI-level governance checks for swarm agent code
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_b995c0dfb8a5460caa7cfde16ac1c7a4 | https://github.com/VRSEN/agency-swarm/issues/593 | 来源类型 github_issue 暴露的待验证使用条件。
## 5. 安装坑 · 来源证据：Feature: Runtime governance and compliance audit trails
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Feature: Runtime governance and compliance audit trails
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_4bd751455da0479bb37a014ef50934dd | https://github.com/VRSEN/agency-swarm/issues/592 | 来源类型 github_issue 暴露的待验证使用条件。
## 6. 安装坑 · 来源证据：v1.9.0 - Agent Swarm TUI and OpenClaw
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：v1.9.0 - Agent Swarm TUI and OpenClaw
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_445071ada1ba4d558d4ebea6ec395364 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 7. 配置坑 · 来源证据：v1.8.0 — Present and Accounted For
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.8.0 — Present and Accounted For
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_d270ab8e87c945878e308b78a2c8e7e6 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.8.0 | 来源类型 github_release 暴露的待验证使用条件。
## 8. 配置坑 · 来源证据：v1.9.2
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.9.2
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_2e69c962dcc44fd5a160047df0f18192 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.2 | 来源类型 github_release 暴露的待验证使用条件。
## 9. 配置坑 · 来源证据：v1.9.5
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.9.5
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_ec6832c5bd7b4083b4dd1a68c50f666f | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.5 | 来源类型 github_release 暴露的待验证使用条件。
## 10. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:719367294 | https://github.com/VRSEN/agency-swarm | README/documentation is current enough for a first validation pass.
## 11. 维护坑 · 来源证据：Research finding: Error detection failure rate in multi-agent chains — empirical data
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Research finding: Error detection failure rate in multi-agent chains — empirical data
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_8ef6210eff50485ba327057aa93e59d8 | https://github.com/VRSEN/agency-swarm/issues/609 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 12. 维护坑 · 来源证据：v1.9.4
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.9.4
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_333f10fed5354907b99a35bb5cba22a4 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.4 | 来源类型 github_release 暴露的待验证使用条件。
## 13. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:719367294 | https://github.com/VRSEN/agency-swarm | last_activity_observed missing
## 14. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:719367294 | https://github.com/VRSEN/agency-swarm | no_demo; severity=medium
## 15. 安全/权限坑 · 存在安全注意事项
- 严重度：medium
- 证据强度：source_linked
- 发现：No sandbox install has been executed yet; downstream must verify before user use.
- 对用户的影响：用户安装前需要知道权限边界和敏感操作。
- 建议检查：转成明确权限清单和安全审查提示。
- 防护动作：安全注意事项必须面向用户前置展示。
- 证据：risks.safety_notes | github_repo:719367294 | https://github.com/VRSEN/agency-swarm | No sandbox install has been executed yet; downstream must verify before user use.
## 16. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:719367294 | https://github.com/VRSEN/agency-swarm | no_demo; severity=medium
## 17. 安全/权限坑 · 来源证据：Enforceable agency chart — cryptographic delegation per agent role in the hierarchy
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Enforceable agency chart — cryptographic delegation per agent role in the hierarchy
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_3ca5d1cf8ec54c2083ed88c2adc8554f | https://github.com/VRSEN/agency-swarm/issues/595 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 18. 安全/权限坑 · 来源证据：Feature: Agent trust and discovery via MoltBridge integration
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature: Agent trust and discovery via MoltBridge integration
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_66c9e8a0b624449c8c4292c01efc6d0c | https://github.com/VRSEN/agency-swarm/issues/528 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 19. 安全/权限坑 · 来源证据：v1.9.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.9.1
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_952f33aba33c45debdfbfe4422b8789c | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。
## 20. 安全/权限坑 · 来源证据：v1.9.3
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.9.3
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_9290fb1e7b174e4a9fe0704355613635 | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.3 | 来源类型 github_release 暴露的待验证使用条件。
## 21. 安全/权限坑 · 来源证据：v1.9.7
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.9.7
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_8e9071bb39904407bc7514f299c9374d | https://github.com/VRSEN/agency-swarm/releases/tag/v1.9.7 | 来源类型 github_release 暴露的待验证使用条件。
## 22. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:719367294 | https://github.com/VRSEN/agency-swarm | issue_or_pr_quality=unknown
## 23. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:719367294 | https://github.com/VRSEN/agency-swarm | release_recency=unknown