OpenAIエージェントSDKの使い方は？

このOpenAI Agents SDKは、OpenAIの言語モデルによって強化されたAIエージェントの開発を簡素化するために設計されたPythonライブラリです。開発者に対して、タスク特化型エージェントの作成、外部機能の統合、エージェント間のタスク委任の管理、入出力の検証の強制、および実行フローの監視を行うためのツールを提供します。このガイドは、SDKを効果的にインストール、設定、および活用するための詳細な技術的手順を提供し、2000語以上の長さで、精度と実用的な応用に重点を置いています。

はじめに

OpenAI Agents SDKは、各エージェントが特定のタスクを実行するように調整されたマルチエージェントシステムを構築するための構造化されたフレームワークを提供します。これらのエージェントは、ユーザーと対話し、統合されたツールを通じてアクションを実行し、他のエージェントにタスクを渡すことによって協力します。SDKの主要なコンポーネントは次のとおりです：

• エージェント：特定の指示と役割に設定された言語モデルのインスタンス。
• ツール：エージェントの能力を拡張する関数やサービス（例：ウェブ検索、カスタムPythonコード）。
• ハンドオフ：エージェントが他のエージェントにタスクをシームレスに委任するためのメカニズム。
• ガードレール：入力と出力が定義された基準を満たすことを確実にするための検証層。
• トレース：デバッグとパフォーマンス分析のための実行ログ。

このガイドは、PythonとAPIインタラクションについて基本的な理解を持っている開発者を対象としており、堅牢で包括的なリソースを作成するための詳細な説明、コード例、およびベストプラクティスを提供します。

インストールと設定

適切なセットアップは、OpenAI Agents SDKを効果的に使用するために重要です。このセクションでは、前提条件、環境設定、インストール、および検証について説明します。

前提条件

続行する前に、以下を確認してください：

• Python 3.8+：python --versionでPythonのバージョンを確認してください。必要に応じてpython.orgからインストールしてください。

• OpenAI APIキー：アカウント設定のplatform.openai.comからキーを取得してください。このキーはOpenAIのサーバーへのリクエストを認証します。

ステップ1：仮想環境の設定

仮想環境はプロジェクト依存関係を隔離し、他のPythonプロジェクトとの競合を防ぎます。作成してアクティブにするには：

• Linux/macOS：

python -m venv agents_env
source agents_env/bin/activate

• Windows：

python -m venv agents_env
agents_env\Scripts\activate

アクティブにすると、ターミナルプロンプトは環境を反映するようになります（例：(agents_env)）。このステップはPython開発のベストプラクティスであり、クリーンな作業空間を確保します。

ステップ2：SDKのインストール

仮想環境がアクティブの状態で、pipを使用してSDKをインストールします：

pip install openai-agents

このコマンドは、最新のSDKバージョンとその依存関係をPyPIから取得します。インストールを確認するには、次のコマンドを実行します：

pip show openai-agents-python

これにより、バージョン番号を含むメタデータが表示され、パッケージがインストールされていることが確認されます。

ステップ3：APIキーの設定

SDKは機能するためにOpenAI APIキーを必要とします。コードに埋め込むことを避けるために環境変数として設定してください。これにより、セキュリティが向上します：

• Linux/macOS：

export OPENAI_API_KEY='your-api-key'

• Windows：

set OPENAI_API_KEY='your-api-key'

セッションを通してこの設定を保持するには、シェルの設定ファイル（例：.bashrcまたは.zshrc）にコマンドを追加してください。あるいは、プログラム的にPython内で設定できますが、これは信頼性が低くなります：

import os
os.environ["OPENAI_API_KEY"] = "your-api-key"

ステップ4：インストールの確認

エージェントが正常に動作していることを確認するために、最小限のエージェントでセットアップをテストします：

from agents import Agent, Runner

agent = Agent(name="TestAgent", instructions="Return 'Setup successful'")
result = Runner.run_sync(agent, "Run test")
print(result.final_output)  # 期待される出力："Setup successful"

これが"Setup successful"と表示される場合、インストールは正常に機能しています。一般的な問題には以下が含まれます：

• 無効なAPIキー：キーを再確認し、余分なスペースやタイプミスがないことを確認してください。
• ネットワークエラー：インターネット接続とOpenAIのサーバーステータスを確認してください。

エージェントの作成

エージェントはSDKの基本的な構成要素であり、それぞれがユニークな役割と動作で定義されています。

エージェントの初期化

Agentクラスはエージェントをインスタンス化するために使用されます。重要なパラメータは以下の通りです：

