コンポーネントガイドに移行します。AutoGen は ChatCompletion API を使用するための組み込みモデルクライアント群を提供しており、すべてのモデルクライアントは ChatCompletionClient プロトコルクラスを実装しています。

AutoGen Core : コンポーネントガイド : モデル・クライアント

作成 : クラスキャット・セールスインフォメーション
作成日時 : 04/15/2025

* 本記事は github microsoft/autogen の以下のページを独自に翻訳した上でまとめ直し、補足説明を加えています :

AutoGen Core : Components Guide : Model Clients

* サンプルコードの動作確認はしておりますが、必要な場合には適宜、追加改変しています。
* ご自由にリンクを張って頂いてかまいませんが、sales-info@classcat.com までご一報いただけると嬉しいです。

クラスキャット人工知能研究開発支援サービス ⭐️ リニューアルしました 😉

◆ クラスキャットは人工知能に関する各種サービスを提供しています。お気軽にご相談ください :

人工知能導入個別相談会(無償)実施中！ [詳細]
人工知能研究開発支援 [詳細]
1. 自社特有情報を含むチャットボット構築支援
2. 画像認識 (医療系含む) / 画像生成
PoC(概念実証)を失敗させないための支援 [詳細]

◆ お問合せ : 下記までお願いします。

クラスキャット セールス・インフォメーション
sales-info@classcat.com
ClassCatJP

AutoGen Core : コンポーネントガイド : モデル・クライアント

AutoGen は ChatCompletion API を使用するために組み込みモデルクライアント群を提供しています。すべてのモデルクライアントは ChatCompletionClient プロトコル・クラスを実装しています。

現在、以下の組み込みモデルクライアントをサポートしています :

OpenAIChatCompletionClient : OpenAI モデルと OpenAI API 互換モデル (e.g., Gemini)
AzureOpenAIChatCompletionClient : Azure OpenAI モデル向け。
AzureAIChatCompletionClient : GitHub モデルと Azure にホストされているモデル向け。
OllamaChatCompletionClient (Experimental) : Ollama でホストされているローカルモデル向け。
AnthropicChatCompletionClient (Experimental) : Anthropic にホストされているモデル向け。
SKChatCompletionAdapter : Semantic Kernel AI コネクタ用アダプター。

これらのモデルクライアントの使用方法の詳細については、各クライアントのドキュメントを参照してください。

モデル呼び出しのログ記録

AutoGen はモデル呼び出しや応答のようなイベントをログ記録するために標準 Python ロギング・モジュールを使用します。ロガー名は autogen_core.EVENT_LOGGER_NAME で、イベントタイプは LLMCall です。

import logging

from autogen_core import EVENT_LOGGER_NAME

logging.basicConfig(level=logging.WARNING)
logger = logging.getLogger(EVENT_LOGGER_NAME)
logger.addHandler(logging.StreamHandler())
logger.setLevel(logging.INFO)

モデルクライアントの呼び出し

モデルクライアントを呼び出すに、create() メソッドを使用できます。この例は OpenAIChatCompletionClient を使用して OpenAI モデルを呼び出しています。

from autogen_core.models import UserMessage
from autogen_ext.models.openai import OpenAIChatCompletionClient

model_client = OpenAIChatCompletionClient(
    model="gpt-4", temperature=0.3
)  # assuming OPENAI_API_KEY is set in the environment.

result = await model_client.create([UserMessage(content="What is the capital of France?", source="user")])
print(result)

finish_reason='stop' content='The capital of France is Paris.' usage=RequestUsage(prompt_tokens=15, completion_tokens=8) cached=False logprobs=None thought=None

ストリーミング・トークン

create_stream() メソッドを使用してトークンチャンクをストリーミングするチャット生成 (completion) リクエストを作成できます。

from autogen_core.models import CreateResult, UserMessage
from autogen_ext.models.openai import OpenAIChatCompletionClient

model_client = OpenAIChatCompletionClient(model="gpt-4o")  # assuming OPENAI_API_KEY is set in the environment.

