OpenAI – エージェント構築のための実践ガイド 日本語翻訳

OpenAIからエージェント構築のための実践ガイドが公開されました。非常に勉強になったので、全文を日本語に翻訳しながら読みました。翻訳の正確さは保証できませんが、メモとして書き残します。

はじめに

大規模言語モデルは、複雑なマルチステップのタスクを処理する能力がますます高まっています。推論、マルチモダリティ、ツール利用の進歩により、エージェントとして知られるLLM（大規模言語モデル）を活用したシステムの新しいカテゴリが生まれました。

このガイドは、初めてエージェントを構築しようとしている製品チームやエンジニアリングチーム向けに設計されており、多くの顧客導入事例から得られた洞察を、実践的で実行可能なベストプラクティスにまとめています。有望なユースケースを特定するためのフレームワーク、エージェントのロジックとオーケストレーションを設計するための明確なパターン、エージェントが安全かつ予測可能で効果的に動作することを保証するためのベストプラクティスが含まれています。

このガイドを読めば、自信を持って最初のエージェント構築を開始するために必要な基礎知識を習得できます。

エージェントとは？

従来のソフトウェアはユーザーがワークフローを合理化し自動化することを可能にしますが、エージェントはユーザーに代わって、高度な独立性を持って同じワークフローを実行することができます。

エージェントとは、あなたに代わってタスクを独立して達成するシステムです。

ワークフローとは、顧客サービスの問題解決、レストランの予約、コード変更のコミット、レポート生成など、ユーザーの目標を達成するために実行する必要がある一連のステップです。

LLMを統合しているが、ワークフロー実行の制御には使用しないアプリケーション（単純なチャットボット、シングルターンのLLM、感情分類器など）はエージェントではありません。

より具体的には、エージェントはユーザーに代わって信頼性高く一貫して行動するために、以下の中核的な特徴を持っています

1. ワークフロー実行の管理と意思決定のためにLLMを活用します。 ワークフローが完了したことを認識し、必要に応じてアクションを自律的に修正できます。失敗した場合は、実行を停止し、制御をユーザーに戻すことができます。
2. 外部システムと対話するための様々なツールにアクセスできます。 これには、コンテキスト収集とアクション実行の両方が含まれます。ワークフローの現在の状態に応じて適切なツールを動的に選択し、常に明確に定義されたガードレール内で動作します。

いつエージェントを構築すべきか？

エージェントの構築には、システムがどのように意思決定を行い、複雑さを処理するかを再考する必要があります。従来の自動化とは異なり、エージェントは、伝統的な決定論的およびルールベースのアプローチが不十分なワークフローに特に適しています。

支払い詐欺分析の例を考えてみましょう。従来のルールエンジンはチェックリストのように機能し、事前に設定された基準に基づいてトランザクションにフラグを立てます。対照的に、LLMエージェントは、経験豊富な調査員のように機能し、コンテキストを評価し、微妙なパターンを考慮し、明確なルールが破られていなくても疑わしい活動を特定します。この微妙な推論能力こそが、エージェントが複雑で曖昧な状況を効果的に管理できる理由です。

エージェントが価値を付加できる場所を評価する際には、これまで自動化に抵抗してきたワークフロー、特に従来の方法が困難に遭遇する場所に優先順位を付けます。

1. 複雑な意思決定:
   顧客サービスワークフローにおける返金承認など、微妙な判断、例外、またはコンテキストに応じた意思決定を伴うワークフロー。
2. 維持が困難なルール:
   広範で複雑なルールセットのために扱いにくくなり、更新が高コストになったり、エラーが発生しやすくなったりしているシステム。例: ベンダーのセキュリティレビューの実行。
3. 非構造化データへの依存度が高い:
   自然言語の解釈、文書からの意味の抽出、またはユーザーとの対話的なやり取りを伴うシナリオ。例: 住宅保険請求の処理。

エージェントの構築に着手する前に、ユースケースがこれらの基準を明確に満たせることを確認してください。そうでなければ、決定論的なソリューションで十分かもしれません。

