Last updated May 14, 2025

The Heroku Managed Inference and Agent add-on extends beyond basic inferencing by automatically executing a curated set of supported tools.

These tools let you create agentic workflows that can read PDFs, interact with Heroku databases, execute LLM-authored code, and integrate with custom code already deployed on Heroku.

Heroku tools are compatible with the v1/agents/heroku API. When the Managed Inference add-on processes a request made by an LLM to run a recognized tool (type="heroku_tool") that you allowed it to call via the tools object, the agents endpoint automatically runs that tool for you.

The tools listed in this article use a simplified notation to specify details. The add-on automatically augments each tool’s API requests with all required information, including input parameters, descriptions, and other metadata. This abstraction ensures the LLM has access to all necessary tool details without requiring additional configuration.

Heroku Tool: dyno_run_command

The dyno_run_command tool allows the agent to run pre-specified commands on a deployed Heroku app. You can use this to make existing code available for use by the LLM. You must specify the entrypoint cmd command to run, as well as provide a description of what your function does and the parameters it expects.

Example:

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 Tool: postgres_get_schema

The postgres_get_schema tool enables an LLM to query the schema of a Heroku Postgres database attached to your app. This tool spins up a one-off dyno to examine the public schema of the specified database, allowing the LLM to understand its structure.

Optionally, you can specify the database attachment name with the alias. If you don’t provide an alias, the tool defaults to DATABASE, which is the standard alias for Heroku Postgres add-ons.

Example:

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 Tool: postgres_run_query

The postgres_run_query tool spins up a one-off dyno within the target_app_name Heroku app, and then runs an SQL query against the database specified in the db_attachment.

Example:

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 Tool: code_exec_*

The code_exec_* tools allow the agent to run code authored by the agent. It also supports the installation of packages and dependencies before running code.

If the agent encounters an error running the code, it automatically retries by reading the error message and adjusting the code or dependencies.

We currently support four programming languages: code_exec_go, code_exec_node, code_exec_python, and code_exec_ruby.

Example:

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 Tool: html_to_markdown

The html_to_markdown tool fetches HTML from a URL, converts it to markdown, and delivers it back to the LLM.

Example:

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 Tool: pdf_to_markdown

The pdf_to_markdown tool fetches a PDF from a URL, converts it to markdown, and delivers it back to the LLM.

Example:

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