CLI Overview

The AG2 CLI (ag2) is a terminal tool for the full agent development lifecycle — from scaffolding projects to running, testing, serving, and publishing agents.

Installation#

pip install ag2-cli

Verify it's installed:

ag2 --help

Commands at a Glance#

Command	Description
`ag2 run`	Execute an agent with a message
`ag2 chat`	Interactive terminal chat session
`ag2 create`	Scaffold projects, agents, tools, and teams
`ag2 serve`	Expose agents as REST, MCP, or A2A endpoints
`ag2 test`	Run evaluation suites and benchmarks
`ag2 install`	Install skills, templates, tools, and more
`ag2 replay`	Replay and debug past sessions
`ag2 arena`	A/B test agent implementations
`ag2 proxy`	Wrap CLIs, APIs, or modules as AG2 tools
`ag2 publish`	Publish artifacts to the AG2 registry

Quick Start#

Create a new project and run it:

ag2 create project my-app --template blank
cd my-app
ag2 run main.py --message "Hello, agent!"

Or run an existing agent file:

ag2 run my_agent.py --message "Summarize this document"

Start an interactive chat session:

ag2 chat my_agent.py

Agent Discovery#

Most commands (run, chat, serve, test) need to find an agent in your Python file. The CLI looks for these in order:

A main() function
A module-level variable named agent or team
A module-level list named agents
Any single ConversableAgent instance

You can also use YAML config files instead of Python:

agent.yaml

llm:
  model: gpt-4o-mini

agents:
  - name: assistant
    system_message: "You are a helpful assistant."

ag2 run agent.yaml --message "Hello"