エージェント設計の基礎

最も基本的な形式では、エージェントは3つのコアコンポーネントで構成されます。

以下は、OpenAIのAgents SDKを使用した場合のコード例です。好みのライブラリを使用したり、スクラッチから直接構築したりして、同じ概念を実装することもできます。

weather_agent = Agent(
    name="Weather agent",
    instructions="You are a helpful agent who can talk to users about the weather.",
    tools=[get_weather],
)

モデルの選択

異なるモデルには、タスクの複雑さ、レイテンシ、コストに関連する異なる強みとトレードオフがあります。次の「オーケストレーション」のセクションで見るように、ワークフロー内の異なるタスクに様々なモデルを使用することを検討するとよいでしょう。

すべてのタスクに最も賢いモデルが必要なわけではありません。単純な検索や意図分類タスクは、より小さく高速なモデルで処理できる場合がありますが、返金を承認するかどうかを決定するような難しいタスクは、より高性能なモデルの恩恵を受ける可能性があります。

効果的なアプローチは、パフォーマンスのベースラインを確立するために、すべてのタスクに対して最も高性能なモデルを使用してエージェントのプロトタイプを構築することです。そこから、より小さなモデルに置き換えてみて、許容可能な結果がまだ得られるかどうかを確認します。これにより、エージェントの能力を早期に制限することなく、より小さなモデルが成功または失敗する箇所を診断できます。

要約すると、モデルを選択するための原則は単純です:

1. 評価を設定してパフォーマンスのベースラインを確立する
2. 利用可能な最高のモデルで精度目標を達成することに焦点を当てる
3. 可能な場合は大きなモデルを小さなモデルに置き換えることで、コストとレイテンシを最適化する

OpenAIモデルの選択に関する包括的なガイドはこちらで見つけることができます。

ツールの定義

ツールは、基盤となるアプリケーションやシステムからのAPIを使用して、エージェントの能力を拡張します。APIを持たないレガシーシステムの場合、エージェントは、人間が行うのと同じように、WebおよびアプリケーションUIを通じてそれらのアプリケーションやシステムと直接対話するために、コンピューター使用モデルに依存することができます。

各ツールは標準化された定義を持つべきであり、ツールとエージェント間の柔軟な多対多の関係を可能にします。十分に文書化され、徹底的にテストされ、再利用可能なツールは、発見可能性を向上させ、バージョン管理を簡素化し、冗長な定義を防ぎます。

大まかに言って、エージェントには3種類のツールが必要です:

たとえば、Agents SDKを使用する場合、上記で定義したエージェントに一連のツールを装備する方法は次のとおりです。

from agents import Agent, WebSearchTool, function_tool

@function_tool
def save_results(output):
    db.insert({"output": output, "timestamp": datetime.time()})
    return "File saved"

search_agent = Agent(
    name="Search agent",
    instructions="Help the user search the internet and save results if
    asked.",
    tools=[WebSearchTool(), save_results],
)

必要なツールの数が増えるにつれて、タスクを複数のエージェントに分割することを検討してください（オーケストレーションを参照）。

指示の設定

高品質な指示は、LLMを活用したアプリにとって不可欠ですが、特にエージェントにとっては重要です。明確な指示は曖昧さを減らし、エージェントの意思決定を改善し、よりスムーズなワークフロー実行とエラーの削減につながります。

エージェント指示のベストプラクティス

o1や03-miniのような高度なモデルを使用して、既存のドキュメントから指示を自動生成できます。このアプローチを示すサンプルプロンプトを以下に示します。

あなたはLLMエージェントの指示を書く専門家です。以下のヘルプセンタードキュメントを、番号付きリストで書かれた明確な指示セットに変換してください。このドキュメントはLLMが従うポリシーになります。曖昧さがなく、指示がエージェントへの指示として書かれていることを確認してください。変換するヘルプセンタードキュメントは次のとおりです {{help_center_doc}}

