> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexgate.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK reference

> Python API for the hexgate package.

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

```python theme={null}
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](/guides/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](/cli/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](/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](/guides/build-an-agent#stream-results). |
| `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](/concepts/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](/concepts/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](/concepts/sandbox).

<Note>
  `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.
</Note>