Quickstart

pip install hexgate

git clone https://github.com/HexamindOrganisation/hexgate.git
cd hexgate
pip install -e .

version: 1
roles:
  support:                       # front-line: small USD refunds only
    default_policy: { mode: deny }
    tools:
      refund_order:
        mode: allow
        constraints:
          - args.amount <= 50
          - args.currency == "USD"
  billing:                       # larger refunds, major currencies
    default_policy: { mode: deny }
    tools:
      refund_order:
        mode: allow
        constraints:
          - args.amount <= 500
          - args.currency in ["USD", "EUR"]

hexgate policy test policy.yaml --role support \
    --tool refund_order --args '{"amount": 400, "currency": "USD"}'
# ✗ DENY · support → refund_order({"amount": 400, "currency": "USD"})
#   reason: Policy on "refund_order" denied: constraint failed — args.amount <= 50

hexgate policy test policy.yaml --role billing \
    --tool refund_order --args '{"amount": 400, "currency": "USD"}'
# ✓ ALLOW · billing → refund_order({"amount": 400, "currency": "USD"})

import asyncio
from hexgate import agent_tool, create_agent, enforce_policy, stream_agent, HexgateContext


@agent_tool(name="refund_order")
async def refund_order(order_id: str, amount: float, currency: str = "USD") -> str:
    """Issue a refund against an order."""
    return f"Refunded {amount} {currency} on {order_id}"

agent, handler = create_agent(
    model="openai:gpt-5.4",
    tools=[refund_order],
    system_prompt="You are a support agent. Use refund_order to issue refunds.",
)
agent = enforce_policy(agent, "policy.yaml")   # the role-aware policy from step 2

async def refund_as(role: str):
    print(f"\n[{role}]")
    async with HexgateContext(user_id="u-1", user_roles=[role]):
        async for event in stream_agent(agent, handler, "Refund $400 on order O-42"):
            ...  # render events however you like

asyncio.run(refund_as("support"))   # refund_order blocked → model sees [policy_denied]
asyncio.run(refund_as("billing"))   # refund_order allowed → the refund runs

export OPENAI_API_KEY=sk-...
python support_demo.py