[備忘録] OpenAIのAgents SDKをGoogle Colabで試す

この記事では、OpenAIの新しいエージェント開発ツール「Agents SDK」をGoogle Colabで試した経験をまとめます。カレー作りを例に、複数のAIエージェントが連携するシステムを、シンプルなコードで構築する方法を紹介します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2648069/3f62afcb-f1f3-4fd1-a5aa-efb9f7e8e3d3.png)


## Agents SDKとは？

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2648069/ea67da4e-c11e-4a33-854f-b148004026bb.png)


Agents SDKは、OpenAIが提供する新しいオープンソースのPythonライブラリで、複数のAIエージェントを効率的に連携させることができます。以前実験的に公開されていた「Swarm」の後継にあたり、より洗練されたインターフェースと機能を備えています。

### 主な特徴

- **マルチエージェント連携**: 複数のエージェントが協力して複雑なタスクを処理
- **ハンドオフ機能**: 適切なタイミングで別のエージェントに処理を引き継ぐ
- **ツール統合**: Web検索など組み込みツールやカスタムツールをシームレスに統合
- **開発効率**: わずか数行のコードで複雑なAIエージェントシステムを構築可能

## 第一印象：シンプルで直感的なインターフェース

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2648069/31af81aa-ca1f-4c12-b84a-b1ba2148838a.png)

Agents SDKを初めて使ってみて、**予想以上にシンプルな実装**に驚きました。特に印象的だったのは、Pythonの関数呼び出しのような自然な形でAIエージェントを定義でき、複雑な振る舞いを少ないコード量で表現できる点です。デコレータを使った関数ツールの定義など、Pythonic（Python的）な設計思想が随所に見られます。

それでは、Google Colabで実際に動かしたサンプルコードをもとに、具体的な実装例を見ていきましょう。

## Google Colabでの環境セットップと基本実装

まず、Google Colabで必要なライブラリをインストールし、環境を設定します。

```python
import os
from google.colab import userdata

# ユーザー情報からAPI キーを取得
api_key = userdata.get('OPENAI_API_KEY')

# 取得した値を環境変数に設定
os.environ['OPENAI_API_KEY'] = api_key

# Agents SDKをインストール
!pip install openai-agents

# Google Colabでの非同期処理のための設定
!pip -q install nest_asyncio
import nest_asyncio
nest_asyncio.apply()
```

次に、カレー作りを例に、基本的なマルチエージェントシステムを実装してみましょう。カレー作りのプロセスを「材料担当」と「調理担当」に分け、「カレーマスター」がユーザーからの質問を適切な担当に振り分けます。

```python
from agents import Agent, Runner, WebSearchTool, function_tool

# 材料準備ツール
@function_tool
def check_ingredients(recipe_type: str) -> dict:
    """カレー作りに必要な材料の在庫状況を確認します"""
    return {
        "available": ["玉ねぎ", "にんじん", "じゃがいも", "カレールウ"],
        "missing": ["牛肉", "ローリエ"]
    }

# 材料担当エージェント
ingredients_agent = Agent(
    name="材料担当",
    instructions="カレーに必要な材料を確認し、提案します。",
    tools=[check_ingredients, WebSearchTool()]
)

# 調理担当エージェント
cooking_agent = Agent(
    name="調理担当",
    instructions="カレーの調理手順を説明します。",
    tools=[WebSearchTool()]
)

# メインエージェント
curry_master = Agent(
    name="カレーマスター",
    instructions="ユーザーの要望を理解し、適切な担当に振り分けます。",
    handoffs=[ingredients_agent, cooking_agent]
)

# 実行
result = Runner.run_sync(
    starting_agent=curry_master,
    input="初めてカレーを作ります。どうすればいいですか？"
)

# 最終結果を表示
print(result.final_output)
```

## 実行結果：初めてのカレー作り

上記のコードを実行すると、カレーマスターが適切なエージェントにタスクを振り分け、以下のような結果が得られました：

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2648069/bf1e297d-ce5c-4f14-8bdb-4064c7ff17b0.png)

```
初めてカレーを作る際の基本的な手順を説明します。これらは一般的な日本風のカレーレシピに基づいています。

### 材料
- カレールー（市販のもの）
- 玉ねぎ 1〜2個
- 人参 1本
- じゃがいも 2〜3個
- 肉（鶏肉、豚肉、牛肉のいずれか）300〜400g
- 水 500ml〜800ml（ルーのパッケージを参考にしてください）
- 米 2〜3合（ご飯として）

### 作り方

1. **下準備をする**
   - 玉ねぎは薄切りにします。
   - 人参は一口大の乱切りにします。
   - じゃがいもも一口大にカットします。
   - 肉は食べやすい大きさに切ります。

2. **材料を炒める**
   - 鍋を中火で熱し、油を引きます。
   - 玉ねぎを入れ、飴色になるまで炒めます。
   - 肉を加え、色が変わるまで炒めます。
   - 人参とじゃがいもを加え、軽く炒めます。

3. **煮込む**
   - 材料がかぶるくらいの水を加えます。
   - 沸騰したらアクを取り、弱火にして材料がやわらかくなるまで約15分〜20分煮込みます。

4. **ルーを溶かす**
   - 火を止め、カレールーを加え混ぜます。
   - 再び火をつけ、弱火で10分ほどかき混ぜながら煮込みます。

5. **仕上げ**
   - 全体がなじんだら火を止めます。
   - ご飯の上にかけてお召し上がりください。

お好みで他の野菜や隠し味を加えても良いでしょう。楽しんで作ってくださいね！
```