• name：文字列識別子（例："MathAgent"）。
• instructions：エージェントの目的を指定する文字列（例："Solve math problems"）。
• model：使用するOpenAIモデル（デフォルト：gpt-4）。
• temperature：出力のランダム性を制御する0から1の間の浮動小数点数（デフォルト：0.7）。

例：基本的なエージェント

こちらは算術演算のためのシンプルなエージェントです：

from agents import Agent, Runner

agent = Agent(
    name="MathAgent",
    instructions="Solve arithmetic expressions."
)
result = Runner.run_sync(agent, "Calculate 10 * 2")
print(result.final_output)  # 出力："20"

Runner.run_syncメソッドはエージェントを同期的に実行し、final_output属性を持つ結果オブジェクトを返します。

高度な設定

特定のニーズに合わせてエージェントをカスタマイズするには、パラメータを調整します：

agent = Agent(
    name="CreativeWriter",
    instructions="Write a short story based on the prompt.",
    model="gpt-4",
    temperature=0.9
)
result = Runner.run_sync(agent, "A robot in a distant galaxy")
print(result.final_output)  # 出力：クリエイティブなストーリー

• モデル：gpt-4は優れた推論を提供し、gpt-3.5-turboはより単純なタスクに対してより速く、安価です。
• 温度：低い値（例：0.2）は予測可能な出力を生成し、高い値（例：0.9）は創造性を高めます。

複数エージェントの例

異なるタスクのために個別のエージェントを作成します：

support_agent = Agent(
    name="SupportBot",
    instructions="Answer technical support questions."
)
code_agent = Agent(
    name="CodeHelper",
    instructions="Generate Python code snippets."
)

support_result = Runner.run_sync(support_agent, "How do I install Python?")
code_result = Runner.run_sync(code_agent, "Write a function to add two numbers")
print(support_result.final_output)  # 出力：インストール手順
print(code_result.final_output)     # 出力："def add(a, b): return a + b"

これは、SDKが多様な役割を処理する柔軟性を示しています。

ツールの統合

ツールはエージェントが外部アクションを実行することを可能にし、エージェントの能力を強化します。SDKはホストツール、カスタム関数ツール、エージェントベースのツールをサポートします。

ホストツールの使用

ホストツール、例えばweb_searchは、事前に構築されており、すぐに使用できます：

from agents import Agent, Runner, web_search

agent = Agent(
    name="ResearchAgent",
    instructions="Answer questions using web search.",
    tools=[web_search]
)
result = Runner.run_sync(agent, "What is the capital of France?")
print(result.final_output)  # 出力："The capital of France is Paris."

エージェントは自動的にweb_searchを呼び出してリアルタイムのデータを取得します。

カスタム関数ツールの作成

@function_toolデコレーターを使用してカスタムツールを定義します。ツールは文字列を受け取り、文字列を返さなければなりません。

例：データ取得ツール

from agents import Agent, Runner, function_tool

@function_tool
def fetch_data(id: str) -> str:
    """Return data for the given ID."""
    # シミュレーションデータベースの検索
    return f"Data for ID {id}: active"

agent = Agent(
    name="DataAgent",
    instructions="Retrieve data using the tool.",
    tools=[fetch_data]
)
result = Runner.run_sync(agent, "Fetch data for ID 123")
print(result.final_output)  # 出力："Data for ID 123: active"

外部APIの統合

ツールは外部サービスに接続できます。以下は天気ツールの例です：

import requests
from agents import function_tool, Agent, Runner

@function_tool
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    api_key = "your-weather-api-key"  # 実際のキーに置き換えてください
    url = f"http://api.weatherapi.com/v1/current.json?key={api_key}&q={city}"
    response = requests.get(url)
    if response.status_code == 200:
        data = response.json()
        return f"The weather in {city} is {data['current']['condition']['text']}."
    return "Weather data unavailable."

agent = Agent(
    name="WeatherAgent",
    instructions="Provide weather updates using the tool.",
    tools=[get_weather]
)
result = Runner.run_sync(agent, "What's the weather in Tokyo?")
print(result.final_output)  # 出力："The weather in Tokyo is Sunny."（例）

これをテストするには、weatherapi.comで無料APIキーにサインアップしてください。

複数のツールを組み合わせる

エージェントは複数のツールを同時に使用できます：

@function_tool
def log_entry(text: str) -> str:
    """Log a message."""
    return f"Logged: {text}"

agent = Agent(
    name="MultiToolAgent",
    instructions="Use tools to search and log.",
    tools=[web_search, log_entry]
)
result = Runner.run_sync(agent, "Search for AI trends and log the query")
print(result.final_output)  # 出力には検索結果とログ確認が含まれます

