ag2-quickstart

クイックスタート：最初の AG2 エージェントを構築する

使用するタイミング

• ユーザーが空のファイルから始めて、動作する AG2 エージェントを作りたい場合。
• どのプロバイダー設定を使えばよいか分からない場合。
• 会話のコンテキストを失わずに、後続のターンをつなげたい場合。
• より大きなタスクで、基本的なエージェント設定を骨組みとして使う場合。まずここから始め、関連する機能スキルを重ねてください。

前提条件

必須の手順：作業を完了する前に依存関係をインストールしてください。 AG2 コードを書いた後、対応するプロバイダー用エクストラ（およびタスクで必要な機能用エクストラ。例：ag-ui、tracing）をインストールします。次のインストールコマンドを実行してください：

pip install "ag2[openai]"   # 使用したプロバイダー／エクストラに置き換えてください

コマンドを実行できない場合は、正確な pip install コマンドを記載してください。これはタスクを完了するために必要な手順であり、任意の注記ではありません。

複数ファイルのプロジェクト（使い捨てのスクリプトではないもの）の場合は、使用したエクストラを指定して ag2 を固定する requirements.txt も用意してください（例：ag2[openai]>=0.14.0）。これにより、環境を再現可能にできます。

適切なプロバイダー用エクストラをインストールし、その API キーを用意してください。各 *Config にはプロバイダー SDK が必要です。一致するエクストラがないと、ImportError: ... requires optional dependencies. Install with pip install "ag2[<provider>]" が表示されます。

プロバイダー	インストール	環境変数	設定クラス
OpenAI	pip install "ag2[openai]"	OPENAI_API_KEY	OpenAIConfig、OpenAIResponsesConfig
Anthropic	pip install "ag2[anthropic]"	ANTHROPIC_API_KEY	AnthropicConfig
Gemini（API キー）	pip install "ag2[gemini]"	GEMINI_API_KEY（または GOOGLE_API_KEY）	GeminiConfig
Vertex AI（Gemini）	pip install "ag2[gemini]"	サービスアカウント／ADC	VertexAIConfig
Ollama（ローカル）	pip install "ag2[ollama]"	—	OllamaConfig
DashScope（Qwen）	pip install "ag2[dashscope]"	DASHSCOPE_API_KEY	DashScopeConfig

プロジェクトルートの .env から python-dotenv で環境変数を読み込むと、シェルでエクスポートしなくてもスクリプトからキーを利用できます：

from dotenv import load_dotenv
load_dotenv()  # reads .env at project root

見慣れないインポートエラーをデバッグする前に、簡単な動作確認を行い、想定した ag2 に対して実行していることを確認してください：

python -c "import sys, ag2; from importlib.metadata import version; print(sys.executable); print('ag2', version('ag2'))"

60 秒でできるレシピ

import asyncio
from ag2 import Agent
from ag2.config import OpenAIConfig

async def main() -> None:
    agent = Agent(
        "assistant",
        prompt="You are a helpful assistant. Reply in one sentence.",
        config=OpenAIConfig(model="gpt-4o-mini"),
    )

    # First turn
    reply = await agent.ask("What is the capital of France?")
    print(reply.body)

    # Continue the same conversation — context is preserved
    reply = await reply.ask("And of Germany?")
    print(reply.body)

asyncio.run(main())

Agent.ask(...) は新しいターンを開始し、AgentReply を返します。AgentReply.ask(...) はコンテキストと履歴を維持したまま、同じ会話を続けます。返信テキストは reply.body にあります。型付き出力については ag2-structured-output スキル（reply.content()）を参照してください。

プロバイダーの選択

各プロバイダーには ag2.config 内に独自の設定クラスがあります。すべての設定クラスで model=、任意の api_key=、および（対応している場合）streaming=True を指定できます。ストリーミングを推奨します。AG2 は非同期とストリーミングを優先して設計されています。

from ag2.config import OpenAIConfig          # gpt-4o, gpt-5-*, o-series, etc.
from ag2.config import OpenAIResponsesConfig # OpenAI Responses API (image gen, file_id support)
from ag2.config import AnthropicConfig       # claude-sonnet-4-6, claude-opus-4-7, etc.
from ag2.config import GeminiConfig          # Gemini Developer API (api_key)
from ag2.config import VertexAIConfig        # Gemini on Google Vertex AI (project + location)
from ag2.config import OllamaConfig          # local Ollama
from ag2.config import DashScopeConfig       # Alibaba Qwen

config = AnthropicConfig(model="claude-sonnet-4-6", streaming=True)

api_key= を省略すると、設定クラスは標準の環境変数（OPENAI_API_KEY、ANTHROPIC_API_KEY、GEMINI_API_KEY（または GOOGLE_API_KEY）など）を読み込みます。

OpenAI 互換エンドポイント（vLLM、LM Studio、Together、NVIDIA NIM など）には、base_url= を設定して OpenAIConfig を使用してください：

config = OpenAIConfig(
    model="qwen-3",
    base_url="http://localhost:8000/v1",
    api_key="NotRequired",  # pragma: allowlist secret
)

マルチターン — reply.ask() をつなげる

agent = Agent("planner", prompt="...", config=config)
reply = await agent.ask("Plan a 5-day Japan trip in late April.")
reply = await reply.ask("Budget is $2500 per person, two travellers.")
reply = await reply.ask("Prefer trains. Day-by-day itinerary.")
print(reply.body)

reply.ask() は以前のターンを引き継ぐため、LLM は制約を記憶しています。代わりに agent.ask(...) をもう一度呼び出すと、新しい会話が始まります。旅行プランナーの完全な例については、assets/multi_turn.py を参照してください。

モデル設定の再利用

設定は不変です。.copy(...) を使うと、上書きを適用した設定を複製できます：

base = OpenAIConfig(model="gpt-5")
hot = base.copy(temperature=0.8)
cheap = base.copy(model="gpt-5-mini")

リクエストごとにユーザー独自の API キーを指定する場合に便利な、ask ごとのモデル上書きもできます：

agent = Agent("assistant", prompt="Help.")
reply = await agent.ask("Hello!", config=OpenAIConfig(model="gpt-5", api_key="sk-..."))  # pragma: allowlist secret

ask ごとの設定は、そのターンに限りエージェントの設定を完全に置き換えます。

さらに詳しく

• 動作するスターター（単一ターン）：assets/hello_agent.py（code_examples/01 に対応）。
• マルチターンのスターター：assets/multi_turn.py（code_examples/03 に対応）。
• VertexAIConfig の認証、extra_body、カスタム httpx クライアント、環境変数のフォールバック表を含む、プロバイダーの完全なリファレンス：website/docs/user-guide/model_configuration.mdx。
• エージェント通信 API の概要（イベント、監視、HITL）：website/docs/user-guide/agents.mdx。
• 静的、動的、ターンごとのプロンプト：website/docs/user-guide/system_prompts.mdx。

よくある落とし穴

• await を忘れる — Agent／AgentReply のすべてのメソッドは非同期です。スクリプトでは asyncio.run(main()) でラップしてください。
• コンテキストが引き継がれると思って agent.ask() を 2 回呼び出す — 引き継がれません。代わりに reply.ask() を使用してください。
• API キーをハードコードする — 設定をそのままコミットできるよう、環境変数によるフォールバック（OPENAI_API_KEY など）を推奨します。
• streaming=True を省略する — AG2 はストリーミングを優先します。対応プロバイダーでこれを有効にしないと、ユーザー体験が損なわれます。
• ask ごとの config= は部分的なマージではなく、全体の上書きです — 設定する項目は慎重に選んでください。