AI・機械学習
OpenAI Agents API
OpenAI Agents API (developers.openai.com)
要約
OpenAIが新たに発表したAgents APIは、アプリケーションにCodexハーネスへのアクセスを提供します。このAPIは、セッション管理、オーケストレーション、コンテキスト圧縮、リカバリなどをOpenAIが担当し、アプリケーション側はツール提供や実行環境の選択を行います。エージェントはコード実行、ファイル編集、外部サーバー接続などが可能なサンドボックス内で動作でき、インシデント対応、データ分析、GitHub issue調査など多様なユースケースが想定されています。
全文翻訳
Agents APIは、アプリケーションにOpenAI管理のAPIを介してCodexハーネスへのアクセスを提供します。OpenAIはセッション、オーケストレーション、コンテキスト圧縮、リカバリを管理し、アプリケーションはツールを提供し、実行環境を選択します。エージェントは、コードを実行し、ファイルを編集し、MCPサーバーに接続し、成果物を生成できるサンドボックスで動作できます。料金モデルの使用は、選択されたモデルのAPIレートで請求されます。OpenAIツールは標準レートを使用し、OpenAIホストのサンドボックスは標準コンテナレートを使用します。
例を試す
これらの完全な例を試してください:
OpenAIホストのサンドボックスでディレクトリツリー スクリプトを作成および実行する。
リリースノートをサブエージェントと比較し、それらの結果を 1 つの回答にまとめる。
完全なアプリケーションを探索する:
インシデント対応エージェント: アラートを調査し、復旧アクションの承認を要求する。
Slack ボット: 接続されたワークプレイスツールを使用してリクエストを調査する。
データアナリスト: 読み取り専用 SQL でウェアハウスの質問に答える。
GitHub issue 調査員: 報告されたバグを再現し、GitHub で調査結果を共有する。
ドキュメントレビュー担当者: ポリシースキルと専門エージェントでドキュメントをレビューする。
コアコンセプト
Agents APIは、次の 4 つの主要な概念を中心に構築されています:
エージェント: エージェントが利用できるモデル、指示、ツール、MCPサーバー。
環境: エージェントがファイルにアクセスし、スキルをロードし、コマンドを実行する、オプションのサンドボックスまたはコンピューター。
セッション: タスクに取り組み、入力に応答する、エージェントの永続的なインスタンス。
イベントとアイテム: エージェントに送信される入力と、セッション中に生成される出力。
セッションの開始から終了まで
クイックスタートで OpenAI ホストのサンドボックスから始めます:
セッションを作成します。
エージェントを構成します。OpenAI がその環境をプロビジョニングします。
タスクを与えます。
環境が準備できたら、ユーザー入力が作業のターンを開始します。
進捗状況を追跡します。
エージェントが完了したとき、または入力を必要とするときに学習するために、出力をストリームするか、Webhook を使用します。
続行または指示する。
同じセッションに別のタスクを送信するか、現在のターン中にエージェントをガイドします。
OpenAI ホストのセッションでは、アプリケーションは入力を送信しイベントを受信し、OpenAI はエージェントを実行し、サンドボックスをプロビジョニングおよび管理します。
セットアップと制限については、環境オプションを参照してください。
管理ハーネスが提供するもの
管理された Codex ハーネスは、以下をサポートします:
サンドボックスでのコマンドとコードの実行。
関連するスキルと指示の適用。
ツールまたは MCP を介した外部データへの接続。
作業中のエージェントの指示。
コンテキストウィンドウを管理するための以前の作業の要約。
作業をサブタスクに分割し、サブエージェントに委任する。
セッションを中断したところから再開する。
API キーの権限と SDK セットアップについては、クイックスタートの前提条件を確認してください。
セッションを作成するときに、これらの機能を構成します:
管理ハーネスの機能を構成する
Python
import OpenAI from "openai";
const client = new OpenAI();
const session = await client.beta.agents.sessions.create({
agent: {
model: "gpt-6-astra",
instructions: "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
tools: [
{ type: "programmatic_tool_calling" },
{
type: "mcp",
server_label: "openai_docs",
transport: {
type: "http",
server_url: "https://developers.openai.com/mcp",
},
},
{ type: "web_search" },
],
multi_agent: {
enabled: true,
max_concurrent_subagents: 4
},
},
environment: {
type: "self_hosted",
workspace_directory: "/workspace",
capability_directories: ["/workspace/capabilities/skills"],
},
input: [
{
role: "user",
content: [
{
type: "input_text",
text: "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup.",
},
],
},
],
});
console.log(session.id);
JavaScript
from openai import OpenAI
client = OpenAI()
session = client.beta.agents.sessions.create(
agent={
"model": "gpt-6-astra",
"instructions": "Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful.",
"tools": [
{"type": "programmatic_tool_calling"},
{
"type": "mcp",
"server_label": "openai_docs",
"transport": {
"type": "http",
"server_url": "https://developers.openai.com/mcp",
},
},
{"type": "web_search"},
],
"multi_agent": {"enabled": True, "max_concurrent_subagents": 4},
},
environment={
"type": "self_hosted",
"workspace_directory": "/workspace",
"capability_directories": ["/workspace/capabilities/skills"],
},
input=[
{
"role": "user",
"content": [
{
"type": "input_text",
"text": "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup.",
}
],
}
],
)
print(session.id)
Go
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
)
ctx := context.Background()
client := openai.NewClient()
session, err := client.Beta.Agents.Sessions.New(ctx, openai.BetaAgentSessionNewParams{
Agent: openai.BetaAgentSessionNewParamsAgent{
Model: openai.String("gpt-6-astra"),
Instructions: openai.String("Use the OpenAI documentation MCP and web search to answer technical questions accurately. Delegate independent research tasks to subagents when useful."),
Tools: []openai.AgentToolParamUnion{
openai.AgentToolParamUnion{OfParamProgrammaticToolCalling: &openai.AgentToolParamProgrammaticToolCalling{}},
openai.AgentToolParamUnion{OfParamMcp: &openai.AgentToolParamMcp{ServerLabel: "openai_docs", Transport: openai.McpTransportParamUnion{OfParamHTTP: &openai.McpTransportParamHTTP{ServerURL: "https://developers.openai.com/mcp"}}}},
openai.AgentToolParamUnion{OfParamWebSearch: &openai.AgentToolParamWebSearch{}},
},
MultiAgent: openai.MultiAgentConfigParam{
Enabled: true,
MaxConcurrentSubagents: openai.Int(4)
},
},
Environment: openai.EnvironmentParamUnion{OfParamSelfHosted: &openai.EnvironmentParamSelfHosted{WorkspaceDirectory: "/workspace", CapabilityDirectories: []string{"/workspace/capabilities/skills"}}},
Input: openai.BetaAgentSessionNewParamsInputUnion{
OfArrayOfInputMessages: []openai.AgentSessionInputMessageParam{
openai.AgentSessionInputMessageParam{
Content: []openai.InputContentParamUnion{
openai.InputContentParamUnion{OfParamInputText: &openai.InputContentParamInputText{Text: "Research how to connect an MCP server to an OpenAI agent, check for recent updates, and summarize the recommended setup."}}}}
}
})
if err != nil {
panic(err)
}
fmt.Println(session.ID)
Java
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.beta.agents.AgentToolParam;
import com.openai.models.beta.agents.EnvironmentParam;
import com.openai.models.beta.agents.McpTransportParam;
import com.openai.models.beta.agents.MultiAgentConfigParam;
import com.openai.models.beta.agents.sessions.SessionCreateParams;
import java.util.List;
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
var session = client
.beta()
.agents()
.sessions()
.create(
SessionCreateParams.builder()
.agent(
SessionCreateParams.Agent.builder()
.model("gpt-6-astra")
.instructions("Use the OpenAI documentation MCP and web search to answer"
+ " technical questions accurately. Delegate independent"
+ " research tasks to subagents when useful.")
.addTool(AgentToolParam.ProgrammaticToolCalling.builder().build())
.addTool(
AgentToolParam.Mcp.builder()
.serverLabel("openai_docs")
.transport(
McpTransportParam.Http.builder()
.serverUrl("https://developers.openai.com/mcp")
.build())
.build())
.addTool(AgentToolParam.WebSearch.builder().build())
.multiAgent(
MultiAgentConfigParam.builder()
.enabled(true)
.maxConcurrentSubagents(4L)
.build())
.build())
.environment(
EnvironmentParam.SelfHosted.builder()
.workspac