HiveGate 0.3.1, released on October 31, is the first release on PyPI. You install it as a tool, write a starter config with one command, start Postgres and Qdrant, and serve. This post walks through that path from an empty directory to an AI agent REST API with per-user sessions, a paused tool call you approve over HTTP, and a cost record for every model call. It ends with what changes when you take it off your laptop.

HiveGate is an MIT-licensed FastAPI service built on Agno. You write the agent. HiveGate serves it. It is not a request-routing API gateway like Kong.

What you need

• Python 3.11 or newer, and uv or pipx
• Docker, for Postgres and Qdrant
• An API key for a model provider. The seeded demo agents use Gemini, so GOOGLE_API_KEY is the shortest path. OpenAI, Anthropic, xAI, Z.ai and DeepSeek keys also work.

Install

uv tool install hivegate-ai   # or: pipx install hivegate-ai

The package is hivegate-ai because PyPI refused hivegate as too similar to an existing project. The command is still hivegate.

Install it as a tool rather than into a project's virtual environment. The package's top-level modules have generic names (api, agents, db), and they can clash with other libraries in a shared environment. uv tool and pipx give it an environment of its own.

Write the config

mkdir my-agents && cd my-agents
hivegate init

init writes four files: compose.yaml, .env, db/migrations/setup.sql and sql/sample_data.sql. The .env is not a copy of the example file. Three values are filled in for a first local run:

• AUTH_DISABLED=true, so you can call /v2 without an API key while the server only listens on your machine.
• ADMIN_SECRET, set to a random 32-byte value instead of the placeholder.
• SECRET_TOKEN_ENC_KEY, a fresh Fernet key. HiveGate encrypts the per-user OAuth tokens it stores with this key, so keep it with your data.

Running init again refuses to overwrite anything. With --force it rewrites the compose files but still keeps an existing .env, because that file holds your API keys and the key your stored tokens are encrypted with.

Open .env and set your model key:

GOOGLE_API_KEY=...

Start the stack

docker compose up -d   # Postgres + Qdrant, seeds demo agents
hivegate serve         # http://127.0.0.1:8000/docs

Compose starts Postgres and Qdrant, creates the schema and seeds a handful of demo agents and teams. Since 0.3.1 it publishes their ports on 127.0.0.1 only, so the databases aren't reachable from your network by accident.

One known wart: docker compose ps reports Qdrant as unhealthy even though it works. The healthcheck calls curl, which the Qdrant image doesn't have, so docker compose up -d --wait fails too. That's #135, a good first issue if you want to fix it.

hivegate serve loads .env from the current directory and starts the API on 127.0.0.1:8000. If no model key is set, it starts anyway and prints a warning, because agents can't answer without one. The interactive OpenAPI docs are at /docs.

First calls

Check that it's up, then list the agents:

curl http://localhost:8000/health
curl http://localhost:8000/v2/agents

You'll see the seeded agents, including demo-assistant. Chat with it:

curl -X POST http://localhost:8000/v2/agents/demo-assistant/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is the capital of France?",
    "stream": false,
    "user_id": "user-1",
    "session_id": "session-1",
    "timezone": "UTC",
    "locale": "en-US"
  }'

The response carries the answer and the identifiers you'll use later:

{
  "content": "The capital of France is Paris.",
  "agent_id": "demo-assistant",
  "session_id": "session-1",
  "model": "gemini-3-flash-preview",
  "status": "completed",
  "run_id": "run-f47ac10b",
  "tools": []
}

Leave out "stream": false and you get server-sent events instead, which is what a chat UI wants.

Every chat names a user_id and a session_id. Send another message with the same pair and the agent sees the earlier turns, because history lives in Postgres, not in the process. Use a different user_id and that user gets their own sessions and memory. Nothing in your agent code has to track who is who.

Agents are data

The demo agents came from SQL, but you create your own over the same API. An agent is an id, a name and a prompt template, plus optional settings for memory, history and reasoning:

