DEV Community: HiveGate

From BizGenie to HiveGate: where our agent runtime began

HiveGate — Tue, 10 Nov 2026 16:00:01 +0000

HiveGate wasn't written from scratch. It started in May 2025 from agent-api, Agno's template for serving agents with FastAPI and Postgres. It became the agent backend for a product called BizGenie, and later we opened it up and gave it a new name.

This post covers where it came from, which parts are still the ones we built for BizGenie, and what we use it for now. The part with code is the approval flow: a tool marked requires_confirmation, a run that comes back PAUSED, and the commit call that resumes it. That flow dates from October 2025 and works the same way in HiveGate 0.3.1.

What BizGenie asked of the backend

BizGenie was a B2B SaaS platform with two kinds of agents. Each employee got a personalized AI copilot, and there were shared, role-based experts on top.

That shape asks more of a backend than a single agent in a script does:

A personal copilot works for one person. When it reads mail or books a meeting, it has to do that in that person's account, with that person's credentials.
A shared expert is one agent with many users. Each conversation with it still belongs to one person, so sessions and history are per user.
An agent that can send email on someone's behalf needs a stop before it sends.

None of this is about the model. Agno already gave us the agent itself: model calls, tools, memory and teams. The work was everything around it, which is what HiveGate is today.

The timeline

May 2025: the backend starts from Agno's agent-api template.
June 2025: BizGenie's agents are added to it.
August 2025: the /v2 routes that HiveGate still serves.
October 2025: the Google and Microsoft workspace toolkits (mail, calendar, contacts, drive) and requires_confirmation on the tools that write.
End of 2025: open-source work begins.
September 2026: the project is renamed HiveGate.
October 31, 2026: 0.3.1, the first release on PyPI.

What carried over: approval before a write

Letting an agent search an inbox is low risk. Letting it send an email or delete a message is not. Agno lets a toolkit name the tools that need a person's confirmation, and when the model calls one, Agno stops the run before the tool executes.

This is how HiveGate's email toolkit declares its writes, in toolkits/email.py (trimmed):

Toolkit.__init__(
    self,
    name="EmailToolkit",
    tools=tools_list,
    requires_confirmation_tools=[
        "send_email",
        "create_draft",
        "send_draft",
        "trash_email",
        "delete_email_permanently",
        "modify_labels",
    ],
)

search_emails and list_drafts aren't on the list, so they run without a pause. The calendar, contacts and drive toolkits follow the same pattern, and so can your own:

from agno.tools import Toolkit

class MyServiceToolkit(Toolkit):
    def __init__(self, user_id: str, service_name: str, auth: bool = True):
        super().__init__(
            name="my_service_toolkit",
            tools=[self.my_action if auth else self.auth_required],
            requires_confirmation_tools=["my_action"] if auth else [],
            stop_after_tool_call_tools=([] if auth else ["auth_required"]),
        )
        self.user_id = user_id
        self.service_name = service_name

The run pauses

A chat request to an agent with the email toolkit:

curl -X POST http://localhost:8000/v2/agents/customer-support/chat \
  -H "X-API-Key: $HIVEGATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Send Jane the password reset instructions.",
    "stream": false,
    "user_id": "user-42",
    "session_id": "sess-abc123",
    "timezone": "America/New_York",
    "locale": "en-US"
  }'

When the model decides to call send_email, the response isn't a finished answer. It has status: "PAUSED", a run_id, and the proposed call with its arguments:

{
  "content": null,
  "agent_id": "customer-support",
  "session_id": "sess-abc123",
  "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"},
      "result": null
    }
  ]
}

Nothing has been sent yet. Your app shows tool_name and tool_args to the user in whatever form fits: a confirmation card, an editable form, a message in Slack.

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. Here the reviewer changed the subject before approving:

curl -X POST http://localhost:8000/v2/agents/customer-support/chat/commit \
  -H "X-API-Key: $HIVEGATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "run_id": "run-f47ac10b",
    "stream": false,
    "user_id": "user-42",
    "session_id": "sess-abc123",
    "updated_tools": [
      {
        "tool_call_id": "tc-001",
        "confirmed": true,
        "tool_args": {"to": "jane@acme.com", "subject": "Password Reset Instructions"},
        "confirmation_note": "Clearer subject"
      }
    ]
  }'

