エージェント エンジン SDK OpenAI エージェント

エージェントを構築する

動作中のプロジェクトから開始するには、agentengine create を実行し、Hello World または User-in-the-ループエージェントの OpenAI Agents SDK バリアントを選択します（--template hello-world-agent-openai または --template insurance-agent-openai）。

from agents import Agent, ModelSettingsfrom agent_engine_sdk_openai_agents import App
app = App(app_name="support")

@app.tool()def lookup_order(order_id: str) -> str:    """Look up an order."""    ...

@app.entrypointdef build() -> Agent:    return Agent(        name="support",        instructions="Help with orders.",        model=app.llm("gpt-4.1", settings=ModelSettings(temperature=0)),        tools=app.tools(),    )

app.llm(...) によって返されたモデルと app.tools() によって返されたツールを使用します。それ以外の場合は、モデルまたはツールが動作する前に読み込みを失敗します。構成された agents.Model を app.llm に渡し、カスタム OpenAIクライアントを使用します。ツール パラメータは、名前で渡すことができるJSON値である必要があります（位置専用パラメータや *args パラメータ、および tool_call_id パラメータは使用できません）。これは、リモート ツールが名前付きJSON値として引数を受け取るためです。 @app.tool(timeout=...) でツールのタイムアウトを設定します。発行されたツール上のネイティブ timeout_seconds はオンに失敗します。ネストされたモデル、データクラス、列挙、日時など、string 以外のツールの結果はJSONテキストとしてモデルに到達します。テキストは標準であるため、再生されたタームはモデルに同じテキストを送信します。キーはソートされ、164.0 などの整数浮動小数点数は 164 と記述されます。ツールの結果の 2**53 を超える整数は呼び出しに失敗し、その引数では耐久性のあるレコードが正確に保持できないため、失敗します。そのような値を string として渡します。

Each invocation runs one native Runner turn and commits it to the Orchestration Engine before returning the result. A tool that raises is reported to the model as the OpenAI Agents SDK does by default, with the text of the installed SDK's default_tool_error_function, and the turn continues. Releases before 0.23 include the tool's error message in that text; later releases send a fixed message without it. The Orchestration Engine records the failure, so a replayed turn sends the model the same text. A call the platform stops or fails instead fails the turn with the error its tool path reports: a policy denial, a cancelled or user-stopped call, or a platform failure such as the Orchestration Engine not acknowledging a tool's result. A platform failure is never reported to the model as a failed tool, because the tool may already have run. Nothing is committed in these cases. One exception remains: when the Orchestration Engine cannot reach a remote tool's Tool Pod, it records the failure as the tool's own, so the model is told the tool failed. When the model calls several tools at once, they run concurrently. Each call keeps the Orchestration Engine activity of its call id, and their results reach the model in the order the model made the calls, whichever finishes first. If one of them waits for approval, the calls that ran before the wait keep their outputs ahead of the approved call's, as the SDK records them. When one call fails the turn, it fails once the calls still running beside it have finished. Agent hooks, hosted prompts, dynamic instructions, and a custom tool_use_behavior are not supported yet. An agent's own input and output guardrails run as described under Input and output guardrails. A project's guardrail policies apply to every model and tool call; see Guardrail policies.

MCP ツール

すべてのエージェント エンジンフレームワークで使用されるキーが同じリモート MCPサーバーを、agent.yaml の mcp.servers 下に一覧表示します。そのツールはエージェントの起動時に検出され、app.tools() は登録された関数の横にあるツールを返し、<server>__<tool> という名前を付けます。

mcp:  servers:    atlas:      url: https://mcp.example.com/mcp      allowed_tools: [find]      auth:        type: bearer_env        token_env: ATLAS_MCP_TOKEN

auth トークンを保持する環境変数の名前を付けます。トークン自体はワークスペースのシークレットに属するか、ローカル開発の場合は .env に属します。

これらのツールの 1 つに対する呼び出しは、他のツールと同様に Organization Engine ツールのアクティビティであり、サーバーの認証情報とネットワーク アクセスを保持するツール ポッドで実行されます。 allowed_tools は、エージェントが取得するサーバーのツールを制限します。失敗した呼び出しまたは MCP エラーの結果は、失敗したツールと同様にモデルに報告されます。永続的なレコードが正確に保持できない、2**53 以上の整数を保持する構造化された結果は変換に失敗します。サーバーがそのような値を string として返すようにします。

