📚 Documentation | 💡 Examples | 🤝 Contributing | 📝 Cite paper | 💬 Join Discord

AG2 was evolved from AutoGen. Fully open-sourced. We invite collaborators from all organizations to contribute.

AG2: Open-Source AgentOS for AI Agents

AG2 (formerly AutoGen) is an open-source programming framework for building AI agents and facilitating cooperation among multiple agents to solve tasks. AG2 aims to streamline the development and research of agentic AI. It offers features such as agents capable of interacting with each other, facilitates the use of various large language models (LLMs) and tool use support, autonomous and human-in-the-loop workflows, and multi-agent conversation patterns.

The project is currently maintained by a dynamic group of volunteers from several organizations. Contact project administrators Chi Wang and Qingyun Wu via [email protected] if you are interested in becoming a maintainer.

Table of contents

• AG2: Open-Source AgentOS for AI Agents
  • Table of contents
  • Getting started
    • Installation
    • Setup your API keys
    • Run your first agent
  • Example applications
  • Introduction of different agent concepts
    • Conversable agent
    • Human in the loop
    • Orchestrating multiple agents
    • Tools
    • Advanced agentic design patterns
  • Announcements
  • Contributors Wall
  • Code style and linting
  • Related papers
  • Cite the project
  • License

Getting started

For a step-by-step walk through of AG2 concepts and code, see Basic Concepts in our documentation.

Installation

AG2 requires Python version >= 3.9, < 3.14. AG2 is available via ag2 (or its alias pyautogen or autogen) on PyPI.

pip install ag2[openai]

Minimal dependencies are installed by default. You can install extra options based on the features you need.

Setup your API keys

To keep your LLM dependencies neat we recommend using the OAI_CONFIG_LIST file to store your API keys.

You can use the sample file OAI_CONFIG_LIST_sample as a template.

[
  {
    "model": "gpt-4o",
    "api_key": "<your OpenAI API key here>"
  }
]

Run your first agent

Create a script or a Jupyter Notebook and run your first agent.

from autogen import AssistantAgent, UserProxyAgent, LLMConfig

llm_config = LLMConfig.from_json(path="OAI_CONFIG_LIST")


with llm_config:
    assistant = AssistantAgent("assistant")
user_proxy = UserProxyAgent("user_proxy", code_execution_config={"work_dir": "coding", "use_docker": False})
user_proxy.initiate_chat(assistant, message="Plot a chart of NVDA and TESLA stock price change YTD.")
# This initiates an automated chat between the two agents to solve the task

Example applications

We maintain a dedicated repository with a wide range of applications to help you get started with various use cases or check out our collection of jupyter notebooks as a starting point.

• Build with AG2
• Jupyter Notebooks

Introduction of different agent concepts

We have several agent concepts in AG2 to help you build your AI agents. We introduce the most common ones here.

• Conversable Agent: Agents that are able to send messages, receive messages and generate replies using GenAI models, non-GenAI tools, or human inputs.
• Human in the loop: Add human input to the conversation
• Orchestrating multiple agents: Users can orchestrate multiple agents with built-in conversation patterns such as swarms, group chats, nested chats, sequential chats or customize the orchestration by registering custom reply methods.
• Tools: Programs that can be registered, invoked and executed by agents
• Advanced Concepts: AG2 supports more concepts such as structured outputs, rag, code execution, etc.

Conversable agent

The ConversableAgent is the fundamental building block of AG2, designed to enable seamless communication between AI entities. This core agent type handles message exchange and response generation, serving as the base class for all agents in the framework.

In the example below, we'll create a simple information validation workflow with two specialized agents that communicate with each other:

Note: Before running this code, make sure to set your OPENAI_API_KEY as an environment variable. This example uses gpt-4o-mini, but you can replace it with any other model supported by AG2.

# 1. Import ConversableAgent class
from autogen import ConversableAgent, LLMConfig

# 2. Define our LLM configuration for OpenAI's GPT-4o mini
#    uses the OPENAI_API_KEY environment variable
llm_config = LLMConfig(api_type="openai", model="gpt-4o-mini")


# 3. Create our LLM agent
with llm_config:
  # Create an AI agent
  assistant = ConversableAgent(
      name="assistant",
      system_message="You are an assistant that responds concisely.",
  )

  # Create another AI agent
  fact_checker = ConversableAgent(
      name="fact_checker",
      system_message="You are a fact-checking assistant.",
  )

# 4. Start the conversation
assistant.initiate_chat(
    recipient=fact_checker,
    message="What is AG2?",
    max_turns=2
)