The run resumes, the email goes out through the user's own Gmail or Outlook account, and the response has the agent's final message. HiveGate copies only confirmed, tool_args (or args) and confirmation_note from each entry onto the paused call. Anything else is ignored.

Set "confirmed": false on every pending tool and the run doesn't resume at all. The response is status: "cancelled" with the content "Tool execution cancelled by user.", and no model call is made.

The same thing from a Python backend:

import httpx

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

def commit(paused: dict, user_id: str, decisions: list[dict]) -> dict:
    body = {
        "run_id": paused["run_id"],
        "user_id": user_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("The paused run is gone. Ask the agent again.")
    response.raise_for_status()
    return response.json()

The limits that came with it

Two things about this flow are worth knowing before you rely on it:

Paused runs live in process memory. If the process restarts, or the commit lands on another replica, commit returns 410 Gone ("Confirmation time window has elapsed"). Run a single replica, or route each session to the same instance, when you use approvals. The conversation itself is in Postgres, so the user keeps their history.
MCP tools have no approval gate yet. Tools from an MCP server run without a pause. That's #93 on the roadmap.

HiveGate also records the API key that made the commit, not the person who clicked approve. If you need the reviewer's identity, store it in your own database before you call commit, or put it in confirmation_note, which is saved with the tool execution.

What else carried over: each user's own accounts

The workspace toolkits from October 2025 are the other half of the copilot idea. An agent that books a meeting for a user does it in that user's Google or Microsoft calendar, not in a shared account.

Your app runs the OAuth consent and hands HiveGate the tokens:

curl -X POST http://localhost:8000/v2/users/user-42/tokens \
  -H "X-API-Key: $HIVEGATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "integration_key": "google_calendar",
    "provider": "google",
    "token_type": "oauth2",
    "token_data": {
      "access_token": "ya29.a0...",
      "refresh_token": "1//0g...",
      "expires_in": 3599,
      "client_id": "1234-abc.apps.googleusercontent.com",
      "client_secret": "GOCSPX-..."
    }
  }'

HiveGate encrypts the token data with Fernet before it's written, refreshes the access token when a tool asks for it close to expiry, and gives it to the tool at the moment it runs. The model never sees it. The per-user OAuth post has the details.

What HiveGate is now

Around that core, HiveGate today has agents, prompts and skills managed as data through the API, supervisor teams with Docker and Kubernetes workers (including Claude Code), per-tenant knowledge in Qdrant, a record of tokens and USD cost for every model call under /usage, Claude prompt caching, HTTP MCP servers in chat, OpenTelemetry and Sentry tracing, and one-click deploys to Railway, Render and Koyeb. It's MIT-licensed, and since 0.3.1 it installs from PyPI.

It's also no longer only ours. Six first-time contributors have joined since late September, with work that ranges from fixing the Qdrant healthcheck to working out how GitHub's and Atlassian's hosted MCP servers do OAuth.

Where we use it today

We build our current AI projects on HiveGate:

A personal-finance app whose agents propose and classify budgets.
Joyful Chess, a chess-learning project in the works. Its AI tutor is built on HiveGate.

That's our own use. It tells you what we test HiveGate against day to day. It isn't evidence that anyone else runs it, and we won't present it that way.

When you don't need it

Agno's own AgentOS also serves agents over HTTP, with sessions, human approval, RBAC and tracing. If your agents are defined in code and AgentOS covers what you need, use AgentOS.

HiveGate is for the case where agents and prompts are data you change over an API, each user connecting their own Google or Microsoft account, approvals that happen inside your product over REST, and a 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 paused-run and commit endpoints are documented in the agents API docs, and the toolkits and their confirmation lists in the toolkits docs.

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

AI agent REST API from pip install: HiveGate 0.3.1

HiveGate — Wed, 04 Nov 2026 16:00:01 +0000

Until last week, trying HiveGate meant cloning the repo, copying .env.example, running a setup script and starting the server from the checkout. That's fine if you want to work on HiveGate. It's a lot to ask if you only want to see whether it fits your agents.

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.

Human approval before risky agent tool calls

HiveGate — Wed, 28 Oct 2026 13:00:03 +0000

Originally published on hivegate.dev.

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.

Deploying Agno agents to production as a REST API

HiveGate — Tue, 20 Oct 2026 16:00:02 +0000

