最終更新日 2025年09月04日(木)

/v1/agents/heroku​ エンドポイントを使用すると、メッセージに基づいてツールを自律的に呼び出すことができる大規模言語モデル (LLM) を搭載したエージェントシステムとやり取りできます。/chat/completions​ とは異なり、単一のモデル応答を生成する v1/agents/heroku​ エンドポイントは、自動ツール実行とマルチステップワークフローをサポートします。

リクエストボディパラメータ

以下のパラメータを使用して、エージェントの動作とエージェントが使用できるツールを管理します。

必須パラメータ

任意のパラメータ

オブジェクトの tools 配列

配列内の各ツールを使用すると、エージェントがユーザーに代わってアクションを呼び出すことができます。Heroku は One-off dyno を介してツール呼び出しを自動的に実行します。現在、/v1/agents/heroku​ エンドポイントは以下の 2 種類のツールをサポートしています。

• heroku_tool: Heroku Managed Inference and Agents がネイティブにサポートするファーストパーティツール
• MCP ツール: Heroku にデプロイするカスタム MCP​ ツール。モデルに呼び出されると Heroku によって自動的に実行されます。独自のカスタム MCP ツールを Heroku にデプロイする方法の詳細は、Heroku MCP ツール​に関する記事を参照してください。

ランタイムパラメータ

v1/agents/heroku​ エンドポイントは、実行時に指定された mcp​ または heroku_tool​ ツールに特定の設定を渡します。モデルは設定を変更できません。

• mcp​ タイプのツールでは ttl_seconds​、max_calls​、dyno_size​ を任意で指定できます。他のパラメータはサポートされていません。
• heroku_tool​ タイプのツールでは、ツール自体に応じて特定のパラメータが必要になるか、または許可されます。詳細は、ツール固有のドキュメント​を参照してください。

オブジェクトの messages 配列

messages​ オブジェクトはメッセージオブジェクトの配列です。

各メッセージはメッセージのスキーマを決定する role​ フィールドを指定する必要があります。現在サポートされているタイプは、user​、assistant​、system​、tool​ です。

role=user メッセージ

user​ メッセージは、モデルにクエリを送信し、応答を促す主な方法です。

role=assistant メッセージ

通常、モデルは assistant​ メッセージのみ生成します。ただし、部分的に完了した assistant​ 応答を作成または事前入力して、モデルが次のターンに生成するコンテンツに影響を与えることができます。

ツール呼び出しオブジェクト

特定のツールを実行するモデルのリクエストを表します。

​ツール呼び出しの例

"tool_calls": [
  {
    "id": "tooluse_abc123",
    "type": "function",
    "function": {
      "name": "dyno_run_command",
      "arguments": "{}"
    }
  }
]

関数オブジェクト

role=system メッセージ

system​ メッセージは、モデルの応答をガイドするためにモデルに与えられる特別なプロンプトです。

role=tool メッセージ

指定されたツールの出力を表す tool​ メッセージオブジェクト。

リクエストヘッダー

すべての /v1/agents/heroku​ リクエストには以下のヘッダーを含める必要があります。

-H "Authorization: Bearer $INFERENCE_KEY"

応答形式

エージェント応答は、Server-Sent Events (SSE) を介してストリームで返されます。各 event: message​ には完了を表す JSON ペイロードが含まれます。最後のイベントはデータ [DONE]​ を使用した event: done​ です。

完了オブジェクト

選択オブジェクト

使用量オブジェクト

リクエストの例

 curl --location $INFERENCE_URL/v1/agents/heroku \
  --header 'Content-Type: application/json' \
  --header "Authorization: Bearer $INFERENCE_KEY" \
  --data @- <<EOF
{
  "model": "$INFERENCE_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "What is the current time and date?"
    }
  ],
  "tools": [
    {
      "type": "heroku_tool",
      "name": "dyno_run_command",
      "runtime_params": {
        "target_app_name": "$APP_NAME",
        "tool_params": {
          "cmd": "echo hello && date",
          "description": "Runs `echo hello && date` on one-off dyno.",
          "parameters": {
            "type": "object",
            "properties": {},
            "required": []
          }
        }
      }
    }
  ]
}
EOF

応答の例

event:message
data:{"id":"chatcmpl-18441121a827937e07e20","object":"chat.completion","created":1748541400,"model":"claude-4-sonnet","system_fingerprint":"heroku-inf-1sefyj8","choices":[{"index":0,"message":{"role":"assistant","content":"I'll run the command to get the current time and date for you.","refusal":null,"tool_calls":[{"id":"tooluse_mo8vfAMhRqm3ypFIoCTmng","type":"function","function":{"name":"dyno_run_command","arguments":"{}"}}]},"finish_reason":"tool_calls"}],"usage":{"prompt_tokens":397,"completion_tokens":55,"total_tokens":452}}

event:message
data:{"id":"chatcmpl-18441121a827937e07e20","object":"tool.completion","created":1748541402,"system_fingerprint":"heroku-inf-1sefyj8","choices":[{"index":0,"message":{"role":"tool","content":"Tool 'dyno_run_command' returned result: hello\nThu May 29 05:56:42 PM UTC 2025","refusal":null,"tool_call_id":"tooluse_mo8vfAMhRqm3ypFIoCTmng","name":"dyno_run_command"},"finish_reason":""}],"usage":{}}

event:message
data:{"id":"chatcmpl-18441121a827937e07e20","object":"chat.completion","created":1748541407,"model":"claude-4-sonnet","system_fingerprint":"heroku-inf-1sefyj8","choices":[{"index":0,"message":{"role":"assistant","content":"Based on the command output, the current time and date is:\n\n**Thursday, May 29, 2025 at 5:56:42 PM UTC**","refusal":null},"finish_reason":"stop"}],"usage":{"prompt_tokens":500,"completion_tokens":40,"total_tokens":540}}

event:done
data:[DONE]