エージェントの起動時にアクセスできないサーバーは、起動を停止します。 timeout_seconds は、 呼び出しを制限するのと同様に、その検出の各リクエストを制限します。

Only the agent runtime lists the server's tools, when it starts; the Tool Pod finds the server for a call from agent.yaml when the call arrives. The Tool Pod also runs the entrypoint, to register the agent's models, and there app.tools() returns the registered functions only. Pass MCP tools to an agent without looking them up by name, for example [tool for tool in app.tools() if tool.name.startswith("atlas__")], so the entrypoint builds in both.

The SDK's own Agent.mcp_servers is refused: the SDK would call the server from the agent's process, outside the Tool Pod. needs_approval on an MCP tool is not supported yet.

引き継ぎ

Use the SDK's own handoffs=[...], with other agents or agents.handoff(...). The runtime reads the whole agent graph the entrypoint returns before each turn and holds every reachable agent to the same rules as the first: its model comes from app.llm(...) (give each agent's model its own llm_id) and its tools from app.tools(), from which each agent can select its own by name. Agent names must be unique.

ハンドオフによって、どのエージェントがアクティブになるかが決まります。オンは 1 回の実行に残ります。コミットされた状態 ではアクティブなエージェントが記録されるため、再起動後の次のローリングも、最後のエージェントを終了したエージェントから開始されます。引き継ぎエージェントによってリクエストされた承認は、そのエージェントで一時停止され、再開されます。

agents.handoff(...) は、ツール名と説明を上書きする場合があります。エージェントはサイクル内で相互に引き渡す場合があります。 input_filter、nest_handoff_history、on_handoffコールバック、input_type、呼び出し可能な is_enabled、手動で構築された Handoff は、モデルやツールが動作する前にオンに失敗します。したがって、ツール名が別のハンドオフの またはそのエージェントのツールの 1 つと一致するエージェントに対してハンドオフは行われます。それ以外の場合、SDK は 1 つを保持し、もう 1 つを削除します。

ツールとしてのエージェント

SDK の独自の Agent.as_tool(...) を使用し、その結果を別のエージェントの tools に配置します。ネストされたエージェントは、グラフ内の他のすべてのエージェントと同じルールに従います。各呼び出しは、ネストされたエージェントを独自の操作として実行します。そのモデル呼び出しとツール呼び出しは、ツールの名前が付けられたパスの下にある Organization Engine のアクティビティであり、同じエージェントツールへの繰り返しの呼び出しまたは同時呼び出しは、モデルが作成した順序で異なるままです。

呼び出しエージェントのモデルには、ツールの応答のみが表示され、呼び出しの交信のみがコミットされます。置換の試行は、記録されたアクティビティからネストされた実行を再生します。呼び出し元のストリームには、呼び出しエージェントの応答とは別に、ツール名と呼び出し ID でタグ付けされた、subagent_start イベントから subagent_end イベントの間のネストされたエージェントのテキストが含まれます。ネストされた実行が失敗すると、タームは失敗します。

ネストされたエージェントが使用するツールには承認が必要になる場合があります。また、エージェントツール自体も承認を必要とする場合があります。または他の承認を使用する際には として一時停止し、待機時間はネストされたエージェントの パスの下に記録されます。 1 つのオンでは、呼び出しエージェントからの とネストされたエージェントからの がまとめて応答されるのを待機します。ツール呼び出し ID は、ターム内で一意である必要があります。承認のために停止するネストされたエージェントは subagent_end を送信しません。再開されたストリームは、テキストの残りの部分の前に subagent_start を使用して再度開き、 が待機する前に呼び出し元が認識したテキストを再度送信しません。

max_turns、custom_output_extractor、構造化入力はサポートされています。置換の試行では、エクストラクターと構造化入力の input_builder が再度呼び出されます。そのため、両方は同じ入力に対して同じ値を返す必要があり、副作用はありません。再生されたモデル呼び出しが記録されたモデル呼び出しと異なる場合、OU はオンを失敗します。