Human in the loop

Human oversight is crucial for many AI workflows, especially when dealing with critical decisions, creative tasks, or situations requiring expert judgment. AG2 makes integrating human feedback seamless through its human-in-the-loop functionality. You can configure how and when human input is solicited using the human_input_mode parameter:

• ALWAYS: Requires human input for every response
• NEVER: Operates autonomously without human involvement
• TERMINATE: Only requests human input to end conversations

For convenience, AG2 provides the specialized UserProxyAgent class that automatically sets human_input_mode to ALWAYS and supports code execution:

Note: Before running this code, make sure to set your OPENAI_API_KEY as an environment variable. This example uses gpt-4o-mini, but you can replace it with any other model supported by AG2.

# 1. Import ConversableAgent and UserProxyAgent classes
from autogen import ConversableAgent, UserProxyAgent, LLMConfig

# 2. Define our LLM configuration for OpenAI's GPT-4o mini
#    uses the OPENAI_API_KEY environment variable
llm_config = LLMConfig(api_type="openai", model="gpt-4o-mini")


# 3. Create our LLM agent
with llm_config:
  assistant = ConversableAgent(
      name="assistant",
      system_message="You are a helpful assistant.",
  )

# 4. Create a human agent with manual input mode
human = ConversableAgent(
    name="human",
    human_input_mode="ALWAYS"
)
# or
human = UserProxyAgent(name="human", code_execution_config={"work_dir": "coding", "use_docker": False})

# 5. Start the chat
human.initiate_chat(
    recipient=assistant,
    message="Hello! What's 2 + 2?"
)

Orchestrating multiple agents

AG2 enables sophisticated multi-agent collaboration through flexible orchestration patterns, allowing you to create dynamic systems where specialized agents work together to solve complex problems.

The framework offers both custom orchestration and several built-in collaboration patterns including GroupChat and Swarm.

Here's how to implement a collaborative team for curriculum development using GroupChat:

Note: Before running this code, make sure to set your OPENAI_API_KEY as an environment variable. This example uses gpt-4o-mini, but you can replace it with any other model supported by AG2.

from autogen import ConversableAgent, GroupChat, GroupChatManager, LLMConfig

# Put your key in the OPENAI_API_KEY environment variable
llm_config = LLMConfig(api_type="openai", model="gpt-4o-mini")

planner_message = """You are a classroom lesson agent.
Given a topic, write a lesson plan for a fourth grade class.
Use the following format:
<title>Lesson plan title</title>
<learning_objectives>Key learning objectives</learning_objectives>
<script>How to introduce the topic to the kids</script>
"""

reviewer_message = """You are a classroom lesson reviewer.
You compare the lesson plan to the fourth grade curriculum and provide a maximum of 3 recommended changes.
Provide only one round of reviews to a lesson plan.
"""

# 1. Add a separate 'description' for our planner and reviewer agents
planner_description = "Creates or revises lesson plans."

reviewer_description = """Provides one round of reviews to a lesson plan
for the lesson_planner to revise."""

with llm_config:
    lesson_planner = ConversableAgent(
        name="planner_agent",
        system_message=planner_message,
        description=planner_description,
    )

    lesson_reviewer = ConversableAgent(
        name="reviewer_agent",
        system_message=reviewer_message,
        description=reviewer_description,
    )

# 2. The teacher's system message can also be used as a description, so we don't define it
teacher_message = """You are a classroom teacher.
You decide topics for lessons and work with a lesson planner.
and reviewer to create and finalise lesson plans.
When you are happy with a lesson plan, output "DONE!".
"""

with llm_config:
    teacher = ConversableAgent(
        name="teacher_agent",
        system_message=teacher_message,
        # 3. Our teacher can end the conversation by saying DONE!
        is_termination_msg=lambda x: "DONE!" in (x.get("content", "") or "").upper(),
    )

# 4. Create the GroupChat with agents and selection method
groupchat = GroupChat(
    agents=[teacher, lesson_planner, lesson_reviewer],
    speaker_selection_method="auto",
    messages=[],
)

# 5. Our GroupChatManager will manage the conversation and uses an LLM to select the next agent
manager = GroupChatManager(
    name="group_manager",
    groupchat=groupchat,
    llm_config=llm_config,
)

# 6. Initiate the chat with the GroupChatManager as the recipient
teacher.initiate_chat(
    recipient=manager,
    message="Today, let's introduce our kids to the solar system."
)