オーケストレーション

基本的なコンポーネントが整ったら、エージェントがワークフローを効果的に実行できるようにするためのオーケストレーションパターンを検討できます。完全に自律的なエージェントを複雑なアーキテクチャですぐに構築したくなるかもしれませんが、顧客は通常、段階的なアプローチでより大きな成功を収めています。

一般に、オーケストレーションパターンは2つのカテゴリに分類されます。

1. シングルエージェントシステム: 単一のモデルが適切なツールと指示を備え、ループ内でワークフローを実行します。
2. マルチエージェントシステム: ワークフローの実行が複数の協調するエージェントに分散されます。

各パターンを詳しく見ていきましょう。

シングルエージェントシステム

単一のエージェントは、ツールを段階的に追加することで多くのタスクを処理でき、複雑さを管理しやすくし、評価とメンテナンスを簡素化します。新しいツールごとに、複数のエージェントを早期に調整する必要なく、その能力が拡張されます。

すべてのオーケストレーションアプローチには、「実行（run）」の概念が必要です。これは通常、エージェントが終了条件に達するまで動作させるループとして実装されます。一般的な終了条件には、ツール呼び出し、特定の構造化された出力、エラー、または最大ターン数への到達が含まれます。

たとえば、Agents SDKでは、エージェントはRunner.run()メソッドを使用して開始されます。これは、以下のいずれかが発生するまでLLM上でループします。

1. 特定の出力タイプによって定義された最終出力ツールが呼び出される。
2. モデルがツール呼び出しなしで応答を返す（例: 直接のユーザーメッセージ）。

使用例:

Agents.run(agent, [UserMessage("What's the capital of the USA?")])

このwhileループの概念は、エージェントの機能の中心です。次に説明するマルチエージェントシステムでは、エージェント間で一連のツール呼び出しとハンドオフを行うことができますが、終了条件が満たされるまでモデルに複数のステップを実行させることができます。

マルチエージェントフレームワークに切り替えずに複雑さを管理するための効果的な戦略は、プロンプトテンプレートを使用することです。異なるユースケースごとに多数の個別のプロンプトを維持するのではなく、ポリシー変数を受け入れる単一の柔軟な基本プロンプトを使用します。このテンプレートアプローチは、さまざまなコンテキストに簡単に適応し、メンテナンスと評価を大幅に簡素化します。新しいユースケースが発生した場合、ワークフロー全体を書き直すのではなく、変数を更新できます。

あなたはコールセンターのエージェントです。あなたは{{user_first_name}}さんと対話しています。{{user_first_name}}さんは{{user_tenure}}の間メンバーです。ユーザーの最も一般的な苦情は{{user_complaint_categories}}についてです。ユーザーに挨拶し、長年の顧客であることに感謝し、ユーザーが持つかもしれない質問に答えてください！

いつ複数のエージェントを作成することを検討すべきか

私たちの一般的な推奨事項は、まず単一のエージェントの能力を最大化することです。エージェントを増やすと、概念の直感的な分離が可能になりますが、追加の複雑さとオーバーヘッドが発生する可能性があるため、多くの場合、ツールを備えた単一のエージェントで十分です。

多くの複雑なワークフローでは、プロンプトとツールを複数のエージェントに分割することで、パフォーマンスとスケーラビリティが向上します。エージェントが複雑な指示に従えなかったり、一貫して誤ったツールを選択したりする場合、システムをさらに分割し、より明確なエージェントを導入する必要があるかもしれません。

エージェントを分割するための実践的なガイドラインには、以下が含まれます:

マルチエージェントシステム

マルチエージェントシステムは、特定のワークフローや要件に合わせてさまざまな方法で設計できますが、顧客との経験から、広く適用可能な2つのカテゴリが浮き彫りになります。

マルチエージェントシステムは、エージェントをノードとして表現するグラフとしてモデル化できます。マネージャーパターンでは、エッジはツール呼び出しを表しますが、分散パターンでは、エッジはエージェント間で実行を転送するハンドオフを表します。

