Skip to content

Why hgateway

The pain: hand-rolled human-in-the-loop

Most agents eventually need a human to approve, decide, edit, or supply context before they can keep going. Teams usually build this per-agent, from scratch:

  • Slack (or email) notification code written from scratch for every new agent.
  • No shared TTL, escalation, or reminder logic — if the human doesn't respond, that's usually just... unhandled.
  • No consistent way to route a question to the right person or channel.
  • Response parsing duplicated across every integration that needs an answer back.
  • The agent's own backend has to stay up and stateful just to wait on a human.

This works for one agent. It stops working at two or three — every new agent reinvents routing, escalation, and resume plumbing that has nothing to do with what the agent is actually for.

The idea: decouple HITL from the agent

What if raising a human interrupt was one typed function call, and a separate system owned everything after that — who gets notified, on what channel, what happens if they don't respond, and how the answer gets back to the agent?

That's hgateway — or rather, Ved, the hgateway agent that owns everything after that call. The agent's job shrinks to "ask a typed question, get a typed answer." Ved owns routing, notification, TTL/escalation, and delivery.

What decoupling unlocks

Once HITL is centralized in Ved instead of re-implemented per agent, here's what that buys you — mapped against the pain points teams hit hand-rolling this themselves.

Available today (current release)

  • Interactive UX — a real interactive message (Slack today), not a notification you have to build response-handling around yourself.
  • Proactive staleness handling — Ttl and OnExpiry.FORWARD_TO_SECONDARY track expiry in the background and act on it, so a HITL that goes stale never just silently sits there.
  • On-the-fly re-routing — RunFeatures.routing lets you point an interrupt at a different person/channel, including escalating to Routing.secondary on expiry, without redeploying the agent.
  • A reasoning capture stack — Ved is designed to capture the responder's reasoning alongside their resolution, not just the raw decision. This is newer surface area; check reference/responses.md for what's exposed today before depending on a specific field.
  • Basic governance controls — routing and channel configuration are defined once in Ved, not re-decided (or skipped) per integration.

Coming in a future release

  • A learning stack — learning from HITL history to reduce repeat/noisy interrupts over time.
  • Strong/advanced governance controls — org-level policy enforcement across HITL types and agent teams, beyond today's basic routing config.

Alongside all of that, a fallback path (fallback=...) means the agent still works if Ved is unreachable — decoupling doesn't mean a hard dependency.

Where the SDK fits

hgateway-sdk is the thin, typed client your agent uses to hand an interrupt to the gateway and get the typed response back. It doesn't own routing, notification, or TTL itself — it's the on-ramp. Everything above is the gateway's job; the SDK's job is making that handoff a single, well-typed call.

Next: see how this flows end-to-end in Architecture, or skip straight to Getting Started to integrate.