Originally published on hivegate.dev.

An Agno agent that works in a script is a few lines of Python. Turning it into something a web or mobile app can call for thousands of users takes more: an HTTP endpoint, a conversation per user, history that survives restarts, API keys, model keys kept on the server, and a container you can deploy.

This post shows how HiveGate, an MIT-licensed FastAPI service built on Agno, handles each of those. It also covers when you should skip HiveGate and use Agno's own AgentOS.

First: you may not need HiveGate

Agno ships AgentOS, which serves agents defined in code over HTTP, with sessions, human approval, RBAC and tracing:

from agno.agent import Agent
from agno.db.postgres import PostgresDb
from agno.models.google import Gemini
from agno.os import AgentOS

support_agent = Agent(
    name="support-agent",
    model=Gemini(id="gemini-3-flash-preview"),
    db=PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5432/ai"),
    add_history_to_context=True,
)

app = AgentOS(agents=[support_agent]).get_app()

If your agents live in your codebase and that covers what you need, use AgentOS. It's maintained by the Agno team and tracks Agno releases.

HiveGate is for a different case: agents that act for your users in their own Google or Microsoft accounts, and agents, prompts and skills that you manage as data through an API instead of shipping code for each change.

Agents are records, not code

In HiveGate you create an agent with a POST. The template becomes the agent's system prompt, stored as a versioned prompt in Postgres. The config block maps onto Agno's Agent options.

curl -X POST http://localhost:8000/v2/agents \
  -H "X-API-Key: $HIVEGATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "support-agent",
    "name": "support-agent",
    "template": "You are the support assistant for Acme. Answer briefly and cite the help center when you can.",
    "description": "Customer support for Acme",
    "tags": ["available_tools:email,calendar"],
    "config": {
      "enable_memory": true,
      "enable_history": true,
      "num_history_runs": 3
    }
  }'

The available_tools: tag switches on HiveGate's built-in toolkits for this agent. Leave it out and the agent gets none of them. Agents that need other tools can point at MCP servers over Streamable HTTP through config.worker_config.mcp_servers.

Changing the prompt later is a PUT /v2/prompts/support_agent (the prompt ID is the agent's name in snake case). The next chat picks up the new template, so a prompt fix doesn't need a redeploy.

Chatting, with sessions per user

Every chat request names a user_id and a session_id. Both are required, as are timezone and locale:

curl -X POST http://localhost:8000/v2/agents/support-agent/chat \
  -H "X-API-Key: $HIVEGATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "My invoice from last month looks wrong.",
    "user_id": "user-1842",
    "session_id": "ticket-5521",
    "timezone": "America/New_York",
    "locale": "en-US",
    "stream": false
  }'

The non-streaming response is a JSON object with content, session_id, run_id, status, the tools the agent called, and token_usage for that call.

Here is what happens to those two IDs:

History. Agno stores each run in a Postgres session table, one table per agent. With enable_history on, the last num_history_runs runs of the same session go back into the model's context. A follow-up with the same session_id continues the conversation, even after a restart or on another replica.
Memory. With enable_memory on, Agno's memory manager keeps facts about the user across sessions, keyed by user_id.
Agent cache. HiveGate builds the Agno Agent once per (prompt, agent, model, user, session) and caches it in the process, so later turns skip setup.

Per-request context goes into Agno's session_state. HiveGate fills it from the request: the user's name and profile (from user_profile), timezone and locale. If you send a tenant_profile, knowledge search is filtered to that tenant's documents, so one deployment can serve several customers without mixing their data.

Streaming

stream defaults to true. The response is Server-Sent Events, one event: message per Agno event, each with a JSON data line:

import json
import httpx

payload = {
    "message": "Summarize my open tickets.",
    "user_id": "user-1842",
    "session_id": "ticket-5521",
    "timezone": "UTC",
    "locale": "en",
}

with httpx.stream(
    "POST",
    "http://localhost:8000/v2/agents/support-agent/chat",
    headers={"X-API-Key": HIVEGATE_KEY},
    json=payload,
    timeout=120,
) as response:
    for line in response.iter_lines():
        if not line.startswith("data: "):
            continue
        event = json.loads(line[len("data: "):])
        if event.get("event") == "RunContent" and isinstance(event.get("content"), str):
            print(event["content"], end="", flush=True)