オーケストレーションパターンに関係なく、同じ原則が適用されます: コンポーネントを柔軟かつ構成可能に保ち、明確でよく構造化されたプロンプトによって駆動します。

マネージャーパターン

マネージャーパターンは、司令塔となるLLMである「マネージャー」が、ツール呼び出しを通じて特化されたエージェントのネットワークをシームレスに調整することを可能にします。コンテキストや制御を失う代わりに、マネージャーは適切なタイミングで適切なエージェントにタスクを賢く委任し、結果を統合して一貫したインタラクションを実現します。これにより、ユーザーは常に必要なときに専門的な機能を利用できる、滑らかで統合された体験を得られます。

ワークフローの実行を単独のエージェントが掌握し、ユーザーと直接やり取りも担当させたい場合に最適なパターンです。

たとえば、Agents SDKでこのパターンを実装する方法は次のとおりです。

from agents import Agent, Runner

manager_agent = Agent(
    name="manager_agent",
    instructions=(
        "You are a translation agent. You use the tools given to you to translate."
        "If asked for multiple translations, you call the relevant tools."
    ),
    tools=[
        spanish_agent.as_tool(
            tool_name="translate_to_spanish",
            tool_description="Translate the user's message to Spanish",
        ),
        french_agent.as_tool(
            tool_name="translate_to_french",
            tool_description="Translate the user's message to French",
        ),
        italian_agent.as_tool(
            tool_name="translate_to_italian",
            tool_description="Translate the user's message to Italian",
        ),
    ],
)

async def main():
    msg = input("Translate 'hello' to Spanish, French and Italian for me!")

    orchestrator_output = await Runner.run(manager_agent, msg)

    for message in orchestrator_output.new_messages:
        print(f"  Translation step: {message.content}")

宣言型 vs 非宣言型グラフ

一部のフレームワークは宣言型であり、開発者はノード（エージェント）とエッジ（決定的または動的なハンドオフ）からなるグラフを通じて、ワークフロー内のすべての分岐、ループ、条件を事前に明示的に定義する必要があります。視覚的な明確さには有益ですが、ワークフローがより動的で複雑になるにつれて、このアプローチはすぐに煩雑で困難になり、しばしば特殊なドメイン固有言語の学習が必要になります。

対照的に、Agents SDKはより柔軟なコードファーストのアプローチを採用しています。開発者は、グラフ全体を事前に定義する必要なく、使い慣れたプログラミング構成要素を使用してワークフローロジックを直接表現でき、より動的で適応性のあるエージェントオーケストレーションを可能にします。

分散型パターン

分散型パターンでは、エージェントはワークフローの実行を相互に「ハンドオフ」できます。ハンドオフは、あるエージェントが別のエージェントに委任することを可能にする一方向の転送です。Agents SDKでは、ハンドオフはツールまたは関数の一種です。エージェントがハンドオフ関数を呼び出すと、最新の会話状態も転送しながら、ハンドオフされた新しいエージェントで即座に実行が開始されます。

このパターンでは、多くのエージェントを対等な立場で使用し、あるエージェントがワークフローの制御を別のエージェントに直接引き渡すことができます。これは、単一のエージェントが中央制御や統合を維持する必要がない場合に最適であり、代わりに各エージェントが必要に応じて実行を引き継ぎ、ユーザーと対話できるようにします。

たとえば、セールスとサポートの両方を処理する顧客サービスワークフローに対して、Agents SDKを使用して分散パターンを実装する方法は次のとおりです。

from agents import Agent, Runner

technical_support_agent = Agent(
    name="Technical Support Agent",
    instructions=(
        "You provide expert assistance with resolving technical issues, "
        "system outages, or product troubleshooting."
    ),
    tools=[search_knowledge_base]
)

sales_assistant_agent = Agent(
    name="Sales Assistant Agent",
    instructions=(
        "You help enterprise clients browse the product catalog, recommend "
        "suitable solutions, and facilitate purchase transactions."
    ),
    tools=[initiate_purchase_order]
)

