Managed Inference and Agents アドオンでの Heroku ツールの使用

この記事の英語版に更新があります。ご覧の翻訳には含まれていない変更点があるかもしれません。

最終更新日 2025年08月20日(水)

Heroku Managed Inference and Agent アドオンは、基本的な推論の域を超えて機能を拡張し、厳選された対応ツールセットを自動で実行します。

これらのツールを使用すると、PDF の読み取り、Heroku データベースとのやり取り、LLM で作成されたコードの実行、Heroku にすでにデプロイされているカスタムコードとの統合などを行えるエージェントワークフローを作成できるようになります。

Heroku ツールは v1/agents/heroku API と互換性があります。Managed Inference アドオンが、LLM から送信された、tools オブジェクト経由での呼び出しを許可されている認識済みのツール (type="heroku_tool"​) を呼び出すリクエストを処理すると、エージェントエンドポイントがそのツールを自動的に実行します。

この記事に記載されているツールでは、簡略化された表記法を使用して詳細を指定します。アドオンは、入力パラメータ、説明、その他のメタデータなど、必要なすべての情報を各ツールの API リクエストに自動で追加します。この抽象化により、LLM は追加の構成を必要とせずに、必要なすべてのツールの詳細にアクセスできるようになります。

target_app_name​ パラメータを受け付けるツールの場合は、対象のアプリに Managed Inference and Agents アドオンがアタッチされていることを確認してください。アドオンをアタッチすると、対象のアプリ内で One-off dyno を起動する権限がアドオンに付与されます。

Heroku ツール: dyno_run_command

dyno_run_command​ ツールを使用すると、エージェントはデプロイされた Heroku アプリで事前に指定されたコマンドを実行できるようになります。このツールにより、既存のコードを LLM で使用できるようになります。実行するエントリポイントの cmd​ コマンドを指定するとともに、関数が行う処理を説明する description​ と、期待される parameters​ も提供する必要があります。

例:

curl $INFERENCE_URL/v1/agents/heroku \
-H "Authorization: Bearer $INFERENCE_KEY" \
-d @- <<EOF
{
  "model": "$INFERENCE_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "Hey what time is it?"
    }
  ],
  "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

Heroku ツール: postgres_get_schema

postgres_get_schema​ ツールを使用すると、LLM がアプリにアタッチされた Heroku Postgres データベース​のスキーマをクエリできるようになります。このツールは One-off dyno を起動して指定されたデータベースのパブリックスキーマを調査し、LLM がその構造を理解できるようにします。

任意でエイリアスを使用してデータベースアタッチメント名を指定できます。エイリアスを指定しない場合、ツールはデフォルトで DATABASE​ を使用します。これは、Heroku Postgres アドオンの標準エイリアスです。

すべてのデータベースツールについて、現在許可されているのはフォロワーデータベース​のみです。フォロワーデータベースはデフォルトで読み取り専用であるため、LLM がデータを変更することはできません。フォロワーデータベースを作成する方法についてはこちら​を参照してください。

例:

curl $INFERENCE_URL/v1/agents/heroku \
-H "Authorization: Bearer $INFERENCE_KEY" \
-d @- <<EOF
{
  "model": "$INFERENCE_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "Hi, can you tell me about my database's schema?"
    }
  ],
  "tools": [
    {
        "type": "heroku_tool",
        "name": "postgres_get_schema",
        "runtime_params": {
            "target_app_name": "$APP_NAME",
            "dyno_size": "basic",
            "tool_params": {
                "db_attachment": "$DATABASE_URL"
            }
        }
    }
  ]
}
EOF

Heroku ツール: postgres_run_query

postgres_run_query​ ツールは、target_app_name​ Heroku アプリ内で One-off dyno を起動し、その後 db_attachment​ で指定されたデータベースに対して SQL クエリを実行します。

すべてのデータベースツールについて、現在許可されているのはフォロワーデータベース​のみです。フォロワーデータベースはデフォルトで読み取り専用であるため、LLM がデータを変更することはできません。フォロワーデータベースを作成する方法についてはこちら​を参照してください。

例:

curl $INFERENCE_URL/v1/agents/heroku \
-H "Authorization: Bearer $INFERENCE_KEY" \
-d @- <<EOF
{
  "model": "$INFERENCE_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "Hi - how many users were created in the last month?"
    }
  ],
  "tools": [
    {
        "type": "heroku_tool",
        "name": "postgres_run_query",
        "runtime_params": {
            "target_app_name": "$APP_NAME",
            "dyno_size": "basic",
            "tool_params": {
                "db_attachment": "$DATABASE_URL"
            }
        }
    }
  ]
}
EOF

Heroku ツール: code_exec_*

code_exec_*​ ツールを使用すると、エージェントが自ら生成したコードを実行できるようになります。またこのツールは、コードを実行する前にパッケージや依存関係をインストールする機能も備えています。

コードの実行中にエラーが発生した場合、エージェントはエラーメッセージを読み取り、コードまたは依存関係を調整して自動的に再試行します。

現在は code_exec_go​、code_exec_node​、code_exec_python​、code_exec_ruby​ の 4 つのプログラミング言語がサポートされています。

例:

curl $INFERENCE_URL/v1/agents/heroku \
-H "Authorization: Bearer $INFERENCE_KEY" \
-d @- <<EOF
{
  "model": "$INFERENCE_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "Hi - what is the sha256 of the string 'FOOBAR'?"
    }
  ],
  "tools": [
    {
        "type": "heroku_tool",
        "name": "code_exec_ruby",
        "runtime_params": {}
    }
  ]
}
EOF

Heroku ツール: html_to_markdown

html_to_markdown​ ツールは URL から HTML を取得し、それをマークダウンに変換して LLM に返します。

例:

curl $INFERENCE_URL/v1/agents/heroku \
-H "Authorization: Bearer $INFERENCE_KEY" \
-d @- <<EOF
{
  "model": "$INFERENCE_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "Hey summarize this webpage for me: https://example.com"
    }
  ],
  "tools": [
    {
      "type": "heroku_tool",
      "name": "html_to_markdown",
      "runtime_params": {}
    }
  ]
}
EOF

Heroku ツール: pdf_to_markdown

pdf_to_markdown​ ツールは URL から PDF を取得し、それをマークダウンに変換して LLM に返します。

例:

curl $INFERENCE_URL/v1/agents/heroku \
-H "Authorization: Bearer $INFERENCE_KEY" \
-d @- <<EOF
{
  "model": "$INFERENCE_MODEL_ID",
  "messages": [
    {
      "role": "user",
      "content": "Hey summarize this PDF for me: https://www.melbpc.org.au/wp-content/uploads/2017/10/small-example-pdf-file.pdf"
    }
  ],
  "tools": [
    {
      "type": "heroku_tool",
      "name": "pdf_to_markdown",
      "runtime_params": {}
    }
  ]
}
EOF