OpenAI Agents APIを試してみた

AIエージェントの実行に必要な仕組みをまとめて扱えるOpenAI Agents APIを試してみました。

Agents APIへタスクを渡し、AIが作業する途中経過を受け取り、最後に作成したファイルをダウンロードしてみます。

APIが動いたことを確かめやすいように、小さな売上CSVを渡します。回答を受け取るだけでなく、ファイルの生成とダウンロードまで試します。

OpenAI Agents APIについて調べてみる

最初にAgents APIの公式ドキュメントを読みました。

Agents API のご紹介 | OpenAI こちらは日本語での紹介ページです。

イメージとしては、Codexの作業部分を自分のプログラムから呼び出す感覚に近そうです。

これまでAPIを使ってAIエージェントを作る場合、モデルへ指示を渡すだけでなく、ツールを実行して結果を返す流れや、作業状態をどこへ残すかも自分のプログラム側で考える必要がありました。

Agents APIでは、セッション、作業の進行、会話が長くなったときの整理、失敗後の復旧などをOpenAI側のハーネスが管理します。

今回の検証で登場する言葉は4つあります。

• agent: 利用するモデルや、作業時の指示をまとめたもの
• session: ひとまとまりの作業と、そのやり取りを保持する場所
• environment: AIがコマンドやプログラムを実行する場所
• event: 作業開始、コマンド実行、完了など、セッション内で発生した出来事

つまり、Agents APIへタスクを渡すと、エージェントが指定した環境で作業し、その様子がイベントとして返ってきます。

自分のプログラム
  ↓ タスクを送る
Agents APIのsession
  ↓
agentが作業する
  ↓
途中経過がeventとして返る
  ↓
作成されたファイルを取得する

今回は、ここまでを一度通して動かしてみます。

今回Agents APIへ頼む作業

動作確認には、次の売上CSVを使います。

date,product,amount
2026-09-01,商品A,1000
2026-09-02,商品B,1500
2026-09-03,商品A,1200
2026-09-04,商品C,900
2026-09-05,商品B,500
2026-09-06,商品C,1100
2026-09-07,商品A,800
2026-09-08,商品B,2000

Agents APIへ渡すタスクはこちらです。

/workspace/sales.csvをPython標準ライブラリで集計してください。

1. productごとのamount合計を降順に並べ、
   /workspace/outputs/sales_summary.csvへ保存する
2. 全体の売上合計、もっとも売上が大きいproduct、product別の合計を、
   /workspace/outputs/report.mdへ日本語で保存する
3. 2ファイルを読み直し、計算結果とファイル内容が一致することを確認する

回答文だけで終わらず、実際にPythonを動かし、ファイルを2つ作れれば成功とします。

通常のAPIでは、Pythonは自分で書く必要がありますよね。

検証用のファイル

次の構成にしました。

openai-agents-api/
├── .env.example
├── .gitignore
├── cleanup_session.py
├── data/
│   └── sales.csv
├── requirements.txt
├── run_agent.py
└── results/

run_agent.pyがAgents APIを呼び出すプログラムです。

実行中に届いたイベントはevents.jsonlへ残します。作成されたファイルとセッション情報もresultsへ保存します。

APIキーを用意する

Agents APIのQuickstartでは、アプリケーションAPIキーに次の権限が必要と書かれていました。デフォルトでは有効になっています。

• api.agents.read
• api.agents.write
• api.responses.write

.env.exampleをコピーします。

cd experiments/openai-agents-api
cp .env.example .env

作成した.envへAPIキーを設定します。

OPENAI_API_KEY=ここへAPIキーを設定
OPENAI_MODEL=gpt-6-astra

もしもの時のために、APIキーがGitへ入らないよう.envは.gitignoreへ追加しておきましょう。

OpenAI Python SDKを更新する

仮想環境を作り、OpenAI Python SDKを入れます。

python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install --upgrade -r requirements.txt

Macに入っていたopenai 2.46.0を確認すると、client.beta.agentsがありませんでした。

公式のQuickstartにもpip install --upgrade openaiと書かれています。Agents APIはベータ版なので、すでにSDKを入れている場合も更新が必要なようです。

検証用プログラムでも、client.beta.agentsが見つからない場合はSDKを更新するよう表示します。

Agents APIでセッションを作る

Agents APIでは、セッションを作るときにエージェントの設定、実行環境、最初のタスクをまとめて渡せます。

今回の中心になる部分はこちらです。

