エージェント向けLLMモデルAPI:ツール呼び出しガイド
エージェントとはループです:モデルがツールを選択し、あなたのコードがそれを実行し、結果が戻り、モデルが次の行動を決定します。ここではそのループの実装例と、計画に考慮すべき制限とコストを示します。

主要ポイント
- エンドポイントはツール、tool_choice、ストリーミングされたtool_calls、およびrole: toolの結果をサポートしています。
- ループに上限を設定し、ツール引数を検証し、短い待機後に429レスポンスを再試行してください。
- フルキーでは並列ワーカーを8以下に保ってください。ストリームは終了するまでスロットを占有します。
- コンテキストウィンドウが拡大する6ステップのエージェント実行には、約0.5セントの費用がかかります。
エージェントがAPIから必要とするもの
エージェント向けLLMモデルAPIを選択する場合、チェックリストはマーケティングが示すよりも短くなります。信頼性の高い関数呼び出し、実行中の会話記録を保持できる十分なサイズのコンテキストウィンドウ、予測可能なレート制限、そして多数の呼び出しを行うループに対してペナルティを与えない価格が必要です。
このAPIは標準的なOpenAIインターフェースを通じてこれらの要件を満たします。toolsとtool_choiceをサポートし、通常およびストリーミングの両方のレスポンスでtool_callsを返し、role: "tool"を持つメッセージとしてツール結果を受け入れます。JSON modeはresponse_formatを通じて利用可能です。コンテキストウィンドウはプロンプトとcompletionを合わせて100,000トークンで、モデルIDはuncensoredです。
フレームワーク側は単なるOpenAIクライアントであるため、ベースURLを設定できるエージェントライブラリのほとんどが動作します。それらをhttps://api.llmmodelsapi.com/v1にポイントし、キーを指定してモデル名を指定します。セットアップの詳細はドキュメントに記載されており、キーページからキーを取得できます。
設計を左右する2つの制限があります。まず、モデルはテキストのみであるため、画像、音声、ファイルの処理はすべてツールで行い、テキストとして戻す必要があります。第二に、このエンドポイントには埋め込み機能がないため、エージェントが検索を行う場合、ベクトル検索には別のソースが必要です。
ループを健全に保つシステムプロンプト
エージェントの失敗の多くはAPIの問題ではなく、あいまいな指示に起因します。優れたシステムプロンプトは、モデルが何者であり、どのツールが存在し、いつ停止し、最終回答の形式がどうなるかを伝えます。以下はリサーチアシスタント用のプロンプトです。
あなたはリサーチアシスタントです。ツールsearch_notesとread_noteを呼び出すことができます。すでに情報を持っていない場合にのみツールを呼び出してください。ツール呼び出しは最大5回まで使用してください。十分な情報が得られたら、短い回答を返し、使用したノートIDをリストしてください。ノートに回答が含まれていない場合は、それを明確に伝えてください。
このプロンプトが何をしているか注目してください。ツール名を指定し、呼び出しの予算を設定し、停止条件を定義し、モデルに「知らない」と言う許可を与えています。最後の部分が重要なのは、無理に回答を迫られたエージェントが何かをでっち上げるからです。
ツール使用には低いtemperatureを設定してください。0.2から0.4の値はツール名と引数フォーマットを安定させます。エージェントが最後にクリエイティブなテキストも生成する場合は、最後の呼び出しのみtemperatureを上げることができます。seedパラメータは渡されるため、デバッグ中に実行を再現する際に役立ちます。
成人向けフィクションやロールプレイエージェントでも、同じパターンが有効です。システムメッセージにペルソナ、シーンルール、ツールを指定してください。このモデルは、法的な成人利用に対してコンテンツ拒否なしで回答するようにチューニングされています。未成年者を含む性的コンテンツは制限対象となります。
Pythonでの最小限のエージェントループ
以下のループには1つのツールがあり、実際のデータの代わりとなる辞書ルックアップです。モデルがツール呼び出しなしで応答するか、固定数のステップ後に停止するまで続行します。
import json
from openai import OpenAI
client = OpenAI(base_url="https://api.llmmodelsapi.com/v1", api_key="YOUR_KEY")
NOTES = {
"n1": "Invoice 114 was paid on March 3.",
"n2": "Invoice 115 is overdue by 12 days.",
}
def search_notes(query):
return [{"id": k, "text": v} for k, v in NOTES.items() if query.lower() in v.lower()]
TOOLS = [{
"type": "function",
"function": {
"name": "search_notes",
"description": "Search internal notes by keyword",
"parameters": {
"type": "object",
"properties": {"query": {"type": "string"}},
"required": ["query"],
},
},
}]
SYSTEM = "You are a research assistant. Use search_notes when needed, at most five calls. Then answer briefly."
def run(question, max_steps=6):
messages = [
{"role": "system", "content": SYSTEM},
{"role": "user", "content": question},
]
for step in range(max_steps):
resp = client.chat.completions.create(
model="uncensored",
messages=messages,
tools=TOOLS,
temperature=0.3,
max_tokens=500,
)
msg = resp.choices[0].message
messages.append(msg)
if not msg.tool_calls:
return msg.content
for call in msg.tool_calls:
try:
args = json.loads(call.function.arguments)
result = search_notes(args["query"])
except Exception as exc:
result = {"error": str(exc)}
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(result),
})
return "Stopped: step limit reached."
print(run("Which invoice is overdue?"))
注意すべき3つの詳細があります。ステップ制限は、混乱したモデルが予算が尽きるまでループしないようにします。tryブロックは、不正な引数文字列をモデルが読み取り修正できるエラーメッセージに変換します。また、すべてのツール結果は一致するtool_call_idで送信され、これがモデルに各回答がどの呼び出しに属するかを知らせます。
429レスポンスと同時実行の処理
エージェントはバースト性があります。プランナーは一度に5つのサブタスクを展開し、それぞれが独自のループを実行します。ここでレート制限が発生します。
フルキーでは8つの同時リクエストと1分あたり300リクエストが許可されます。トライアルキーでは2と60です。制限を超えるとAPIはHTTP 429を返します。エラーコードはどの制限に達したかを示します:1分あたりのリクエスト数はrate_limited、同時実行数が多すぎる場合はconcurrencyです。一時的な過負荷時には、Retry-After: 5ヘッダー付きで429も返されます。
これらすべてを再試行可能として扱ってください。ヘッダーの秒数、またはヘッダーがない場合は数秒待ってからリクエストを再送信してください。失敗したリクエストは課金されないため、再試行にはコストがかかりません。小さなラッパーでこのタスクを実行できます。
import time
from openai import OpenAI, RateLimitError
client = OpenAI(base_url="https://api.llmmodelsapi.com/v1", api_key="YOUR_KEY", max_retries=0)
def chat_with_retry(**kwargs):
for attempt in range(5):
try:
return client.chat.completions.create(model="uncensored", **kwargs)
except RateLimitError as err:
wait = 5
if err.response is not None:
wait = int(err.response.headers.get("retry-after", 5))
time.sleep(wait)
raise RuntimeError("Still rate limited after 5 attempts")
429を回避するために、ワーカープールに上限を設定してください。セマフォ8はフルキーに一致します。ユーザーインターフェースにストリーミングレスポンスを送信する場合、ストリームは最後のトークンが届くまで同時実行スロットを占有することに注意してください。低速なクライアントが長い回答を読み取っている間、スロットを占有し続けます。X-RateLimit-Limit-RequestsおよびX-RateLimit-Limit-Concurrencyヘッダーを読むことで、コードは使用しているキーに応じて適応できます。
コンテキスト、メモリ、および実行コスト
ループの各ステップで完全な会話記録が再送信されます。これがチャットAPIの動作原理であり、ツール呼び出しごとに入力トークンが増加することを意味します。プロンプトが2,000トークンから始まり、ステップごとに1,000トークン増加し、ステップごとに300出力トークンを持つ6ステップの実行を考えます。
- 入力トークン:2,000 + 3,000 + 4,000 + 5,000 + 6,000 + 7,000 = 27,000
- 出力トークン:6 x 300 = 1,800
- 入力コスト:27,000 x 0.15 / 1,000,000 = $0.00405
- 出力コスト:1,800 x 0.50 / 1,000,000 = $0.0009
- 合計:1回の実行あたり$0.00495
1,000回のこのような実行で$4.95です。これはエージェントが複数のステップで思考させるのに十分な安さですが、増加傾向には注意が必要です。100,000トークンの空きがある場合、長時間実行されるエージェントは最終的にウィンドウを埋め尽くし、その大きなプロンプトの入力コストはステップごとに100,000 x 0.15 / 1,000,000 = $0.015になります。
制御下に保つための3つの習慣があります。ツール結果を会話記録に挿入する前に切り捨てる(例:ウェブページの最初の2,000文字)。履歴が閾値を超えたら、古いステップを1つの短いメッセージに要約する。そして、会話自体をメモリとして頼るのではなく、永続的な事実を独自のデータベースに保存する。
各レスポンスのX-Balance-USDヘッダーには残高が表示されるため、エージェントのスーパーバイザーは残高が下限を下回った時点で実行を停止できます。クレジットは$20から前払いされ、期限はありません。チャージボーナスについては価格ページをご覧ください。
計画のための現実的な制限
どのモデルベースのエージェントにもガードレールが必要であり、これも例外ではありません。以下の点に備えてください。
- 不正な引数。 モデルは有効なJSONではない、または必須フィールドが欠落したツール引数を生成する可能性があります。防御的に解析し、エラーをツール結果として返してください。
- 誤ったツールの選択。 短く明確なツール説明を書いてください。2つのツールが似ている場合、モデルはそれらを混同します。フローが特定の呼び出しを必要とする場合は、
tool_choiceを使用して特定の呼び出しを強制してください。 - テキストのみ。 画像の入力・出力、音声、埋め込み、ファインチューニングはありません。それらの部分は別で行い、結果をテキストとして渡してください。
- 単一モデル。 エンドポイントの背後には1つのオープンウェイトモデルがあり、ベンダー間のルーターではありません。簡単なステップ用に小さなモデルを選択することはできません。
- 破壊的なツール。 エージェントに削除や支払いツールを与える場合は、独自のコードで確認ステップを行ってください。
プランニングエージェントは第2パスからも恩恵を受けます。ループが回答を返した後、モデルにツール結果を確認させ、JSON modeを使用して判断と支持できない主張のリストを返すような、もう1回の安価な呼び出しを行うことができます。これにより数百トークンが追加され、最も一般的な失敗、つまりツールが返したものを無視した自信に満ちた回答が検出されます。
最後に、すべてのステップをログに記録してください。メッセージ、ツール引数、および各レスポンスのX-Request-Idヘッダーを保存します。実行が失敗した場合、リクエストIDで正確な呼び出しを特定でき、ログに記録された会話記録でどのツール結果がモデルを誤解させたかがわかります。エージェントは、失敗した実行を再生して一度に1つずつ変更できる場合に、改善が最も容易になります。
コミットする前にトライアルでエージェントをテストしてください。新規ユーザーは$0.50のクレジットを取得でき、上記の6ステップ実行では約101回の完全な実行をカバーします(0.50 / 0.00495)。トライアルの同時リクエスト2を念頭に置き、エージェントを1つずつ実行してください。サービスのより広い概要については、トークンごとの料金概要をお読みください。プロンプトはトレーニングには使用されません。
その他のガイド
質問と回答
APIはエージェントのツール呼び出しをサポートしていますか?
はい。ツールとtool_choiceを受け付け、ストリーミング時を含むtool_callsを返し、結果をrole toolのメッセージとして受け取ります。
エージェント呼び出しは同時にいくつ実行できますか?
フルキーでは8つの同時リクエストと1分あたり300リクエストが可能です。トライアルキーでは2つの同時リクエストと1分あたり60リクエストが可能です。
429エラーが発生した場合、エージェントはどうすべきですか?
Retry-Afterの値を待つか、指定がない場合は数秒待ってから再試行してください。拒否されたリクエストは課金されません。
エージェントは画像や音声に対応できますか?
いいえ。このモデルはテキストのみに対応するため、他のメディアはお客様のツールで処理し、テキストとして渡す必要があります。
キーはフォーム 1 つで手に入ります
アカウントを作成し、キーをコピーし、ベースURLを変更します。これでセットアップは完了です。