messages = [
    UserMessage(content="Write a very short story about a dragon.", source="user"),
]

# Create a stream.
stream = model_client.create_stream(messages=messages)

# Iterate over the stream and print the responses.
print("Streamed responses:")
async for chunk in stream:  # type: ignore
    if isinstance(chunk, str):
        # The chunk is a string.
        print(chunk, flush=True, end="")
    else:
        # The final chunk is a CreateResult object.
        assert isinstance(chunk, CreateResult) and isinstance(chunk.content, str)
        # The last response is a CreateResult object with the complete message.
        print("\n\n------------\n")
        print("The complete response:", flush=True)
        print(chunk.content, flush=True)

Streamed responses:
In the heart of an ancient forest, beneath the shadow of snow-capped peaks, a dragon named Elara lived secretly for centuries. Elara was unlike any dragon from the old tales; her scales shimmered with a deep emerald hue, each scale engraved with symbols of lost wisdom. The villagers in the nearby valley spoke of mysterious lights dancing across the night sky, but none dared venture close enough to solve the enigma.

One cold winter's eve, a young girl named Lira, brimming with curiosity and armed with the innocence of youth, wandered into Elara’s domain. Instead of fire and fury, she found warmth and a gentle gaze. The dragon shared stories of a world long forgotten and in return, Lira gifted her simple stories of human life, rich in laughter and scent of earth.

From that night on, the villagers noticed subtle changes—the crops grew taller, and the air seemed sweeter. Elara had infused the valley with ancient magic, a guardian of balance, watching quietly as her new friend thrived under the stars. And so, Lira and Elara’s bond marked the beginning of a timeless friendship that spun tales of hope whispered through the leaves of the ever-verdant forest.

------------

The complete response:
In the heart of an ancient forest, beneath the shadow of snow-capped peaks, a dragon named Elara lived secretly for centuries. Elara was unlike any dragon from the old tales; her scales shimmered with a deep emerald hue, each scale engraved with symbols of lost wisdom. The villagers in the nearby valley spoke of mysterious lights dancing across the night sky, but none dared venture close enough to solve the enigma.

------------

The token usage was:
RequestUsage(prompt_tokens=0, completion_tokens=0)

Note : ストリーミング・レスポンスの最後のレスポンスは常にタイプ CreateResult の最後のレスポンスになります。

Note : デフォルトの使用レスポンスはゼロ値を返します。使用を有効にするには、詳細は create_stream() をご覧ください。

構造化出力

OpenAIChatCompletionClient と AzureOpenAIChatCompletionClient の response_format フィールドを Pydantic BaseModel クラスに設定することで構造化出力を有効にできます。

Note : 構造化出力はそれをサポートするモデルに対してのみ利用可能です。それはまた構造化出力をサポートするモデルクライアントが必要です。現在、OpenAIChatCompletionClient と AzureOpenAIChatCompletionClient が構造化出力をサポートしています。

from typing import Literal

from pydantic import BaseModel


# The response format for the agent as a Pydantic base model.
class AgentResponse(BaseModel):
    thoughts: str
    response: Literal["happy", "sad", "neutral"]


# Create an agent that uses the OpenAI GPT-4o model with the custom response format.
model_client = OpenAIChatCompletionClient(
    model="gpt-4o",
    response_format=AgentResponse,  # type: ignore
)

# Send a message list to the model and await the response.
messages = [
    UserMessage(content="I am happy.", source="user"),
]
response = await model_client.create(messages=messages)
assert isinstance(response.content, str)
parsed_response = AgentResponse.model_validate_json(response.content)
print(parsed_response.thoughts)
print(parsed_response.response)

# Close the connection to the model client.
await model_client.close()

I'm glad to hear that you're feeling happy! It's such a great emotion that can brighten your whole day. Is there anything in particular that's bringing you joy today? 😊
happy

create() メソッドの extra_create_args パラメータを使用して response_format フィールドを設定し、各リクエストに対して構造化出力を設定することもできます。

モデルレスポンスのキャッシュ