エージェントのハンドオフ

ハンドオフはエージェントがタスクを委任することを可能にし、複雑なワークフローを実現します。

ハンドオフの設定

プライマリエージェントを定義し、handoffsパラメータを通じてセカンダリエージェントにアクセスさせます：

from agents import Agent, Runner

english_agent = Agent(
    name="EnglishHelper",
    instructions="Respond in English only."
)
spanish_agent = Agent(
    name="SpanishHelper",
    instructions="Respond in Spanish only."
)
triage_agent = Agent(
    name="LanguageRouter",
    instructions="Detect the language and hand off to the appropriate agent.",
    handoffs=[english_agent, spanish_agent]
)

result = Runner.run_sync(triage_agent, "Hola, ¿qué tal?")
print(result.final_output)  # 出力："¡Bien, gracias!"（または類似）

triage_agentは入力を分析し、適切な言語特化エージェントに委任します。

ハンドオフロジック

ハンドオフの決定はプライマリエージェントの指示に依存します。例えば：

• "入力にスペイン語の単語が含まれている場合、SpanishHelperにハンドオフする."
• "英語の入力にはEnglishHelperを使用する."

英語の入力でテストします：

result = Runner.run_sync(triage_agent, "How are you?")
print(result.final_output)  # 出力："I'm good, thanks!"

ネストされたハンドオフ

深いワークフローのために、エージェントはハンドオフを持つ他のエージェントにハンドオフできます：

analysis_agent = Agent(
    name="AnalysisBot",
    instructions="Analyze data and hand off for reporting."
)
report_agent = Agent(
    name="ReportBot",
    instructions="Generate a report from analysis."
)
main_agent = Agent(
    name="WorkflowManager",
    instructions="Start with analysis.",
    handoffs=[analysis_agent, report_agent]
)

result = Runner.run_sync(main_agent, "Analyze sales data")
print(result.final_output)  # 出力：生成したレポート

ガードレールの実装

ガードレールはPydanticモデルを使用して入力と出力に制約を課します。

ガードレールの定義

出力構造を検証するためにモデルを作成します：

from pydantic import BaseModel
from agents import Agent, Runner

class QuestionCheck(BaseModel):
    is_question: bool
    reason: str

guard_agent = Agent(
    name="QuestionGuard",
    instructions="Determine if the input is a question.",
    output_type=QuestionCheck
)

result = Runner.run_sync(guard_agent, "What is the capital of France?")
print(result.final_output)  # 出力：{"is_question": true, "reason": "Ends with a question mark"}

ワークフロー統合

ガードレールを使用して入力をフィルタリングします：

task_agent = Agent(
    name="TaskProcessor",
    instructions="Process questions only.",
    handoffs=[guard_agent]
)
result = Runner.run_sync(task_agent, "Tell me a story")
print(result.final_output)  # 出力は質問ではないことを示します

トレースとデバッグ

トレースはエージェントの実行の詳細をログし、OpenAI ダッシュボードを通じてアクセス可能です。

トレースの有効化

トレースは自動的に行われます。各実行は次の情報を含むトレースを生成します：

• 入力/出力データ
• ツール呼び出し
• ハンドオフイベント
• エラー

デバッグの例

エージェントが失敗した場合、トレースを確認して次のことを特定します：

• 不正なツールパラメータ
• ハンドオフの誤ルーティング
• APIエラー

ベストプラクティス

パフォーマンスの最適化

• モデルの選択：速度にはgpt-3.5-turboを、複雑な推論にはgpt-4を使用してください。
• 温度：精度には0.2、創造性には0.9を使用します。
• 非同期実行：並列タスクにはRunner.run_asyncを使用します。

エラー処理

• ツール：明確なエラーメッセージを返します（例："Invalid ID"）。
• ハンドオフ：失敗のためのフォールバックエージェントを含めます。

ワークフロー設計

• モジュール性：タスクをエージェント間で分割します。
• 明確さ：明示的な指示を書くこと。
• 検証：重要なステージでガードレールを適用します。

結論

OpenAI Agents SDKは、開発者が専門のエージェント、統合ツール、協力的なワークフローを使用して高度なAIシステムを構築することを可能にします。このガイドは、その潜在能力を最大限に活用するための技術的な基盤を提供し、例やベストプラクティスを用意しています。

さて、次は何をしますか？さまざまな指示、ツール、ワークフローを試してみてください。もし何か問題が発生した場合は、APIのテストに役立つApidogのようなツールを無料で手に入れてください。