on_streamコールバック、hooks、run_config、session、プロバイダー継続 ID、呼び出し可能な needs_approval または is_enabled、ツール 文字列、ネストされたエージェントまたはエージェント上の入力または出力の文字列から に、ネイティブ timeout_seconds、および独自のエージェントツールを使用して自分自身にアクセスできるエージェントは、モデルやツールが動作する前にオンに失敗します。

承認

ツールを @app.tool(needs_approval=True) と登録して、各呼び出しを承認するようにします。引数は、SDK の独自の function_tool(needs_approval=...) が FunctionTool に渡されるため、app.tools() は返します。返されたツールで needs_approval を設定することも機能します。モデルが承認を必要とするツールを呼び出すと、起動は一時停止されます。呼び出しは、モデルが呼び出しを行った順序で、それぞれにツールとその引数を付けて、承認を待機している呼び出しごとに 1 つの割り込みを伴う status: suspended を返します。承認を最初に実行する必要のない同じ応答内の呼び出し。同じセッションで通常の呼び出しエンドポイントから再開します。resume_map は一度にすべての割り込み ID に応答します。

{"resume_map": {"<interrupt id>": {"confirmed": true}}}

interrupts 保留中のすべての承認を一覧表示します。 suspend_payload は、単一のペイロードを読み取る呼び出し元の場合、最初の の値のみを渡します。

{"confirmed": false, "rejection_message": "..."} 呼び出しを拒否したモデルには、SDK 独自の reject(..., rejection_message=...) と同様に、ツールの結果ではなく拒否メッセージが表示されます。 rejection_message がない場合、モデルには SDK のデフォルトの拒否テキストが表示されます。空の は拒否されます。承認にはメッセージは含まれません。 Ops Manager は待機とその応答を記録します。再開は、記録されたモデル呼び出しからタームを再生し、SDK 独自の RunState を通じて応答を適用し、残りの部分のみを実行するため、ツールは承認前に実行されることはなく、プレフィックス出力は繰り返されず、待機中の再起動によって何も失われることはありません。応答されていない割り込みを残す再開は拒否されます。 needs_approval は True または False である必要があり、呼び出し可能ではありません。

入力文字列と出力の文字列監視

input_guardrails と output_guardrails を使用して、SDK ドキュメントとしてエージェント上のデータベースを宣言します。

from agents import Agent, GuardrailFunctionOutput, Runner, input_guardrail

@app.entrypointdef build() -> Agent:    judge = Agent(        name="topic judge",        instructions="Answer yes if the message is about an order, else no.",        model=app.llm("gpt-4.1-mini", llm_id="judge"),    )
    @input_guardrail    async def on_topic(context, agent, input) -> GuardrailFunctionOutput:        verdict = await Runner.run(judge, input, context=context.context)        return GuardrailFunctionOutput(            output_info=None,            tripwire_triggered=verdict.final_output.strip().lower() != "yes",        )
    return Agent(        name="support",        model=app.llm("gpt-4.1"),        tools=app.tools(),        input_guardrails=[on_topic],    )

ポリシー拒否としてオンをトリップする警告フィールドです。実行は error_code policy_denied とそのクラスのプラットフォーム独自のメッセージで終了します。拒否の理由は文字列に名前を付け、その output_info を除外します。これは保存された実行ではなく、ランタイムのログとライブストリームの エラーイベントのメタデータ内にあります。タームは何もコミットしないため、通信はその前のタームから継続されます。起動がすでに実行されたツールは元に戻されません。

拒否は文字列に名前を付けるため、すべての文字列には名前が必要です。 @input_guardrail または @output_guardrail で宣言された 、または 関数 から構築された は、関数の を受け取ります。 functools.partial から構築された または 呼び出し可能なオブジェクトには ないため、name= を渡します。名前のない文字列は、モデルを呼び出す前に拒否されます。

SDK の Runner との違いは 3 つあります。

• 入力文字列は、最初のモデル呼び出しの前に終了します。 SDK のデフォルト は、モデル呼び出しの横にそれらを開始します。これは、ガーフィールドがトリップするかどうかにかかわらず、作成され、支払いが行われます。ここで、run_in_parallel=True run_in_parallelは効果がありません。

