harnest.graph

All Python modules · Import and compatibility guidance

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`	Class
`Event`	Class
`Graph`	Class
`GraphContext`	Class
`Join`	Class
`START`	Value or type alias

Edge

A directed graph edge between two node references.

Edge(source: str, target: str, route: Route = None) -> None

Fields (— means no declared default):

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

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.

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.

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()`

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.

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.

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`

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.

from harnest.graph import START, Edge, Graph

root_agent = Graph(
    name="support_flow",
    nodes={"respond": "responder"},
    edges=(Edge(START, "respond"),),
)

Graph.build

Graph.build(backend: str = 'adk') -> Any

Lower this graph with the named runtime backend.

Parameters and example

Parameter	Type	Default
`backend`	`str`	`'adk'`

from harnest.graph import Graph

graph: Graph
result = graph.build()

GraphContext

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

GraphContext(state: Mapping[str, Any]) -> None

Fields (— means no declared default):

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

Parameters and example

Parameter	Type	Default	Description
`state`	`Mapping[str, Any]`	Required	Read-only session state.

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.

Join() -> None

Example

from harnest.graph import Join

nodes = {"web": search_web, "docs": search_docs, "merge": Join()}

START

START = 'START'

Example

from harnest.graph import START, Edge

edge = Edge(START, "first_node")

Overview

Get started

Harnest Studio

Guides

API reference

harnest.graph

Node event fields

Exports

Edge

Event

Graph

Graph.build

GraphContext

Join

START

​Node event fields

​Exports

​Edge

​Event

​Graph

​Graph.build

​GraphContext

​Join

​START

Node event fields

Exports

Edge

Event

Graph

Graph.build

GraphContext

Join

START