How to Use AG2 Framework Tools and Integrations

AG2 is an open-source framework for building multi-agent AI applications that evolved from Microsoft's AutoGen project. The framework enables developers to create systems where multiple AI agents collaborate autonomously on complex tasks.

The core philosophy behind AG2 centers on agent conversation patterns. Unlike single-agent systems that handle tasks in isolation, AG2 agents communicate with each other, delegate subtasks, and coordinate their efforts. This approach mirrors how human teams work together on projects.

Key characteristics of AG2:

• Multi-agent conversations: Agents interact through structured dialogues, not isolated function calls
• Autonomous task solving: Agents can plan, execute, and iterate without constant human intervention
• Human-in-the-loop support: Built-in mechanisms for human oversight and intervention when needed
• Flexible agent roles: Configure agents as assistants, executors, critics, or custom roles

AG2 moved to community governance after diverging from AutoGen, establishing its own development roadmap focused on stability, developer experience, and production readiness. The framework currently powers numerous production agent applications across research, enterprise automation, and developer tooling.

AG2 and AutoGen share common ancestry but have developed distinct identities. Understanding these differences helps developers choose the right framework and migrate existing projects.

Historical context:

AutoGen emerged from Microsoft Research as an experimental framework for multi-agent conversations. AG2 began as a community-maintained fork that prioritized stability and production use cases. Over time, the projects diverged sufficiently that AG2 became its own entity with separate governance and release cycles.

Key differences:

Architecture approach: AutoGen emphasizes rapid prototyping and research flexibility. AG2 focuses on predictable, production-ready patterns with better error handling and state management.

Tool ecosystem: AG2 developed its own tool registration and execution patterns, while AutoGen maintains closer ties to Microsoft's ecosystem. AG2's approach offers more flexibility for custom integrations.

Community and support: AG2 operates under independent community governance with contributions from multiple organizations. AutoGen remains primarily Microsoft-maintained.

Migration considerations: Code written for older AutoGen versions typically requires updates for AG2 compatibility, particularly around agent configuration and tool registration patterns. AG2 provides migration guides for common scenarios.

Most new multi-agent projects choose AG2 for its stability guarantees and broader integration ecosystem. Research projects requiring bleeding-edge features sometimes prefer AutoGen's experimental branch.

AG2 organizes tools into functional categories based on what capabilities they add to agent systems. Understanding these categories helps you select the right tools for your use case.

Communication Tools

These tools enable agents to interact with external messaging platforms and notification systems:

• DiscordAgent: Send and retrieve messages from Discord channels
• SlackAgent: Send messages to Slack workspaces for team notifications
• TelegramAgent: Bot integration for Telegram messaging

These agents wrap platform APIs with AG2's conversation patterns, allowing your agents to participate in human communication channels naturally.

Web Interaction Tools

Tools for accessing and processing web content:

• WebSurferAgent: Built-in web browsing with automatic navigation, form filling, and content extraction
• Browser Use integration: Programmatic browser control for complex web workflows
• Crawl4AI integration: Structured data extraction from websites

These tools differ from simple HTTP clients by maintaining session state, handling JavaScript-rendered content, and extracting semantic information rather than just raw HTML.

Code Execution Tools

AG2 supports multiple code execution environments:

• Local code executor: Run Python code in isolated local environments
• Docker executor: Containerized execution for reproducibility and security
• Jupyter integration: Execute code in persistent notebook kernels

Code execution tools follow AG2's two-step pattern: an agent proposes code to run, and an executor agent handles the actual execution. This separation allows for review and validation before execution.

Research and Analysis Tools

Specialized tools for information gathering:

• DeepResearchAgent: Automated research workflows with source tracking
• RetrieveChat: RAG-powered conversations with document collections
• Vector store support: Pinecone, Weaviate, Chroma, and other vector databases

One of AG2's strengths is its ability to incorporate tools from other AI frameworks. This interoperability prevents vendor lock-in and lets you combine the best capabilities from different ecosystems.

LangChain Tools Integration

LangChain offers hundreds of pre-built tools for APIs, databases, and services. AG2 can use these through its interoperability layer:

from autogen.interop import Interoperability
from langchain_community.tools import WikipediaQueryRun


wikipedia_tool = WikipediaQueryRun()


ag2_tool = Interoperability.convert_tool(wikipedia_tool, "wikipedia")


agent.register_for_llm(ag2_tool)

The conversion process handles type mapping, documentation transfer, and execution routing automatically. Over 200 LangChain tools work out of the box with AG2.

CrewAI Tools Integration CrewAI's specialized agent tools integrate similarly:

from crewai_tools import SerperDevTool
from autogen.interop import Interoperability


search_tool = SerperDevTool()


ag2_search = Interoperability.convert_tool(search_tool, "web_search")

This integration is particularly valuable for teams migrating from CrewAI or combining both frameworks' strengths.

PydanticAI Tools Integration PydanticAI's type-safe tools work with AG2's validation layer:

from pydantic_ai import Tool
from autogen.interop import Interoperability


validated_tool = Tool(my_function, retries=3)


ag2_validated = Interoperability.convert_tool(validated_tool, "validated_function")

The interoperability layer preserves type validation and retry logic when converting PydanticAI tools.

Production agent systems need reliable storage for files, conversation history, and intermediate outputs. Here are the primary approaches for adding file storage to AG2 agents.

Local File System Storage

For development and single-machine deployments:

import os
from pathlib import Path


WORKSPACE_DIR = Path("./agent_workspace")
WORKSPACE_DIR.mkdir(exist_ok=True)