• エージェントの文字列は、エージェントがリストした順序で一度に 1 つずつ実行され、トリップ後の文字列は実行されません。 SDK はこれらをまとめて起動します。

• 出力保護 を持つエージェントは、テキストをストリーミングしません。 SDK は、出力が監視する前に応答をストリーミングし、実行の最終値のみを保留します。ここで、呼び出し元は、ガベージが経過すると、オンの結果全体を受け取ります。出力保護のないエージェントは、以前のようにストリームします。

SDK と同様に、入力文字列はエージェントに属し、新しいメッセージでこれまでのやり取りをチェックします。出力データベースは、タームの最終応答を提供するエージェントに属します。ハンドオフ後に、 に渡されたエージェントは次の返しを開始するため、入力保護はそれらをチェックします。

置き換え試行では、最初からタームを再度実行し、ガーフィールドを含め、承認を待機するタームは再開時にそれらを再度実行します。したがって、文字列は同じ入力に対して同じ検証を返し、プロセス外では何も変更しない必要があります。モデルにクエリを実行するエージェントは、 が 以上であるため、エントリポイントがアプリのビルド中に呼び出されるエージェントを通じて実行されます。判断のモデル呼び出しは、プロジェクトの ポリシーの下でのオーケストレーション エンジンのアクティビティであり、リプレイは、再度要求するのではなく、記録された応答を返します。実行には次の役割を伴う が必要です。プレーンなモデル名を持つ の判断は、実行時にプロバイダーの認証情報がないため、失敗します。判断エージェントのツール、承認、ハンドオフは適格ではありません。レビューのためにボタンの応答を保持するプロジェクトポリシーはオンに失敗します。アプリのグラフのエージェントのみがレプリカを待機できます。外部サービスを直接呼び出す文字列はサポートされていません。プラットフォームのネットワーク ポリシーの外部で、リプレイごとに再度呼び出しが行われます。app.llm(...)judgecontext=context.context

ツール 文字列とツールとして使用されるエージェントの文字数フィールドでは、まだサポートされていません。

ガーフィールド ポリシー

プロジェクトの保護ポリシーは、ツールとして使用されるエージェントのものを含む、すべてのモデルとツール呼び出しにオーケストレーション エンジンによって適用され、アプリケーションコードは必要ありません。ログ、編集、またはブロックするポリシーは、呼び出しが返す変更のみをログに記録、編集、またはブロックするポリシーです。

モデル応答のレビューを必要とするポリシーは、承認と同様にタームを一時停止します。応答は保留され、呼び出しでは status: suspended が返され、その値が guardrail_review の下でレビューを名付ける割り込みを伴う を返します。同じ方向のツール承認の後に待機し、1 つの resume_map がそれらにまとめて解決します。

{"resume_map": {"<interrupt id>": {"decision": "approve", "reviewer_notes": "checked"}}}

承認により、ツール呼び出しに含まれる保持された応答が、別のプロバイダー呼び出しなしで解放されます。を拒否するとタームは失敗し、何もリリースされません。応答を保持し、決定を記録します。アダプターは、承認される前に保持されたテキストを表示することはありません。

実行を停止するために、 アダプターはすべてのエージェントに agent_engine_guardrail_review という名前のツールを提供します。これにはモデルは提供されていません。停止は対話コンテンツではないため、後のモデル呼び出しもコミットされた履歴にも含まれません。の実行に対するランサーの独自の結果には引き続きそれがリストされるため、ツールとして使用されるエージェントの custom_output_extractor は、そのエージェントの応答が確認されたときに、その実行のアイテム間で 呼び出しとその空の出力が表示されます。レビュー には名前を付けませんが、保持された応答には 名前を付けません 。各レビューには、実行の max_turns の 1 つが必要です。その名前のツールやハンドオフ、またはそれを呼び出すモデル応答はオンに失敗します。

メモリ

agent.yaml で memory: true を使用すると、 ツールは app.memory を通じてプロジェクトの長期メモリの読み取りと書き込みを行い、LgGraph アプリと ADK アプリは同じフェイルを使用します。

@app.tool()def remember_preference(preference: str) -> str:    """Remember how the customer likes to be contacted."""    result = app.memory.save_semantic(text=preference, label="contact_preference")    return "saved" if result.acknowledged else "not saved"