autogen_ext は任意の ChatCompletionClient をラップできる ChatCompletionCache を実装しています。このラッパーの使用は、同じプロンプトで基盤クライアントに複数回クエリする場合、発生するトークン使用を回避できます。

ChatCompletionCache は CacheStore プロトコルを使用しています。DiskCacheStore と RedisStore を含む CacheStore の幾つかの有用なバリアントを実装しました。

ローカルキャッシュ用に diskcache を使用した例です :

# pip install -U "autogen-ext[openai, diskcache]"

import asyncio
import tempfile

from autogen_core.models import UserMessage
from autogen_ext.cache_store.diskcache import DiskCacheStore
from autogen_ext.models.cache import CHAT_CACHE_VALUE_TYPE, ChatCompletionCache
from autogen_ext.models.openai import OpenAIChatCompletionClient
from diskcache import Cache


async def main() -> None:
    with tempfile.TemporaryDirectory() as tmpdirname:
        # Initialize the original client
        openai_model_client = OpenAIChatCompletionClient(model="gpt-4o")

        # Then initialize the CacheStore, in this case with diskcache.Cache.
        # You can also use redis like:
        # from autogen_ext.cache_store.redis import RedisStore
        # import redis
        # redis_instance = redis.Redis()
        # cache_store = RedisCacheStore[CHAT_CACHE_VALUE_TYPE](redis_instance)
        cache_store = DiskCacheStore[CHAT_CACHE_VALUE_TYPE](Cache(tmpdirname))
        cache_client = ChatCompletionCache(openai_model_client, cache_store)

        response = await cache_client.create([UserMessage(content="Hello, how are you?", source="user")])
        print(response)  # Should print response from OpenAI
        response = await cache_client.create([UserMessage(content="Hello, how are you?", source="user")])
        print(response)  # Should print cached response

        await openai_model_client.close()
        await cache_client.close()


asyncio.run(main())

True

キャッシュされたレスポンスの前後で cached_client.total_usage() (or model_client.total_usage()) を検査すると、同一のカウントが生成されるはずです。

キャッシュは、cached_client.create or cached_client.create_stream に提供された正確な引数にセンシティブなので、ツールや json_output 引数の変更はキャッシュミスに繋がる可能性があることに注意してください。

モデルクライアントでエージェントを構築する

ChatCompletion API を使用して、メッセージに応答できる単純な AI エージェントを作成しましょう。

from dataclasses import dataclass

from autogen_core import MessageContext, RoutedAgent, SingleThreadedAgentRuntime, message_handler
from autogen_core.models import ChatCompletionClient, SystemMessage, UserMessage
from autogen_ext.models.openai import OpenAIChatCompletionClient


@dataclass
class Message:
    content: str


class SimpleAgent(RoutedAgent):
    def __init__(self, model_client: ChatCompletionClient) -> None:
        super().__init__("A simple agent")
        self._system_messages = [SystemMessage(content="You are a helpful AI assistant.")]
        self._model_client = model_client

    @message_handler
    async def handle_user_message(self, message: Message, ctx: MessageContext) -> Message:
        # Prepare input to the chat completion model.
        user_message = UserMessage(content=message.content, source="user")
        response = await self._model_client.create(
            self._system_messages + [user_message], cancellation_token=ctx.cancellation_token
        )
        # Return with the model's response.
        assert isinstance(response.content, str)
        return Message(content=response.content)

SimpleAgent クラスは autogen_core.RoutedAgent クラスのサブクラスで、メッセージを適切なハンドラに自動的にルーティングする利便性のためのものです。それは、ユーザからのメッセージを処理する、単一のハンドラ handle_user_message を持ちます。それは ChatCompletionClient を使用してメッセージへのレスポンスを生成します。そしてダイレクトな通信モデルに従って、レスポンスをユーザに返します。

Note : タイプ autogen_core.CancellationToken の cancellation_token は非同期操作をキャンセルするために使用されます。それはメッセージハンドラ内の async 呼び出しにリンクされ、ハンドラをキャンセルするために呼び出し側により使用できます。