order_management_agent = Agent(
    name="Order Management Agent",
    instructions=(
        "You assist clients with inquiries regarding order tracking, "
        "delivery schedules, and processing returns or refunds."
    ),
    tools=[track_order_status, initiate_refund_process]
)

triage_agent = Agent(
    name="Triage Agent",
    instructions="You act as the first point of contact, assessing customer "
    "queries and directing them promptly to the correct specialized agent.",
    handoffs=[technical_support_agent, sales_assistant_agent,
              order_management_agent],
)

await Runner.run(
    triage_agent,
    input("Could you please provide an update on the delivery timeline for "
          "our recent purchase?")
)

上記の例では、最初のユーザーメッセージはtriage_agentに送信されます。入力が最近の購入に関するものであることを認識すると、triage_agentはorder_management_agentへのハンドオフを呼び出し、制御をそれに転送します。

このパターンは、会話のトリアージのようなシナリオや、元のエージェントが関与し続ける必要なく、特定のタスクを特化されたエージェントに完全に引き継がせたい場合に特に効果的です。オプションで、2番目のエージェントに元のエージェントへのハンドオフバックを装備し、必要に応じて再び制御を転送できるようにすることもできます。

ガードレール

適切に設計されたガードレールは、データプライバシーリスク（例: システムプロンプトの漏洩防止）や評判リスク（例: ブランドに沿ったモデルの振る舞いの強制）を管理するのに役立ちます。ユースケースですでに特定したリスクに対処するガードレールを設定し、新しい脆弱性を発見するにつれて追加のガードレールを重ねることができます。

ガードレールはLLMベースのデプロイメントにおける重要なコンポーネントですが、堅牢な認証および認可プロトコル、厳格なアクセス制御、および標準的なソフトウェアセキュリティ対策と組み合わせる必要があります。

ガードレールを階層的な防御メカニズムと考えてください。単一のガードレールだけでは十分な保護を提供する可能性は低いですが、複数の特化されたガードレールを一緒に使用することで、より回復力のあるエージェントが作成されます。下の図では、LLMベースのガードレール、正規表現などのルールベースのガードレール、およびOpenAIモデレーションAPIを組み合わせて、ユーザー入力を精査しています。

ガードレールの種類

ガードレールの構築

ユースケースですでに特定したリスクに対処するガードレールを設定し、新しい脆弱性を発見するにつれて追加のガードレールを重ねます。以下のヒューリスティックが効果的であることがわかっています。

まずは自分たちのユースケースで既に把握しているリスクに対応するガードレールを構築し、その後、新たな脆弱性を発見するたびに追加のガードレールを積み重ねていきましょう。以下のヒューリスティック（経験則）が効果的です。

1. データプライバシーとコンテンツの安全性に焦点を当てる
2. 遭遇した実際の現場でのエッジケースや失敗に基づいて新しいガードレールを追加する
3. セキュリティとユーザーエクスペリエンスの両方を最適化し、エージェントの進化に合わせてガードレールを調整する

たとえば、Agents SDKを使用してガードレールを設定する方法は次のとおりです。

from agents import (
    Agent,
    GuardrailFunctionOutput,
    InputGuardrailTripwireTriggered,
    RunContextWrapper,
    Runner,
    TResponseInputItem,
    input_guardrail,
    Guardrail,
    GuardrailTripwireTriggered
)
from pydantic import BaseModel

class ChurnDetectionOutput(BaseModel):
    is_churn_risk: bool
    reasoning: str

churn_detection_agent = Agent(
    name="Churn Detection Agent",
    instructions="Identify if the user message indicates a potential "
                 "customer churn risk.",
    output_type=ChurnDetectionOutput,
)

