1. ツールの構造 – Type hints・Docstrings・Decoraters の役割 –
OpenAI Agents SDK を使ってエージェントにツールを持たせるには、単に Python の関数を書くだけでは不十分。Type hint（タイプヒント）、Docstrings（ドックストリング）、Decorater（デコレーター）という3つの要素を正しく組み合わせることで、エージェントはその関数を意味のあるツールとして理解できるようになる。
2. サンプルコード
@function_tool
def check_membership_level(user_id: int) -> str:
"""
会員IDを受け取り、その会員ランクを返します。
引数:
user_id (int): 会員ID
戻り値:
str: 会員ランクを表す文字列
"""
if user_id in (1, 2):
return "Gold"
elif user_id in (3, 4):
return "Silver"
else:
return "Bronze"
(1) タイプヒント（Type hints）
def check_membership_level(user_id: int) -> str:
ここで使われている : int や -> str が タイプヒント。
user_id: int
→ 引数user_idは整数であることを示す。-> str
→ 戻り値は文字列であることを示す。
通常の Python では型を書かなくても動くが、Agents SDK では重要な意味を持つ。
SDK は この型情報をそのまま LLM に渡し、「このツールは整数を受け取り、文字列を返す」と理解させる。
つまりタイプヒントは、
- 人間向けの説明
- エージェント向けの仕様定義
を同時に担っている。
(2) ドックストリング（Docstrings）
"""
会員IDを受け取り、その会員ランクを返します。
"""
関数定義の直後に書かれる文字列が Docstring 。
Agents SDK では、Docstring が以下のような役割を果たす。
- この関数が「何をするツールなのか」を LLM に伝える。
- 引数や戻り値の意味を補足する。
- ツール選択時の判断材料になる。
Docstring は必須ではないが、書いておくことで エージェントの誤解を減らせる。
「人間向けの関数コメント」ではなく、「LLM向けの説明書」と考えると理解しやすい。
(3) デコレーター（Decoraters）
@function_tool
この1行があることで、単なる Python 関数が 「エージェントが呼び出せるツール」 に変わる。
デコレーターの役割は以下のとおり。
- この関数を SDK に登録する。
- 型ヒントや Docstring を解析対象にする。
- LLM が「この関数を使ってよい」と判断できるようにする。
言い換えると「この関数はエージェントの行動の一部として使ってよい」と宣言するのがデコレーターである。
3. なぜこの3点セットが重要なのか
OpenAI Agents SDK は、関数をコードとしてではなく“仕様”として読む 仕組みになっている。
- タイプヒント → 入出力の形式
- ドックストリング → 目的と意味
- デコレーター → ツールとしての登録
この3つが揃って初めて、エージェントは関数を正しく理解し、適切な場面で呼び出せるようになります。
4.まとめ
- タイプヒントは「入力と出力の契約」
- Docstring は「エージェント向けの説明書」
- デコレーターは「ツールとして使ってよいという宣言」
Agents SDK を使う上では、
「Python関数を書く」＝「エージェント用APIを定義する」
という意識を持つことが重要になる。