ag2

library1.0.3pypypi✓ verified 22d ago

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.

llm-agents ai-ml

pip install "ag2[openai]"

github ↗package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · AG2

ag2

llm-agentspythonv1.0.3

Install

7.8s avg

Import

8825ms

Disk

84MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.0.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.915 runs

installs and imports cleanly · install 0.0s · import 2.301s · 94MB

glibc

py 3.10–3.915 runs

installs and imports cleanly · install 7.8s · import 1.229s · 94MB

84MB installed

● package 84MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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)

✓ from autogen.beta import Agent

✗ from ag2 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`.

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.")

Debug

Known issues

breakingAG2 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.

affects: 0.11.x to 1.0

deprecatedThe `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`).

affects: 0.9+, 0.12+

gotchaLLM 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.

affects: 0.8+

gotchaThe `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.

affects: All versions

securityAs 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.

affects: 0.11.4+

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'ag2'

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

fix

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

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

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'.

Agents are throwing due to docker not running

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'.

ModuleNotFoundError: No module named 'autogen'

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`).
```bash
pip install ag2
```
Then in your Python code:
```python
import ag2
# or, if you prefer the old alias, it should still work after installing ag2
import autogen 
from autogen import Agent, ConversableAgent
```

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

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.
```bash
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`.

Upgrade

Version history

1.0.3latest on PyPI · released Aug 28, 2026

Audit

Dependencies

pythonrequiredRequires Python version >= 3.10 and < 3.14.

openaioptionalRequired for OpenAI LLM integrations. Other providers (e.g., Gemini, Anthropic) require installing their respective extras.

Agent activity

49 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ag2ai/ag2 ↗

packagehttps://pypi.org/project/ag2/ ↗

homepagehttps://ag2.ai/ ↗

docshttps://docs.ag2.ai ↗