curl -X POST http://localhost:8000/v2/agents \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-first-agent",
    "name": "My First Agent",
    "template": "You are a helpful assistant that answers questions concisely.",
    "description": "A simple Q&A agent",
    "tags": ["qa", "general"]
  }'

It's available at /v2/agents/my-first-agent/chat straight away, with no redeploy. Changing a prompt is an API call, not a release. The agents API docs list every field.

A tool call that waits for a person

Letting an agent search an inbox is low risk. Letting it send an email is not. HiveGate's built-in Google and Microsoft toolkits mark every write as requires_confirmation: send_email, trash_email, schedule_meeting and the rest. Your own Agno toolkits opt in with requires_confirmation_tools=[...].

When the model calls one of those tools, the run stops before the tool executes, and the chat response says so:

{
  "content": null,
  "status": "PAUSED",
  "run_id": "run-f47ac10b",
  "tools": [
    {
      "tool_call_id": "tc-001",
      "tool_name": "send_email",
      "requires_confirmation": true,
      "tool_args": {"to": "jane@acme.com", "subject": "Password Reset"}
    }
  ]
}

Nothing has been sent yet. Show the pending call wherever your users are, then send the decision back. The reviewer can edit the arguments, not only say yes or no:

curl -X POST http://localhost:8000/v2/agents/my-first-agent/chat/commit \
  -H "Content-Type: application/json" \
  -d '{
    "run_id": "run-f47ac10b",
    "stream": false,
    "user_id": "user-1",
    "session_id": "session-1",
    "updated_tools": [
      {
        "tool_call_id": "tc-001",
        "confirmed": true,
        "tool_args": {"to": "jane@acme.com", "subject": "Password Reset Instructions"}
      }
    ]
  }'

Set "confirmed": false and the run ends with status: "cancelled" without calling the tool. Since 0.3.1 the same works for team runs, which used to pause and then couldn't be committed (#116).

Two limits to know. Paused runs live in the server's memory, so a restart or a request that lands on another replica gets 410 Gone. Run a single replica, or route each session to the same instance, when you use approvals. And tools from MCP servers don't have an approval gate yet; that's roadmap item #72. The human approval post covers the flow in depth.

What did that cost?

Every model call is metered: input, output, cache-read and cache-write tokens, and the USD cost from a versioned price table. The read-only /usage API groups it by agent, user, tenant, model, API key or status:

curl "http://localhost:8000/usage/summary?window=24h&group_by=user"
curl "http://localhost:8000/usage/calls?order=cost&limit=10"

/usage/calls returns the most expensive calls first, with session and run ids, so you can find the conversation behind a spike. With a Claude model, prompt caching is on by default in 0.3.1, and the cache-read tokens show up in the same records. The token cost post shows the queries behind a per-user cost report.

Off your laptop

AUTH_DISABLED=true is only acceptable while nothing else can reach the server, and hivegate serve enforces that. Ask it to listen on another host with auth off and it refuses:

$ hivegate serve --host 0.0.0.0
Refusing to serve on 0.0.0.0 with AUTH_DISABLED on: every route would be open. Remove it from .env.

It refuses the placeholder ADMIN_SECRET the same way. Remove AUTH_DISABLED from .env, restart, and create an API key with the admin secret init generated:

curl -X POST http://localhost:8000/admin/api-keys \
  -H "X-Admin-Secret: $ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name": "Frontend", "owner_id": "team-frontend", "scopes": ["agents:read", "agents:chat"]}'

The raw key (agk_...) is returned once and stored as a SHA-256 hash. Send it as X-API-Key on every /v2 call. For the cost dashboard, a key with only the usage:read scope can read /usage and nothing else. The authentication docs have the details.

For a hosted deployment you don't need the package at all. The prebuilt image deploys in one click to Railway, Render or Koyeb from the deploy page, and the deployment docs cover a production setup of your own.

Upgrading

uv tool upgrade hivegate-ai
hivegate migrate

