AG2: Open-Source AgentOS for AI Agents

0.11.5 verified Mon Apr 13 auth: no python

AG2 (formerly AutoGen) is an open-source programming framework for building AI agents and facilitating cooperation among multiple agents to solve tasks. It provides fundamental building blocks to create, deploy, and manage AI agents, supporting various LLMs, tool use, autonomous and human-in-the-loop workflows, and multi-agent conversation patterns. The current version is 0.11.5 and it maintains a rapid release cadence with frequent updates and new features.

pip install "ag2[openai]"

Common errors

error ModuleNotFoundError: No module named 'ag2' ↓

cause The 'ag2' package is not installed in the Python environment.

fix

Install the 'ag2' package using pip: 'pip install ag2'.

error TypeError: Assistants.create() got an unexpected keyword argument 'file_ids' ↓

cause An older version of 'ag2' is incompatible with the OpenAI library version 1.21 or later.

fix

Upgrade 'ag2' to version 0.2.27 or higher: 'pip install --upgrade ag2'.

error Agents are throwing due to docker not running ↓

cause AG2 agents attempt to execute code within a Docker container, but Docker is not running.

fix

Ensure Docker is running, or disable Docker usage by setting 'use_docker' to 'False' in 'code_execution_config'.

error ModuleNotFoundError: No module named 'autogen' ↓

cause This error occurs because the official package name for the AG2 library on PyPI is `ag2` (or historically `autogen-agentchat`, `pyautogen`), but users might attempt to import from a module named `autogen` which might not be installed or is a different, unofficial package.

fix

Ensure you have installed the correct package, ag2, and import classes directly from the ag2 top-level module (or autogen if you are using an alias, after pip install ag2).

pip install ag2

Then in your Python code:

import ag2
# or, if you prefer the old alias, it should still work after installing ag2
import autogen 
from autogen import Agent, ConversableAgent

error AttributeError: module 'autogen' has no attribute 'Agent' ↓

cause This usually happens when an incorrect or outdated `autogen` package is installed (e.g., a stub package or an older version that doesn't expose the 'Agent' class directly under the `autogen` namespace) instead of the primary `ag2` package.

fix

First, uninstall any potentially conflicting autogen or pyautogen packages, then install or upgrade to the official ag2 package.

pip uninstall autogen pyautogen autogen-agentchat # uninstall all conflicting packages
pip install --upgrade ag2

Then ensure your imports are correct, typically from ag2 import Agent or import ag2 as autogen followed by autogen.Agent.

Warnings

breaking AG2 is transitioning from its original framework (autogen.agentchat) to a new, redesigned beta framework (autogen.beta) which will become the official v1.0. This will involve deprecations and architectural changes in upcoming minor versions (v0.12, v0.13, v0.14) before the beta becomes stable at v1.0. Users should plan for migration. ↓

fix Monitor the official AG2 documentation and release roadmap for migration guides and adopt the `autogen.beta` API for new projects to ensure future compatibility.

deprecated The `GPTAssistantAgent` class is deprecated as of v0.12 and will be removed in v0.14. Similarly, the `Swarm` orchestration pattern (and related functions like `initiate_swarm_chat()`) has been deprecated since v0.9 in favor of the new `GroupChat` pattern. ↓

fix Migrate from `GPTAssistantAgent` to `ConversableAgent`. For multi-agent orchestration, use the unified `GroupChat` pattern and its associated classes (`GroupChat`, `GroupChatManager`).

gotcha LLM provider packages are not installed by default with `pip install ag2`. Users must explicitly install them as extras (e.g., `pip install "ag2[openai]"`) for their chosen LLM provider to function. ↓

fix Install AG2 with the appropriate extra for your desired LLM provider, e.g., `pip install "ag2[openai]"`, `"ag2[gemini]"`, `"ag2[anthropic]"`, etc.

gotcha The `LLMConfig` object uses `deepcopy` internally to prevent unintended modifications. If `llm_config` contains custom objects that do not implement a `__deepcopy__` method, it can lead to `TypeError`. ↓

fix Ensure any custom objects passed within `LLMConfig` implement the `__deepcopy__` method to support deep copying.

security As of v0.11.4, `ShellExecutor` now uses `shell=False` with `shlex.split` to prevent shell command injection vulnerabilities. Previously, users might have inadvertently created insecure execution environments. ↓

fix Review any custom shell command execution logic. Ensure that commands passed to `ShellExecutor` are properly sanitized and do not rely on `shell=True` behavior if not explicitly intended and secured.

Install

pip install "ag2[gemini,anthropic]"

pip install ag2

Imports

ConversableAgent
```
from autogen import ConversableAgent
```
The primary class for creating flexible, conversational AI agents.
LLMConfig
```
from autogen import LLMConfig
```
Used to define the configuration for Language Model interactions.
GroupChat
```
from autogen import GroupChat
```
For orchestrating conversations among multiple agents.
GroupChatManager
```
from autogen import GroupChatManager
```
Manages the flow and speaker selection within a GroupChat.
Agent (beta)
wrong
```
from ag2 import Agent
```
correct
```
from autogen.beta import Agent
```
The `autogen.beta` module introduces a redesigned agent framework, which will become the official `ag2` v1.0 API. While `from ag2 import Agent` might be seen in some older examples or specific contexts, the future-proof path is `autogen.beta.Agent`.

Quickstart

This quickstart initializes a `ConversableAgent` with an OpenAI LLM configuration and runs a single-turn conversation. It demonstrates basic agent creation and interaction, requiring the `OPENAI_API_KEY` environment variable to be set.

import os
from autogen import ConversableAgent, LLMConfig

# Ensure your OpenAI API key is set as an environment variable
# For example: export OPENAI_API_KEY="YOUR_API_KEY"

openai_api_key = os.environ.get("OPENAI_API_KEY", "")

if not openai_api_key:
    print("Error: OPENAI_API_KEY environment variable is not set.")
    exit()

llm_config = LLMConfig(
    {
        "api_type": "openai",
        "model": "gpt-5-nano",
        "api_key": openai_api_key
    }
)

# Create a poetic AI assistant
my_agent = ConversableAgent(
    name="helpful_agent",
    system_message="You are a poetic AI assistant, respond in rhyme.",
    llm_config=llm_config,
)

# Run the agent with a prompt
response = my_agent.run(
    message="In one sentence, what's the big deal about AI?",
    max_turns=1, # Limit turns for a quick, non-interactive example
    user_input=False, # Disable human input for automatic execution
)

# Print the agent's final response
if response.chat_history:
    print(response.chat_history[-1]["content"])
else:
    print("No response generated.")