def save_agent_output(filename: str, content: str) -> str:
    filepath = WORKSPACE_DIR / filename
    filepath.write_text(content)
    return str(filepath)

Local storage works for prototyping but lacks durability, sharing capabilities, and redundancy for production.

Cloud Object Storage

Direct integration with S3-compatible storage:

import boto3

s3_client = boto3.client('s3')

def upload_to_s3(filename: str, content: bytes, bucket: str) -> str:
    s3_client.put_object(Bucket=bucket, Key=filename, Body=content)
    return f"s3://{bucket}/{filename}"

Cloud storage provides durability and scalability but requires managing credentials, permissions, and access patterns separately from your agent logic.

Intelligent Workspace Storage with MCP

For teams building multi-agent applications, Fast.io's MCP server provides purpose-built storage with 251 tools accessible through the Model Context Protocol:

Key advantages for AG2 agents:

• Automatic indexing: Files become searchable by content and meaning through built-in RAG
• Multi-agent coordination: File locks prevent conflicts when multiple agents access the same files
• Ownership transfer: Agents can create workspaces and transfer them to human users
• No local I/O: Agents pull files from Google Drive, OneDrive, Box, and Dropbox via URL import
• Free tier: 50GB storage, 5,000 monthly credits, no credit card required

The MCP approach separates storage concerns from agent logic while providing rich capabilities through a standardized protocol.

Give Your AI Agents Persistent Storage

Give your AG2 agents persistent storage with built-in RAG indexing. Fast.io provides 251 MCP tools, 50GB free storage, and seamless multi-agent coordination. No credit card required.

Start Building Free

Let's walk through building a practical AG2 application that demonstrates tool usage, storage integration, and multi-agent collaboration.

Application Overview: Research Assistant

Our application consists of three agents working together:

Research Agent: Uses web search and browsing tools to gather information 2.

Analysis Agent: Processes and synthesizes findings using code execution 3.

Storage Agent: Manages documents and persists results

Step 1: Configure the Agents

from autogen import ConversableAgent, LLMConfig

llm_config = LLMConfig(
    config_list=[{
        "model": "gpt-4",
        "api_key": os.environ["OPENAI_API_KEY"]
    }]
)


researcher = ConversableAgent(
    name="researcher",
    system_message="You are a research assistant. Use web search and browsing tools to gather accurate information.",
    llm_config=llm_config
)


analyzer = ConversableAgent(
    name="analyzer",
    system_message="You analyze research findings and write Python code to process data when needed.",
    llm_config=llm_config
)


storage = ConversableAgent(
    name="storage",
    system_message="You manage files and storage operations.",
    llm_config=llm_config
)

Step 2: Register Tools

from autogen.tools import tool

@tool(description="Search the web for information")
def web_search(query: str) -> str:
    
    pass

@tool(description="Read a file from storage")
def read_file(filepath: str) -> str:
    
    pass

@tool(description="Write content to a file")
def write_file(filepath: str, content: str) -> str:
    
    pass

### Register tools with appropriate agents
researcher.register_for_llm(web_search)
storage.register_for_execution(read_file, write_file)

Step 3: Orchestrate the Conversation ```python

researcher.initiate_chat( analyzer, message="Research the current state of renewable energy adoption in Europe. Search for recent statistics and trends.", max_turns=10 )

analyzer.initiate_chat( storage, message="Save the research findings to /workspace/renewable_energy_report.md", max_turns=5 )

#### Production Considerations

**Error handling**: Wrap tool executions in try-catch blocks and implement retry logic for transient failures.

**State persistence**: Save conversation states periodically to resume interrupted workflows.

**Rate limiting**: Implement delays and backoff strategies when calling external APIs.

**Security**: Use dependency injection for API keys and credentials rather than hardcoding them in agent configurations.

**Monitoring**: Log agent decisions, tool usage, and conversation flows for debugging and auditing.

After working with AG2 across multiple production deployments, certain patterns consistently produce better results.

Tool Design Guidelines

Keep tools focused: Each tool should do one thing well. A "search_and_summarize" tool is harder to debug than separate "search" and "summarize" tools that agents can combine.

Document thoroughly: AG2 agents rely on function docstrings and type annotations to understand tool capabilities. Include examples in descriptions:

@tool(description="Calculate shipping costs for a given weight and destination")
def calculate_shipping(weight_kg: float, destination: str) -> dict:
    pass

Handle errors gracefully: Tools should return informative error messages rather than raising exceptions. Agents can often recover from errors or try alternative approaches when given clear feedback.

Agent Configuration Patterns

Use specific system messages: Vague instructions like "you are a helpful assistant" produce vague results. Specificity matters:

• Bad: "You handle files"
• Good: "You manage file operations in /workspace. Always confirm file paths before writing. Log all operations."

Limit conversation length: Set max_turns to prevent infinite loops. Most tasks complete within a reasonable number of turns.

Implement human checkpoints: For critical operations, add human proxy agents that pause execution for approval:

human_proxy = ConversableAgent(
    name="human",
    human_input_mode="ALWAYS"  # Pauses for human input
)

Performance Optimization Cache tool results: Expensive operations like web searches benefit from caching:

from functools import lru_cache

@lru_cache(maxsize=100)
@tool(description="Search with caching")
def cached_search(query: str) -> str:
    return expensive_search_operation(query)

Parallel execution: When agents can work independently, run conversations in parallel rather than sequentially.

Selective tool registration: Only register tools an agent actually needs. Fewer options reduce decision time and improve accuracy.