with client.beta.agents.sessions.create(
    agent={
        "model": model,
        "instructions": "作業は実際に実行し、生成したファイルを読み直して確認してください。",
    },
    environment={
        "type": "openai_hosted",
        "network": {"access": "disabled"},
        "files": [
            {
                "type": "inline",
                "path": "/workspace/sales.csv",
                "data": encoded_csv,
            }
        ],
    },
    input=task,
    stream=True,
) as events:
    for event in events:
        print(event.type)

今回はエージェントを事前登録せず、セッションの中へモデルと指示を直接書きました。

environmentにはopenai_hostedを指定しています。これはOpenAIが用意するLinux環境です。Agents APIには自分で用意した環境を接続する方法もありますが、最初の検証なので構築が不要なほうを選びました。

集計に外部通信は必要ありません。そこで、実行環境からのネットワーク接続はdisabledにしています。

ローカルのsales.csvはBase64という文字列へ変換し、/workspace/sales.csvとして渡します。

イベントを保存する

stream=Trueを指定すると、セッション内で発生したイベントを順番に受け取れます。

画面へ表示するだけでは後から確認できないため、受信したJSONをevents.jsonlにも保存します。

for event in events:
    payload = event.model_dump(mode="json")
    log.write(json.dumps(payload, ensure_ascii=False) + "\n")
    print(f"event={payload.get('type', 'unknown')}")

AIの回答だけでなく、実行環境の準備やコマンドの実行もイベントとして流れてくるのか確認します。

作成されたファイルを取得する

実行環境で作られたファイルを、ここではartifactと呼びます。

Files and artifactsによると、OpenAIが用意した環境では、/workspace/outputsのファイルが作業完了時にartifactとして公開されるようです。

セッション完了後に一覧を取得し、手元へダウンロードします。

for artifact in client.beta.agents.sessions.artifacts.list(session_id):
    destination = RESULTS_DIR / "artifacts" / Path(artifact.path).name

    with client.beta.agents.sessions.artifacts.with_streaming_response.content(
        artifact.id,
        session_id=session_id,
    ) as response:
        response.stream_to_file(destination)

Agents APIへ仕事を頼むところだけでなく、その結果を自分のプログラムへ戻すところまで試せます。

Agents APIを実行する

次のコマンドで実行します。

python3 run_agent.py

実行結果はこちらです。

API実行とOpenAI-hosted sandboxesの料金がかかります。

完了すると、次のファイルが作られます。

results/
├── events.jsonl
├── summary.json
└── artifacts/
    ├── report.md
    └── sales_summary.csv

ダウンロードしたファイルを確認します。

cat results/artifacts/sales_summary.csv
cat results/artifacts/report.md
cat results/summary.json

sales_summary.csvの内容はこちらです。

product,amount
商品B,4000
商品A,3000
商品C,2000

入力したCSVを手元で計算すると、売上合計は9,000です。

商品別では、商品Bが4,000、商品Aが3,000、商品Cが2,000になります。Agents APIが作った2ファイルと一致するか確認します。

report.mdの内容はこちらです。

# 売上集計レポート

全体の売上合計：9,000

もっとも売上が大きいproduct：商品B（売上合計：4,000）

## product別の合計（売上合計の降順）

| product | amount合計 |
| --- | ---: |
| 商品B | 4,000 |
| 商品A | 3,000 |
| 商品C | 2,000 |

※金額の単位は元のCSVに記載されていません。同額の場合はproduct名の昇順で掲載しています。

一致しています。

OpenAI Agents APIにはテンプレート機能もある

OpenAI API Platformに新設されたAgents APIにアクセスしたらテンプレート機能を発見しました。

どうやらエージェントの用途を定義して置けるらしいです。

最初の SRE agent for incident response を見てみます。

インシデント報告用SREエージェントの定義(引用)

試してみて

Agents APIは、サンドボックス環境まで付随してタスク実行を行えるようになります。モデルへ質問して回答を受け取るだけのAPIはアプリケーション側での実装が必要でしたが、その必要もありません。いよいよプログラミングが代替されつつある実感を強くしました。

今回は1回のタスクで終わらせています。次は同じセッションへ追加の指示を送り、前の作業内容やファイルを引き継げるのか試してみたいです。

ここまで読んでいただき、ありがとうございます。もしこの記事の技術や考え方に少しでも興味を持っていただけたら、ネクストのエンジニアと気軽に話してみませんか。

• 選考ではありません
• 履歴書不要
• 技術の話が中心
• 所要時間30分程度
• オンラインOK

エンジニアと話してみる