リクエストの実行中に行われた呼び出しでは、そのリクエストのユーザーが使用されます。書込みは永続的なアクティビティではなく、ライブです。クラッシュした後にツール呼び出しが再生されると、その書込みが再度実行されるため、繰り返し安全な書込みを優先します。

耐久状態

コミットされた各 タームは、ランサーの完全な入力リストを、それが属するアプリとセッション、およびタームを終了したエージェントの名前とともに、 __agent_engine_openai_agents__ 状態プロパティの下に保存します。次のビューは、そのエージェントを使用してそのリストから続行されます。コミットされたメッセージは、履歴リーダーの明示的なフィールドプロジェクションです。これらは読み取られません。

Ops Manager 履歴を読む のユーザーは、そのプロジェクション: ユーザーと支援のメッセージ、各ツール呼び出し、および各出力が表示されます。ツールとして使用されるエージェントへのハンドオフと呼び出しは、出力を含む通常の呼び出しとして表示されます。ネストされたエージェント独自の交信はコミットされないため、履歴にはありません。モデル呼び出しとツール呼び出しは実行のアクティビティ レコードにあります。

サポートされている項目は、テキストメッセージ、関数呼び出し、テキスト関数出力です。は 1 つのモデル応答をまとめて呼び出し、その後は他の呼び出しの前に 1 回の呼び出しごとに 1 つの出力を呼び出します。別のアプリまたはセッションに属するその他の項目、任意の状態、およびアクティブなエージェントによって、アプリは新しいモデルまたはツールの作業が開始される前にタームを失敗させることがなくなりました。

セッションとブランチ

Ops Manager のコミット状態は、唯一の 対話ストア です。アダプターは、その状態を入力として、Runner を自動的に呼び出すため、SDK Session オブジェクトは使用されず、プロバイダーがホストする継続（previous_response_id、ディスカッション ID、またはホストされたプロンプトなど）が実行者に渡されるか、から Agent.as_tool、または登録されたモデルの extra_body または extra_args）は、モデルが動作する前に失敗します。

ブランチは、別のセッションのコミットされた状態から開始される新しいセッションです。その最初のタームはソースの通信と アクティブなエージェントを続行し、独自のセッションでコミットし、その後はソースとは何も共有しません。承認は、どの順序でも同様に機能します。アダプターは 1 回ごとに 1 回コミットするため、完了した 回の最後に通信を中断できます。プラットフォームはコミットされたステップからのみブランチするため、承認を待機しているタームは完了するまでブランチに何も提供しません。

ブランチの作成は、SDK ではなく プラットフォーム操作です。アダプターはブランチAPIを追加せず、SDK 独自のセッションブランチ (AdvancedSQLiteSession.create_branch_from_turn) が利用できないため、アプリは自分のやり取りをブランチできません。プラットフォームのブランチAPI は実行します。

モデル呼び出し

ネイティブ Runner が作成するすべてのモデル呼び出しは、Organization Engine LM アクティビティになります。エージェントのモデルは記録されたアクティビティから応答し、モデル自体は ツール ポッド で実行されます。置換の試行では記録された応答が再生され、Runner に同一の出力項目が与えられます。

プラットフォームが処理する呼び出しごとの設定のみがその境界を超える。max_tokens、top_p、frequency_penalty、presence_penalty、timeout、parallel_tool_calls、reasoning.effort、verbosity、および という名前の tool_choice 。 temperature などのプロバイダー設定は登録したモデルに属し、ツール ポッドはそれを適用します。登録されたモデルには、tool_choice または timeout（エージェントに設定）、またはプロバイダーが保存された通信を継続するようにする extra_body / extra_args フィールドを実行できません（previous_response_id、conversation、conversation_id 、prompt）、またはアダプターが各呼び出しに対して構築する内容を上書きするもの（tools、input、instructions、または出力形式など）、または reasoning、reasoning_effort、または verbosity を設定するもの} が未加工フィールドとして表示されるようになりました（ModelSettings.reasoning と ModelSettings.verbosity を使用）。ネイティブ トレース、プロバイダーがホストする継続、および停止シーケンスは、 呼び出しが送信される前に失敗します。