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

# harnest.graph

> Public Python signatures, fields, and methods.

[All Python modules](https://usefused.com/docs/harnest/reference/api/overview.md) · [Import and compatibility guidance](https://usefused.com/docs/harnest/build/python-imports.md)

## Node event fields

| `Event` property | Purpose |
| - | - |
| `output` | Pass a value to the next node |
| `route` | Select a conditional edge |
| `message` | Emit assistant text |
| `state_delta` | Update managed session state |

## Exports

| Name | Kind |
| - | - |
| [`Edge`](#edge) | Class |
| [`Event`](#event) | Class |
| [`Graph`](#graph) | Class |
| [`GraphContext`](#graphcontext) | Class |
| [`Join`](#join) | Class |
| [`START`](#start) | Value or type alias |

## Edge

A directed graph edge between two node references.

```python theme={null}
Edge(source: str, target: str, route: Route = None) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `source` | `str` | `—` |
| `target` | `str` | `—` |
| `route` | `Route` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default | Description |
> | - | - | - | - |
> | `source` | `str` | Required | Node the edge starts from, or `START`. |
> | `target` | `str` | Required | Node the edge leads to. |
> | `route` | `Route` | `None` | Follow only when the source `Event` has this route. `None` means always. |
>
> ```python theme={null}
> from harnest.graph import Edge
>
> edge = Edge("classify", "refunds", route="refund")
> ```

## Event

Provider-neutral output emitted by a callable graph node.

`output` is passed to downstream nodes, `route` selects conditional
edges, and `message` emits user-facing assistant text. A node may set
more than one field on the same event.

```python theme={null}
Event(
    output: Any | None = None,
    route: Route = None,
    message: str | None = None,
    state_delta: Mapping[str, Any] = ...,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `output` | `Any \| None` | `None` |
| `route` | `Route` | `None` |
| `message` | `str \| None` | `None` |
| `state_delta` | `Mapping[str, Any]` | `dict()` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default | Description |
> | - | - | - | - |
> | `output` | `Any \| None` | `None` | Value passed to the next node. |
> | `route` | `Route` | `None` | Selects which conditional `Edge` to follow. |
> | `message` | `str \| None` | `None` | Assistant text shown to the user. |
> | `state_delta` | `Mapping[str, Any]` | `...` | Keys to update in session state. |
>
> ```python theme={null}
> from harnest.graph import Event
>
> event = Event(output="cleaned text", route="ready")
> ```

## Graph

A small, provider-neutral directed workflow graph.

Node mapping keys are the stable references used by `Edge`. Values are
lowered by a backend and may be agent definitions, callables, nested
graphs, joins, or backend-native nodes.

```python theme={null}
Graph(
    name: str,
    nodes: Mapping[str, Any],
    edges: Sequence[Edge],
    description: str = '',
    max_concurrency: int | None = None,
    output_schema: PydanticModel | None = None,
) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `name` | `str` | `—` |
| `nodes` | `Mapping[str, Any]` | `—` |
| `edges` | `Sequence[Edge]` | `—` |
| `description` | `str` | `''` |
| `max_concurrency` | `int \| None` | `None` |
| `output_schema` | `PydanticModel \| None` | `None` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default | Description |
> | - | - | - | - |
> | `name` | `str` | Required | Graph name. A valid Python identifier other than `user`. |
> | `nodes` | `Mapping[str, Any]` | Required | Map of node name to node (callable, agent, nested graph, `Join()`, or agent name). |
> | `edges` | `Sequence[Edge]` | Required | Edges between node names, starting from `Edge(START, ...)`. |
> | `description` | `str` | `''` | Short description of the graph. |
> | `max_concurrency` | `int \| None` | `None` | — |
> | `output_schema` | `PydanticModel \| None` | `None` | Pydantic model that validates the final output. |
>
> ```python theme={null}
> from harnest.graph import START, Edge, Graph
>
> root_agent = Graph(
>     name="support_flow",
>     nodes={"respond": "responder"},
>     edges=(Edge(START, "respond"),),
> )
> ```

### Graph.build

```python theme={null}
Graph.build(backend: str = 'adk') -> Any
```

Lower this graph with the named runtime backend.

> [accordion] Parameters and example
>
> | Parameter | Type | Default |
> | - | - | - |
> | `backend` | `str` | `'adk'` |
>
> ```python theme={null}
> from harnest.graph import Graph
>
> graph: Graph
> result = graph.build()
> ```

## GraphContext

Portable, read-only session state supplied to managed graph callables.

```python theme={null}
GraphContext(state: Mapping[str, Any]) -> None
```

Fields (`—` means no declared default):

| Field | Type | Default |
| - | - | - |
| `state` | `Mapping[str, Any]` | `—` |

> [accordion] Parameters and example
>
> | Parameter | Type | Default | Description |
> | - | - | - | - |
> | `state` | `Mapping[str, Any]` | Required | Read-only session state. |
>
> ```python theme={null}
> from harnest.graph import GraphContext
>
> def greet(value: str, context: GraphContext):
>     name = context.state.get("customer_name")
>     ...
> ```

## Join

Marker for a node that joins all of its incoming graph branches.

```python theme={null}
Join() -> None
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.graph import Join
>
> nodes = {"web": search_web, "docs": search_docs, "merge": Join()}
> ```

## START

```python theme={null}
START = 'START'
```

> [accordion] Example
>
> ```python theme={null}
> from harnest.graph import START, Edge
>
> edge = Edge(START, "first_node")
> ```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.