PythonでAIエージェントを作る基本は、モデルへの依頼、使える関数の定義、関数呼び出し、結果の返却、終了判定を小さなループとして実装することです。 最初から複数エージェントや長期記憶を加える必要はありません。読み取り専用の関数を一つ接続し、正常終了と失敗終了の両方を観察できる構成から始めます。
AIエージェント開発を体系的に学びたい方は、AIエージェントが学べるおすすめスクールで、AI活用、Python実装、マンツーマン支援の違いを比較できます。
| 部品 | Python側の役割 | 最初の実装 |
|---|---|---|
| 指示 | 目的と禁止事項を渡す | 一つの仕事へ限定 |
| モデル | 次の行動または回答を選ぶ | 一種類を使う |
| ツール | 外部情報を読む、処理する | 読み取り関数を一つ |
| 状態 | 途中結果を保持する | 一回の実行内だけ |
| 制御 | 回数、例外、終了を管理する | 上限と失敗理由を表示 |
仮想環境と秘密情報を分けて準備する
プロジェクトごとに仮想環境を作り、SDKと依存関係を分離します。Python公式のvenv資料では、環境を作成して有効化する基本操作が説明されています。
APIキーはソースコードへ直接書かず、環境変数や秘密管理機能から読み取ります。公開リポジトリへ設定ファイルを含めないことも初期段階で確認します。
準備時の確認項目。
- Pythonの対象バージョンを決める
- 仮想環境を作る
- 必要なSDKだけを導入する
- APIキーを環境変数へ置く
- 入力と出力を記録する場所を決める
Python公式の環境変数資料を参照し、キーが未設定なら処理を開始せず、分かるエラーを返すようにします。
モデルと一つの関数で最小構成を作る
最初の題材には、商品を購入する関数ではなく、登録済みの資料名を検索する関数が向きます。関数名、引数の型、説明、戻り値を明確にすると、モデルが用途を判断しやすくなります。
OpenAI Agents SDKの公式資料では、Python関数をツールとして扱い、エージェントループ、セッション、ガードレール、トレースなどを実行基盤へ任せられます。
概念上の最小ループは次の形です。
for turn in range(MAX_TURNS):
decision = call_model(messages, tools=[search_docs])
if decision.is_final:
return decision.text
result = run_validated_tool(decision.tool_call)
messages.append(result)
raise RuntimeError("規定回数内に終了しませんでした")この例で重要なのはSDK名ではなく、回数上限、引数検証、終了理由をアプリケーション側が持つ点です。モデルが道具を呼ぶと決めても、実行前の許可判定はコードで行います。
関数の入力を検証し、結果を構造化する
「資料を探す」という曖昧な関数より、search_docs(query: str, limit: int)のように入力を限定します。件数の上限、空文字、許可される検索先を検証し、成功、結果なし、権限外、障害を別の状態として返します。
Agents SDKのツール資料では、Python関数のスキーマ化や、ホスト型ツール、ローカル実行ツール、エージェントをツールとして扱う方法が整理されています。戻り値はモデルに読ませる説明文だけでなく、監視しやすい構造も保持します。
| 結果 | 戻す情報 | 次の動作 |
|---|---|---|
| 成功 | 候補、件数、参照元 | 回答を作る |
| 結果なし | 空である事実、検索条件 | 条件変更を求める |
| 入力不正 | 対象引数、許容形式 | 再入力を求める |
| 権限外 | 拒否理由 | 実行せず終了 |
| 障害 | 種類、再試行可否 | 上限内で再試行 |
ログとテストで判断過程を追えるようにする
最終回答だけでは、モデルがどの関数をどの引数で選び、何が返ったか分かりません。依頼ID、ターン番号、関数名、検証結果、所要時間、終了理由を記録します。ただしAPIキーや個人情報をそのまま残さない設計が必要です。
Agents SDKのトレース資料では、モデル生成、関数呼び出し、引き継ぎ、ガードレールなどを追跡できます。機密データをトレースへ含める設定もあるため、便利さだけで有効化せず保存内容を確認します。
次の五件を最低限のテストにします。
- 一回の関数呼び出しで正しい候補を返す
- 結果がなく、推測せずに伝える
- 不正な引数を拒否する
- 関数の例外を利用者向けの失敗へ変換する
- 上限回数で停止し、理由を記録する
Agents SDKのガードレール資料も、入力、出力、関数ツール周辺で検査を置く方法を説明しています。各仕組みの適用範囲は異なるため、ガードレールがあるだけで全操作が保護されるとは考えません。
AIエージェントの学習順序と合わせ、Python文法、API、ツール呼び出し、評価の順に習得すると実装上の迷いを減らせます。
Pythonで作るAIエージェントでよくある質問
Python初心者でも作れますか？
関数、辞書、例外処理、環境変数を学んだ段階で小さな試作は可能です。非同期処理やデータベースは後回しにし、一つの関数を安全に呼び出して停止できることを先に目標へ置くと進めやすくなります。
フレームワークを使わずに実装できますか？
モデルAPIの応答を読み、関数を振り分け、結果を再送する処理を自作すれば実装できます。一方でターン管理、トレース、セッションなども自分で持つため、学習目的か運用目的かで自作範囲を決めてください。
最初からデータベース更新を任せてもよいですか？
最初は検索や参照に限定し、引数検証と停止条件を確認する方が安全です。更新を追加するときは、対象レコードと変更内容を表示し、人の承認後に一回だけ実行する構成から試します。
最小ループを説明できれば次の基盤を選べる
Python実装では、モデルの賢さよりも、入力から終了までの制御をコードで明示することが土台です。各部品の責任を分ければ、後からフレームワークを採用しても挙動を追えます。
- 仮想環境と秘密情報をソースコードから分ける
- 一つの読み取り関数でモデルとツールの往復を作る
- 引数、権限、回数上限を実行側で検証する
- ログと失敗テストで終了理由を確認する
共通処理をフレームワークへ任せたい方は、LangChainによるAIエージェント開発でツール定義と実行ループの組み方を確認できます。