**感想：** デコレータを使った関数ツールの定義が特に気に入りました。Pythonらしく、宣言的にエージェントを定義できるため、コードが読みやすく保守しやすいです。`handoffs`パラメータによるエージェント間の連携も直感的です。同じ量のコードで、驚くほど豊富な結果が得られる点に感動しました。

## 従来の複雑な実装と比較して

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2648069/3131e110-bfbd-4c5e-a212-e63d7d0eb00a.png)

以前は同様の機能を実装するために、次のような複雑な処理が必要でした：

1. ユーザー入力を解析
2. 何をすべきか判断するためのプロンプト設計
3. 適切なAPIを選択
4. ツールの呼び出し方法をAIに教える
5. ツールからの結果を再びAIに渡す
6. 複数ターンの会話を管理する状態管理

新しいAPIとSDKでは、これらの多くが自動化され、開発者は本質的な部分（どんなツールが必要か、どんなエージェントが必要か）に集中できます。

## なぜこれがゲームチェンジャーなのか

1. **開発時間の短縮**: シンプルなインターフェースにより、プロトタイピングから本番実装までの時間が大幅に短縮されます

2. **メンテナンス性の向上**: わかりやすいコード構造により、長期的なメンテナンスが容易になります

3. **スケーラビリティ**: 必要に応じてエージェントを追加するだけで、システムを拡張できます

4. **学習コストの低減**: APIの一貫性により、新しい機能を学ぶ時間が短縮されます

特に、デコレータを使った関数ツールの定義や、エージェントの宣言的な定義は、Pythonの哲学「明示的であることがimplicitであることよりも優れている」に沿っており、コードの意図が明確になります。

## 実装する上での注意点

シンプルな反面、初期段階のツールであるため、以下の点には注意が必要です：

1. **エラーハンドリング**: まだ安定していない部分があるため、適切なエラーハンドリングを実装すべき
2. **コスト管理**: 特にWeb検索やコンピュータ操作は比較的高額なので、使用量の監視が重要
3. **APIの変更**: 今後インターフェースが変わる可能性があるため、定期的に公式ドキュメントを確認する

### エラーハンドリング

Agents SDKでは、エラーが発生した場合の適切な処理が重要です。特にAPIが新しいため、予期せぬエラーに備えましょう。

```python
try:
    result = Runner.run_sync(
        starting_agent=curry_master,
        input="初めてカレーを作ります。どうすればいいですか？"
    )
except Exception as e:
    print(f"エラーが発生しました: {e}")
    # フォールバック処理
```

### コスト管理

Agents SDKを使用すると、複数のモデル呼び出しが発生するため、コスト管理が重要になります。特に本番環境で使用する場合は、使用量をモニタリングする仕組みを考慮しましょう。

## まとめ：Agents SDKの魅力

![agents-sdk-appeal-fixed.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/2648069/5ae4cfb0-41c6-4555-b8d9-c74a6312add1.png)


Google Colabで実際にAgents SDKを試した結果、そのシンプルさと直感的なインターフェースに感銘を受けました。特にPythonの機能を活かした宣言的なエージェント定義と、デコレータを使ったツール実装は開発効率を大きく向上させます。

カレー作りでたとえると：
- **Agents SDK** = 専門性を持ったシェフチームによる効率的な分業システム
- **ハンドオフ機能** = 各工程の専門家への円滑な引き継ぎ
- **カスタムツール** = 特別な調理器具や秘伝のレシピ

個人的には、わずか数十行のコードで複雑なマルチエージェントシステムを構築できる点が最大の魅力だと感じました。このような直感的な開発体験により、AIエージェント開発の敷居が大きく下がり、より多くの開発者が高度なAIアプリケーションを簡単に構築できるようになるでしょう。

---

*追記: この記事はOpenAIのAgents SDKの初期バージョン（2025年3月時点）に基づいています。今後のアップデートで変更される可能性があるため、最新の公式ドキュメントを参照することをお勧めします。*

## 参考
[OpenAI エージェント開発のための新たなツール](https://openai.com/ja-JP/index/new-tools-for-building-agents/)