@input_guardrail
async def churn_detection_tripwire(
    ctx: RunContextWrapper[None], agent: Agent, input: str |
    list[TResponseInputItem]
) -> GuardrailFunctionOutput:
    result = await Runner.run(churn_detection_agent, input,
                              context=ctx.context)

    return GuardrailFunctionOutput(
        output_info=result.final_output,
        tripwire_triggered=result.final_output.is_churn_risk,
    )

customer_support_agent = Agent(
    name="Customer support agent",
    instructions="You are a customer support agent. You help customers with "
                 "their questions.",
    input_guardrails=[
        Guardrail(guardrail_function=churn_detection_tripwire),
    ],
)

async def main():
    
    await Runner.run(customer_support_agent, "Hello!")
    print("Hello message passed")
    
    try:
        await Runner.run(agent, "I think I might cancel my subscription")
        print("Guardrail didn't trip this is unexpected")
    except GuardrailTripwireTriggered:
        print("Churn detection guardrail tripped")

Agents SDK では ガードレールを最優先の概念として扱い、デフォルトで「楽観的実行」モデルを採用しています。つまり、メインのエージェントが先に出力を積極的に生成しつつ、その裏でガードレールが同時に走り、制約に違反した場合はただちに例外を投げて処理を中断します。

ガードレールは、ジェイルブレイク防止・関連性確認・キーワードフィルタリング・ブラックリスト適用・安全性分類などのポリシーを強制する関数または別のエージェントとして実装できます。たとえば前述の例では、エージェントは数学の質問を楽観的に処理しますが、math_homework_tripwire ガードレールが違反を検知した時点で例外を発生させます。

人間の介入を計画する

人間の介入は、ユーザーエクスペリエンスを損なうことなくエージェントの実際のパフォーマンスを向上させることを可能にする重要なセーフガードです。これは、特にデプロイメントの初期段階で重要であり、失敗を特定し、エッジケースを発見し、堅牢な評価サイクルを確立するのに役立ちます。

人間の介入メカニズムを実装することで、エージェントはタスクを完了できない場合に gracefully に制御を転送できます。顧客サービスでは、これは問題を人間のエージェントにエスカレーションすることを意味します。コーディングエージェントの場合、これは制御をユーザーに戻すことを意味します。

通常、人間の介入を保証する2つの主要なトリガーがあります。

1. 失敗しきい値の超過: エージェントの再試行またはアクションに制限を設定します。エージェントがこれらの制限を超えた場合（例: 複数回の試行後に顧客の意図を理解できなかった場合）、人間の介入にエスカレーションします。
2. 高リスクアクション: 機密性が高い、元に戻せない、または利害関係が大きいアクションは、エージェントの信頼性に対する自信が高まるまで、人間の監視をトリガーする必要があります。例には、ユーザーの注文のキャンセル、大規模な返金の承認、または支払いの実行が含まれます。

まとめ

エージェントは、システムが曖昧さを推論し、ツールを横断してアクションを実行し、高度な自律性を持ってマルチステップのタスクを処理できる、ワークフロー自動化の新時代を示します。より単純なLLMアプリケーションとは異なり、エージェントはワークフローをエンドツーエンドで実行するため、複雑な意思決定、非構造化データ、または脆弱なルールベースのシステムを伴うユースケースに適しています。

信頼性の高いエージェントを構築するには、強力な基盤から始めます: 高性能なモデルを明確に定義されたツールと、明確で構造化された指示と組み合わせます。複雑さのレベルに合ったオーケストレーションパターンを使用し、単一のエージェントから始めて、必要な場合にのみマルチエージェントシステムに進化させます。ガードレールは、入力フィルタリングやツール使用から人間参加型の介入まで、あらゆる段階で重要であり、エージェントが本番環境で安全かつ予測可能に動作することを保証するのに役立ちます。

成功への道は、オールオアナッシングではありません。小さく始め、実際のユーザーで検証し、時間をかけて能力を成長させます。適切な基盤と反復的なアプローチにより、エージェントは真のビジネス価値を提供できます。タスクだけでなく、インテリジェンスと適応性をもってワークフロー全体を自動化しましょう。