migrate reads .env from the current directory and applies any database changes the new version ships. Coming from a clone of 0.3.0, apply db/migrations/011_token_usage_cost.sql (it adds the metering columns), and note that compose.yaml now reads DB_PASS and DB_DATABASE instead of DB_PASSWORD and DB_NAME.

What else is in 0.3.1

Everything merged since 0.3.0 on September 29:

• Per-call token cost metering and the /usage API (#109)
• Prompt caching for Claude models (#110)
• Approvable paused team runs (#116)
• error_code: "provider_billing" and a plain message when a provider account is out of credits, instead of the provider's raw error (#125)
• A warning that names the server when an MCP server with an unsupported transport is dropped, instead of the agent silently getting fewer tools (#146, from first-time contributor @coughlmao)
• Dependency upgrades that clear the open security advisories (#134)

The full list is in the changelog.

When you don't need HiveGate

Agno ships its own AgentOS, which serves agents defined in code over HTTP with sessions, human approval, RBAC and tracing. If your agents live in your codebase and AgentOS covers what you need, use AgentOS. It's maintained by the Agno team and tracks Agno releases.

HiveGate is for the case where agents and prompts are data you change over an API, each of your users connects their own Google or Microsoft account, approvals happen in your product over REST, and you need to know what each user cost you.

Try it

uv tool install hivegate-ai
mkdir my-agents && cd my-agents && hivegate init
# set GOOGLE_API_KEY in .env
docker compose up -d && hivegate serve

Then open http://127.0.0.1:8000/docs. The quickstart and the rest of the docs go from there, and issues and questions are welcome on GitHub.

If this is useful, a star helps other people find the project: ⭐ github.com/hivegate-ai/hivegate.

An agent turn is rarely one model call. The model reads the tools and the system prompt, calls a tool, reads the result, calls another tool, and only then answers. Every one of those round trips re-sends everything before it. A support agent that looks harmless in testing can cost far more for the user who keeps it busy all day, and a run that fails after three round trips is still billed.

Your provider's dashboard shows one number per API key. It doesn't know which of your users, tenants or agents spent it. If you want to bill, cap or simply understand that spend, you need the cost of each call recorded next to who made it.

This post shows how that works in HiveGate, an open-source FastAPI service for Agno agents: what gets recorded, how to query it, how prices are applied, and how Claude prompt caching changes the numbers. Both features landed on main this month (#109 and #110). They are not in a tagged release yet; the latest is v0.3.0.

First: you may already have this

If every model call already goes through an LLM proxy or an observability tool that prices calls, such as LiteLLM, Langfuse or Helicone, you have per-call cost data. Tag those calls with your user and tenant ids and you may not need anything else.

HiveGate's meter is for the case where the agents run inside HiveGate and you want the cost in the same Postgres database as the sessions, keyed by the same user_id, session_id and tenant_id, without running another service.

What gets recorded

Every chat, commit, MCP and team run writes one row to the token_usage table. That includes streamed and non-streamed runs, and also runs that failed, were refused, or were abandoned when the client hung up. A row has:

• Who: agent_id, user_id, session_id, run_id, tenant_id, and the api_key_name that made the request.
• Tokens: prompt_tokens, completion_tokens, cache_read_tokens, cache_write_tokens and reasoning_tokens.
• Work: model_requests (round trips), tool_calls, duration_ms and ttft_ms (time to first token).
• Money: cost_usd, the prices_version it was priced with, and unpriced_models for anything the price table doesn't know.
• Outcome: status, one of completed, paused, cancelled, error or refused, plus the error text, which stays server-side.
• Breakdown: a JSONB breakdown that splits the cost per model type, so the main model, the memory model and the compression model are each priced at their own rate.

tenant_id comes from the request's tenant_profile.tenant_id, or from user_profile.tenant_id if there's no tenant profile. Send it on every chat request and you can group by tenant later.

Failed runs are recorded with their real tokens on purpose. A run that errors after the model was called is still billed by the provider, and a client retrying such a run in a loop can spend a lot without anyone noticing. A run that pauses for human approval is recorded as paused, and the resumed part gets its own row when it's committed.

Recording runs off the event loop in a thread pool with its own database session, and it never fails the caller's request. If the write fails, the error is logged and the user still gets their answer.

The cost of a single call

A non-streaming chat response carries the usage of that call in token_usage (trimmed):

{
  "status": "completed",
  "content": "Your order shipped on Tuesday.",
  "token_usage": {
    "input_tokens": 412,
    "output_tokens": 86,
    "cache_read_tokens": 8240,
    "cache_write_tokens": 388,
    "reasoning_tokens": 0,
    "model_requests": 2,
    "model": "claude-sonnet-5-5",
    "cost_usd": 0.004302,
    "unpriced_models": null,
    "status": "completed"
  }
}

The numbers above are an example, not a measurement, but the fields are the real ones. That's enough to show a running total in your own UI, or to stop a session when it crosses a budget you set.

A key that can read usage and nothing else

The /usage endpoints accept an API key with the usage:read scope (or admin), or the X-Admin-Secret header. Create a key for your dashboard with the admin API (see API keys in the admin docs):

curl -X POST http://localhost:8000/admin/api-keys \
  -H "X-Admin-Secret: $ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name": "usage-dashboard", "owner_id": "finance", "scopes": ["usage:read"]}'

The raw key is in the api_key field of the response, and it's shown only once. A key whose only scope is usage:read is refused on every /v2 route with a 403, so a key you hand to a dashboard can't call agents and spend tokens.

Which users cost the most

GET /usage/summary returns the totals for a window and a breakdown by one dimension. window is one of 1h, 6h, 24h, 7d or 30d, and group_by is one of agent, tenant, model, api_key, user or status:

curl -H "X-API-Key: $USAGE_KEY" \
  "http://localhost:8000/usage/summary?window=7d&group_by=user"

Each group, and the totals, has calls, cost_usd, input_tokens, output_tokens, cache_read_tokens, cache_write_tokens, reasoning_tokens, model_requests, failed_calls and failed_cost_usd. Groups are sorted by cost, most expensive first. The response also has model_types, the cost split between the main model and helper models such as the memory model, which is where unexpected spend often hides.

Swap group_by=user for tenant to see the cost per customer, or for status to see how much you paid for runs that failed.

The most expensive calls

GET /usage/calls lists individual calls, the most expensive first by default:

curl -H "X-API-Key: $USAGE_KEY" \
  "http://localhost:8000/usage/calls?window=24h&tenant=acme&min_cost=0.05&limit=20"

You can filter by agent, tenant, status and min_cost, and set order=recent to get the newest first. Every call carries its session_id and run_id, so you can open the conversation that produced it and see why it took twelve round trips.

Two more endpoints cover dashboards:

• GET /usage/timeseries?window=7d&bucket=1d&group_by=agent returns the cost per time bucket for the top groups by cost (8 by default, top goes up to 20). The rest are folded into (other) so a chart stays readable.
• GET /usage/live?after_id=0 returns the latest calls, oldest first. Poll it again with the last_id from the response to get only what's new.

How prices are applied

Costs come from the price table in agents/pricing.py, in USD per million tokens, for Anthropic, Gemini and OpenAI models. GET /usage/prices returns the table that's in use.

Providers count tokens differently, and the meter follows each convention. Anthropic reports cache reads and writes separately from input_tokens. Gemini and OpenAI include cached tokens inside input_tokens, so the meter subtracts them before applying the full input price. Gemini reports thinking tokens separately and bills them at the output rate.

A model that isn't in the table is never guessed. Its calls are stored with cost_usd set to null and the model listed in unpriced_models. The summary counts those in unpriced_calls and partially_priced_calls. When either is above zero, read cost_usd as a lower bound, not a total.

To add or correct a price without a redeploy, set PRICING_OVERRIDES:

PRICING_OVERRIDES='{"my-model": {"input": 5, "output": 25, "cache_read": 0.5, "cache_write": 6.25}}'

Prompt caching for Claude models

Each round trip of an agent re-sends the tools, the system prompt and the whole conversation so far. Without caching, all of that bills at the full input price every time. The PR that turned caching on (#110) notes that on our own deployment, 0% of input tokens had been cached across all agents in the previous 30 days, and one agent was sending about 50K input tokens per run.

Claude models in HiveGate now run with two cache breakpoints, set in agents/model_factory.py:

ANTHROPIC_PROMPT_CACHING: dict[str, Any] = {
    "cache_system_prompt": True,
    "request_params": {"cache_control": {"type": "ephemeral"}},
}

• cache_system_prompt marks the system prompt. Tools render before it, so the tools and the system prompt are cached together. HiveGate passes a fixed system message per agent, so that prefix is shared by every run of the agent, across users.
• The top-level cache_control is Anthropic's automatic caching. It marks the last block and moves forward as the conversation grows, so each tool-loop round trip and each follow-up turn reads everything before it from cache.

There's nothing to configure. Both breakpoints use the 5-minute TTL, and each read refreshes it. A prompt shorter than the model's minimum cacheable length (1024 tokens on Sonnet 4.6, 4096 on Haiku 4.5) is simply sent uncached, with no error.

What caching does to the bill

Cache reads bill at a fraction of the input price, and cache writes at 1.25x. For claude-sonnet-5-5, the price table has $2 per million input tokens, $0.20 for cache reads and $2.50 for cache writes.

Take an agent whose tools and system prompt add up to 10,000 tokens, and a turn with four round trips. Counting only that prefix:

• Uncached: 4 × 10,000 tokens × $2/M = $0.080.
• Cached: one write, 10,000 × $2.50/M = $0.025, then three reads, 3 × 10,000 × $0.20/M = $0.006. Total $0.031.

That's arithmetic from the price table, not a benchmark. The conversation part grows with every round trip and is cached the same way, so long tool loops gain the most. The cache lives for five minutes after its last read: an agent nobody has used for longer pays the write again, and so does a conversation that sat idle.

You don't have to trust the arithmetic. The meter records cache_read_tokens and cache_write_tokens for every call, so /usage/summary?group_by=agent shows, per agent, how much of the input came from cache and what it cost.

Upgrading an existing database

On a fresh install, HiveGate creates the token_usage table with all the columns on startup. An existing database needs the new columns from db/migrations/011_token_usage_cost.sql. Every statement is ADD COLUMN IF NOT EXISTS, and existing rows keep working:

psql "$DATABASE_URL" -f db/migrations/011_token_usage_cost.sql

For history from before the meter existed, scripts/usage_from_runs.py builds a read-only per-agent cost report from Agno's stored runs.

Try it

• Deploy HiveGate from the deploy page, or run it locally from main. Create a usage:read key, send a few chat requests with a user_id and a tenant_profile, and call /usage/summary?group_by=user.
• The meter is in api/services/usage.py, the queries in db/usage_queries.py and the prices in agents/pricing.py, all in the GitHub repo. The Agno deploy post covers sessions, API keys and streaming.

If this is useful, a star helps other people find the project: ⭐ github.com/hivegate-ai/hivegate.

Letting an agent search an inbox is low risk. Letting it send an email, cancel a meeting or permanently delete a message is not. A wrong recipient or a hallucinated date becomes a real-world mistake. The usual answer is human-in-the-loop: the agent proposes the call, a person reviews it, and only then does it run.

This post shows how that works in HiveGate, an open-source FastAPI service for Agno agents. The run pauses, your app gets the proposed call, and a second request approves, edits or denies it.

Which tools pause

Agno lets a toolkit mark tools as requires_confirmation. When the model calls one, Agno stops the run before executing it. HiveGate's built-in toolkits mark every write:

• Email: send_email, create_draft, send_draft, trash_email, delete_email_permanently, modify_labels
• Calendar: schedule_meeting, schedule_meeting_find_time, cancel_meeting
• Contacts: create_contact, update_contact, delete_contact
• Drive: read_file
• Workers: run_claude_code, run_managed_agent

Read-only tools such as search_emails and list_events run without a pause. Your own Agno toolkits opt in the same way, through requires_confirmation_tools=[...]. Tools from MCP servers don't have an approval gate yet. That's on the roadmap.

Step 1: the run pauses

A normal chat request:

curl -X POST http://localhost:8000/v2/agents/support-agent/chat \
  -H "X-API-Key: $HIVEGATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Email jordan@acme.example that the renewal call moves to Thursday 3pm.",
    "user_id": "user-1842",
    "session_id": "inbox-1",
    "timezone": "America/Chicago",
    "locale": "en-US",
    "stream": false,
    "user_profile": {
      "profile_id": "user-1842",
      "email": "dana@acme.example",
      "full_name": "Dana Lee",
      "role": "Account manager",
      "tenant_id": "acme"
    }
  }'

Instead of a finished answer, the response has status: "PAUSED", a run_id, and the pending call with its arguments (trimmed here):

{
  "agent_id": "support-agent",
  "session_id": "inbox-1",
  "status": "PAUSED",
  "run_id": "6f1c9a2e-...",
  "tools": [
    {
      "tool_call_id": "call_8Jx2...",
      "tool_name": "send_email",
      "requires_confirmation": true,
      "tool_args": {
        "to": ["jordan@acme.example"],
        "subject": "Renewal call moved to Thursday",
        "body_text": "Hi Jordan, the renewal call is now Thursday at 3pm CT. Thanks, Dana"
      },
      "result": null
    }
  ]
}

Nothing has been sent yet. With "stream": true, you get the same data as an SSE event whose event field is RunPaused, and then the stream ends.

Show tool_name and tool_args to the user, or to whoever reviews actions for them, in whatever form fits your app: a confirmation card, an editable form, a Slack message.

Step 2: approve, edit or deny

The decision goes to POST /v2/agents/{agent_id}/chat/commit with the run_id, the same user_id and session_id, and one entry per pending tool in updated_tools.

Approve as proposed:

curl -X POST http://localhost:8000/v2/agents/support-agent/chat/commit \
  -H "X-API-Key: $HIVEGATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "run_id": "6f1c9a2e-...",
    "user_id": "user-1842",
    "session_id": "inbox-1",
    "stream": false,
    "updated_tools": [
      {"tool_call_id": "call_8Jx2...", "confirmed": true}
    ]
  }'

The agent resumes, the email is sent through the user's own Gmail or Outlook account, and the response has the agent's final message, status: "completed" and the token usage for the resumed part.

Edit, then approve. The reviewer fixed the time, so send the corrected arguments with the approval. tool_args replaces the proposed arguments, so send the full set:

{"tool_call_id": "call_8Jx2...", "confirmed": true,
 "tool_args": {
   "to": ["jordan@acme.example"],
   "subject": "Renewal call moved to Thursday",
   "body_text": "Hi Jordan, the renewal call is now Thursday at 4pm CT. Thanks, Dana"
 },
 "confirmation_note": "Corrected time to 4pm"}

Deny:

{"tool_call_id": "call_8Jx2...", "confirmed": false, "confirmation_note": "Wrong recipient"}

If every pending tool is denied, HiveGate doesn't resume the run at all. It returns status: "cancelled" with the content "Tool execution cancelled by user.", and no model call is made. If you approve some tools and deny others, the run resumes: Agno executes the approved ones, skips the denied ones, and tells the model they were rejected.

The fields HiveGate accepts in each updated_tools entry are confirmed, tool_args (or args) and confirmation_note. Anything else is ignored.

The same thing from Python

A minimal backend helper, with the review step left to your UI:

import httpx

BASE = "http://localhost:8000/v2/agents/support-agent"
HEADERS = {"X-API-Key": HIVEGATE_KEY}

def chat(message: str, user: dict, session_id: str) -> dict:
    body = {
        "message": message,
        "user_id": user["profile_id"],
        "session_id": session_id,
        "timezone": "UTC",
        "locale": "en",
        "stream": False,
        "user_profile": user,
    }
    return httpx.post(f"{BASE}/chat", headers=HEADERS, json=body, timeout=120).json()

def decide(paused: dict, user: dict, decisions: list[dict]) -> dict:
    """decisions: one {"tool_call_id", "confirmed", optional "tool_args", "confirmation_note"} per pending tool."""
    body = {
        "run_id": paused["run_id"],
        "user_id": user["profile_id"],
        "session_id": paused["session_id"],
        "stream": False,
        "updated_tools": decisions,
    }
    response = httpx.post(f"{BASE}/chat/commit", headers=HEADERS, json=body, timeout=120)
    if response.status_code == 410:
        raise RuntimeError("Paused run is gone; ask the agent again.")
    response.raise_for_status()
    return response.json()

reply = chat("Cancel my 2pm with Jordan.", user, "inbox-1")
if reply["status"] == "PAUSED":
    pending = [t for t in reply["tools"] if t.get("requires_confirmation")]
    decisions = review_in_ui(pending)  # your code: returns approve/edit/deny per tool
    reply = decide(reply, user, decisions)
print(reply["content"])

If the chat request named a model, send the same model on commit. HiveGate uses it to find the paused agent.

Where paused runs live

A paused run is held in the memory of the HiveGate process that paused it, until it's committed. If the process restarts, or the commit lands on a different replica, commit returns 410 Gone ("Confirmation time window has elapsed"). Two practical consequences:

• Run a single replica, or route each session to the same instance, when you use approvals.
• Treat a 410 as "the proposal expired": ask the agent again rather than retrying the commit.

The conversation itself is stored in Postgres, so the user doesn't lose their history when a pending action expires.

The audit trail

Here is what HiveGate records about a decision:

• The run, in the agent's session. Agno stores each run in the agent's Postgres session table. A resumed run's tool executions carry the arguments that actually ran (including any edits), requires_confirmation, confirmed and the confirmation_note.
• The cost of the resumed run. The resumed part is metered like any other call: a row in token_usage with the user, session, API key name, number of tool calls, status and USD cost. You can list them with GET /usage/calls?agent=support-agent&order=recent, which needs a key with the usage:read scope.
• Logs. Every commit is logged with its run_id, and a fully denied run is logged as such. Set OTEL_TRACING_BACKEND=otlp and OTEL_LOGGING_BACKEND=otlp (Sentry and Logtail are also supported) to send traces and logs to your observability stack.

What it doesn't record is which person clicked approve. HiveGate sees the API key that made the commit, not your end user's identity. If you need that for compliance, record the reviewer and the decision in your own database before you call commit. You can also put the reviewer in confirmation_note, which is stored with the tool execution. A fully denied run is never resumed, so it leaves no usage row. Your own record and the log line are the trace for those.

A note on /v2/approvals

HiveGate also has an approvals inbox at /v2/approvals, used by the supervisor platform. GET /v2/approvals lists pending requests, and POST /v2/approvals/{job_id}/approve, /deny or /decide records a decision. It can push requests out through notification plugins (webhook, Slack, Telegram, Discord and WhatsApp are built in; GET /v2/approvals/plugins/list shows them). Those requests are also held in process memory. For the agent chat flow in this post, the commit call is what resumes the run.

Try it

• Deploy HiveGate from the deploy page. Create an agent tagged available_tools:email, store a test Gmail token for one user (see the OAuth post), and ask the agent to email you. The run will pause.
• The commit endpoint is in api/routes/v2/agents.py and the Agno resume logic is in agents/hitl.py in the GitHub repo.

If this is useful, a star helps other people find the project: ⭐ github.com/hivegate-ai/hivegate.