SDK reference - hexgate

The curated public surface re-exported from the top-level hexgate package. Each symbol links to the guide where it’s used in context.

from hexgate import (
    create_agent,
    agent_tool,
    enforce_policy,
    create_manifest,
    AgentManifest,
    AgentPolicy,
    stream_agent,
    stream_agent_raw,
    invoke_agent,
    load_agent,
    load_local_agent,
    load_registered_agent,
    load_hexgate_agent,
    register_agent_factory,
    HexgateContext,
)

Building agents

Symbol	What it does
`create_agent(model, tools, system_prompt, …)`	Build a native agent + handler. See Build an agent.
`agent_tool(name=…)`	Decorator that turns an async function into a policy-gated tool.
`create_manifest(agent, …)`	Derive an `AgentManifest` from any supported agent without POSTing it. See register.
`AgentManifest`	Pydantic model the platform stores and the dashboard renders.

Policy enforcement

Symbol	What it does
`enforce_policy(agent, policy, approval_handler=…)`	Apply an `AgentPolicy` or YAML path to an agent. Accepts an optional handler for `approval_required` outcomes. See policy YAML shape.
`AgentPolicy`	Pydantic model of a policy (roles, tools, modes, constraints).

Running agents

Symbol	What it does
`stream_agent(agent, handler, message)`	Yield normalized events (text deltas, tool lifecycle, run end). See Build an agent.
`stream_agent_raw(...)`	Lower-level streaming without normalization.
`invoke_agent(...)`	Run to completion and return the final result.

Loading & registering agents

Symbol	What it does
`load_agent(name)`	Resolve by name — platform when `HEXGATE_API_KEY` is set, else local / registered.
`load_local_agent(name)`	Load a directory agent (`./<dir>/agent.yaml`, `./examples/<dir>/agent.yaml`, …).
`load_registered_agent(name)`	Load an agent registered in-process via a factory.
`load_hexgate_agent(name)`	Fetch a named agent (+ roles) from the platform. See user scope.
`register_agent_factory(name, factory)`	Register a code-defined agent factory so `load_agent` / `load_registered_agent` can resolve it.

Identity

Symbol	What it does
`HexgateContext(user_id, user_roles=[…], session_id=…, ttl_seconds=…, attributes={…})`	Per-request scope context manager — its primary role is the decision input. See user scope.

Built-in tools

Filesystem tools are importable from hexgate: read_file, write_file, edit_file, glob, grep, bash. The shell-backed ones run inside the workspace sandbox.

web_search, fetch, and refund_order are no longer built in — they moved to examples/tools/ (websearch.py, fetch.py, refund.py). Import them from there. For a code-defined agent, pass the tool in create_agent(..., tools=[...]); for a YAML-loaded agent, satisfy a tool named in the YAML via load_agent(name, extra_tools={...}). A direct from hexgate import web_search raises an ImportError that points at the new location.

​Building agents

​Policy enforcement

​Running agents

​Loading & registering agents

​Identity

​Built-in tools

Building agents

Policy enforcement

Running agents

Loading & registering agents

Identity

Built-in tools