When executed, this code creates a collaborative system where the teacher initiates the conversation, and the lesson planner and reviewer agents work together to create and refine a lesson plan. The GroupChatManager orchestrates the conversation, selecting the next agent to respond based on the context of the discussion.

For workflows requiring more structured processes, explore the Swarm pattern in the detailed documentation.

Tools

Agents gain significant utility through tools as they provide access to external data, APIs, and functionality.

Note: Before running this code, make sure to set your OPENAI_API_KEY as an environment variable. This example uses gpt-4o-mini, but you can replace it with any other model supported by AG2.

from datetime import datetime
from typing import Annotated

from autogen import ConversableAgent, register_function, LLMConfig

# Put your key in the OPENAI_API_KEY environment variable
llm_config = LLMConfig(api_type="openai", model="gpt-4o-mini")

# 1. Our tool, returns the day of the week for a given date
def get_weekday(date_string: Annotated[str, "Format: YYYY-MM-DD"]) -> str:
    date = datetime.strptime(date_string, "%Y-%m-%d")
    return date.strftime("%A")

# 2. Agent for determining whether to run the tool
with llm_config:
    date_agent = ConversableAgent(
        name="date_agent",
        system_message="You get the day of the week for a given date.",
    )

# 3. And an agent for executing the tool
executor_agent = ConversableAgent(
    name="executor_agent",
    human_input_mode="NEVER",
)

# 4. Registers the tool with the agents, the description will be used by the LLM
register_function(
    get_weekday,
    caller=date_agent,
    executor=executor_agent,
    description="Get the day of the week for a given date",
)

# 5. Two-way chat ensures the executor agent follows the suggesting agent
chat_result = executor_agent.initiate_chat(
    recipient=date_agent,
    message="I was born on the 25th of March 1995, what day was it?",
    max_turns=2,
)

print(chat_result.chat_history[-1]["content"])

Advanced agentic design patterns

AG2 supports more advanced concepts to help you build your AI agent workflows. You can find more information in the documentation.

• Structured Output
• Ending a conversation
• Retrieval Augmented Generation (RAG)
• Code Execution
• Tools with Secrets

Announcements

🔥 🎉 Nov 11, 2024: We are evolving AutoGen into AG2! A new organization AG2AI is created to host the development of AG2 and related projects with open governance. Check AG2's new look.

📄 License: We adopt the Apache 2.0 license from v0.3. This enhances our commitment to open-source collaboration while providing additional protections for contributors and users alike.

🎉 May 29, 2024: DeepLearning.ai launched a new short course AI Agentic Design Patterns with AutoGen, made in collaboration with Microsoft and Penn State University, and taught by AutoGen creators Chi Wang and Qingyun Wu.

🎉 May 24, 2024: Foundation Capital published an article on Forbes: The Promise of Multi-Agent AI and a video AI in the Real World Episode 2: Exploring Multi-Agent AI and AutoGen with Chi Wang.

🎉 Apr 17, 2024: Andrew Ng cited AutoGen in The Batch newsletter and What's next for AI agentic workflows at Sequoia Capital's AI Ascent (Mar 26).

More Announcements

Contributors Wall

Code style and linting

This project uses pre-commit hooks to maintain code quality. Before contributing:

1. Install pre-commit:

pip install pre-commit
pre-commit install

2. The hooks will run automatically on commit, or you can run them manually:

pre-commit run --all-files

Related papers

• AutoGen: Enabling Next-Gen LLM Applications via Multi-Agent Conversation

• EcoOptiGen: Hyperparameter Optimization for Large Language Model Generation Inference

• MathChat: Converse to Tackle Challenging Math Problems with LLM Agents

• AgentOptimizer: Offline Training of Language Model Agents with Functions as Learnable Weights

• StateFlow: Enhancing LLM Task-Solving through State-Driven Workflows

Cite the project

@software{AG2_2024,
author = {Chi Wang and Qingyun Wu and the AG2 Community},
title = {AG2: Open-Source AgentOS for AI Agents},
year = {2024},
url = {https://github.com/ag2ai/ag2},
note = {Available at https://docs.ag2.ai/},
version = {latest}
}

License

This project is licensed under the Apache License, Version 2.0 (Apache-2.0).

This project is a spin-off of AutoGen and contains code under two licenses:

• The original code from https://github.com/microsoft/autogen is licensed under the MIT License. See the LICENSE_original_MIT file for details.

• Modifications and additions made in this fork are licensed under the Apache License, Version 2.0. See the LICENSE file for the full license text.

We have documented these changes for clarity and to ensure transparency with our user and contributor community. For more details, please see the NOTICE file.