# Create the runtime and register the agent.
from autogen_core import AgentId

model_client = OpenAIChatCompletionClient(
    model="gpt-4o-mini",
    # api_key="sk-...", # Optional if you have an OPENAI_API_KEY set in the environment.
)

runtime = SingleThreadedAgentRuntime()
await SimpleAgent.register(
    runtime,
    "simple_agent",
    lambda: SimpleAgent(model_client=model_client),
)
# Start the runtime processing messages.
runtime.start()
# Send a message to the agent and get the response.
message = Message("Hello, what are some fun things to do in Seattle?")
response = await runtime.send_message(message, AgentId("simple_agent", "default"))
print(response.content)
# Stop the runtime processing messages.
await runtime.stop()
await model_client.close()

Seattle is a vibrant city with a wide range of activities and attractions. Here are some fun things to do in Seattle:

1. **Space Needle**: Visit this iconic observation tower for stunning views of the city and surrounding mountains.

2. **Pike Place Market**: Explore this historic market where you can see the famous fish toss, buy local produce, and find unique crafts and eateries.

3. **Museum of Pop Culture (MoPOP)**: Dive into the world of contemporary culture, music, and science fiction at this interactive museum.

4. **Chihuly Garden and Glass**: Marvel at the beautiful glass art installations by artist Dale Chihuly, located right next to the Space Needle.

5. **Seattle Aquarium**: Discover the diverse marine life of the Pacific Northwest at this engaging aquarium.

6. **Seattle Art Museum**: Explore a vast collection of art from around the world, including contemporary and indigenous art.

7. **Kerry Park**: For one of the best views of the Seattle skyline, head to this small park on Queen Anne Hill.

8. **Ballard Locks**: Watch boats pass through the locks and observe the salmon ladder to see salmon migrating.

9. **Ferry to Bainbridge Island**: Take a scenic ferry ride across Puget Sound to enjoy charming shops, restaurants, and beautiful natural scenery.

10. **Olympic Sculpture Park**: Stroll through this outdoor park with large-scale sculptures and stunning views of the waterfront and mountains.

11. **Underground Tour**: Discover Seattle's history on this quirky tour of the city's underground passageways in Pioneer Square.

12. **Seattle Waterfront**: Enjoy the shops, restaurants, and attractions along the waterfront, including the Seattle Great Wheel and the aquarium.

13. **Discovery Park**: Explore the largest green space in Seattle, featuring trails, beaches, and views of Puget Sound.

14. **Food Tours**: Try out Seattle’s diverse culinary scene, including fresh seafood, international cuisines, and coffee culture (don’t miss the original Starbucks!).

15. **Attend a Sports Game**: Catch a Seahawks (NFL), Mariners (MLB), or Sounders (MLS) game for a lively local experience.

Whether you're interested in culture, nature, food, or history, Seattle has something for everyone to enjoy!

上記の SimpleAgent は、常に、システムメッセージと最新のユーザメッセージのみを含む最新のコンテクストを伴い応答します。autogen_core.model_context からのモデルコンテキスト・クラスを使用してエージェントに以前の会話を「記憶」(remember) させることができます。See the Model Context page for more details.

環境変数からの API キー

上記の例で、api_key 引数で API キーを提供できることを示しています。重要なことは、OpenAI と Azure OpenAI クライアントは openai パッケージを使用していることで、これは (api キーが) 提供されていない場合、環境変数から api キーを自動的に読みます。

OpenAI については、OPENAI_API_KEY 環境変数を設定できます。
Azure OpenAI については、AZURE_OPENAI_API_KEY 環境変数を設定できます。

加えて、Gemini (Beta) については、GEMINI_API_KEY 環境変数を設定できます。

これは、コードに機密性の高い api キーを含めることを回避しますので、探究すべき良い実践です。

以上

月	火	水	木	金	土	日
	1	2	3	4	5	6
7	8	9	10	11	12	13
14	15	16	17	18	19	20
21	22	23	24	25	26	27
28	29	30