If a model call fails mid-stream, you get an event: error with a generic message. The details stay in the server log, so provider internals don't leak to clients.

Picking the model per request

A request can set model. Otherwise HiveGate uses DEFAULT_CHAT_MODEL, and falls back to gemini-3-flash-preview if that's unset. Besides pinned IDs such as claude-sonnet-4-6, it accepts aliases like anthropic:sonnet-latest or google:flash-latest. An alias resolves to the vendor's newest model in that tier and never moves you up to a pricier tier. Model keys stay in the server's environment; clients never see them.

API keys and cost per user

/v2/* requires an X-API-Key. Create keys with the admin secret:

curl -X POST http://localhost:8000/admin/api-keys \
  -H "X-Admin-Secret: $ADMIN_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"name": "acme-web", "rate_limit": 1000}'

The raw key is in the api_key field of the response, and it's shown only once. For local work, AUTH_DISABLED=true skips the check. Never set it on a deployment other people can reach.

Every model call is metered: tokens, cache reads, tool calls, duration and USD cost go into a token_usage table, including failed and abandoned runs. To see which users cost the most:

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

The usage endpoints accept a key with the usage:read scope. A key whose only scope is usage:read is refused on /v2, so a dashboard key can't call agents.

Running it

Locally, Docker Compose starts Postgres and Qdrant and seeds demo agents:

git clone https://github.com/hivegate-ai/hivegate && cd hivegate
cp .env.example .env    # set GOOGLE_API_KEY, uncomment AUTH_DISABLED=true
docker compose up -d
./scripts/dev_setup.sh && source .venv/bin/activate && ./scripts/start_server.sh

For a server, use the prebuilt multi-arch image ghcr.io/hivegate-ai/hivegate:latest. The deploy page has one-click buttons for Render, Railway and Koyeb, plus Kubernetes and AWS, Azure and GCP manifests. The settings that matter:

Variable	Why
`DB_HOST`, `DB_PORT`, `DB_USER`, `DB_PASS`, `DB_DATABASE`	Postgres for agents, sessions, tokens and usage
`ADMIN_SECRET`	Protects `/admin/*`, where API keys are created
`GOOGLE_API_KEY` / `ANTHROPIC_API_KEY` / `OPENAI_API_KEY`	At least one model provider
`SECRET_TOKEN_ENC_KEY`	Fernet key that encrypts stored user OAuth tokens
`QDRANT_URL`	Optional, for per-tenant knowledge

GET /health is the health check. The deploy page ends with a five-step smoke test: health, list agents, create an agent, one real LLM call, then cleanup.

What to know before scaling out

Conversation history is in Postgres, so any replica can serve the next turn. Two things live in process memory: the cached Agent objects, and runs that are paused waiting for a human to approve a tool call. A paused run has to be resumed on the process that paused it. If you use approvals, run one replica or route each session to the same instance. The post on approvals covers that flow.

When to use which

Agents defined in code, one team, standard Agno features: AgentOS.
Agents that act in each user's Gmail, Outlook or calendar; agents and prompts edited through an API; per-tenant knowledge; supervisor teams with container workers: HiveGate.

Try it

Deploy in one click from the deploy page.
Read the source, open an issue or star the repo on GitHub.

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

DEV Community: HiveGate

From BizGenie to HiveGate: where our agent runtime began

What BizGenie asked of the backend

The timeline

What carried over: approval before a write

The run pauses

Approve, edit or deny

The limits that came with it

What else carried over: each user's own accounts

What HiveGate is now

Where we use it today

When you don't need it

Try it

AI agent REST API from pip install: HiveGate 0.3.1

What you need

Install

Write the config

Start the stack

First calls

Agents are data

A tool call that waits for a person

What did that cost?

Off your laptop

Upgrading

What else is in 0.3.1

When you don't need HiveGate

Try it

Human approval before risky agent tool calls

Which tools pause

Step 1: the run pauses

Step 2: approve, edit or deny

The same thing from Python

Where paused runs live

The audit trail

A note on /v2/approvals

Try it

Deploying Agno agents to production as a REST API

First: you may not need HiveGate

Agents are records, not code

Chatting, with sessions per user

Streaming

Picking the model per request

API keys and cost per user

Running it

What to know before scaling out

When to use which

Try it

A note on `/v2/approvals`