Agents and graphs

agent.py exports the configured root_agent. In managed mode this is an Agent or portable Graph; in advanced mode it wraps a native ADK or LangGraph target with Agent.advanced(...).

Root type	Choose it for
`Agent`	One model-led agent
`Graph`	Routing, branches, joins, or several agents
`Agent.advanced(...)`	Native framework behavior outside the portable API

See Python imports for the public modules that group agent, model, tool, and runtime APIs.

Managed agent

The concise form builds a native agent for the selected framework:

agent.py

from harnest.agent import Agent
from harnest.model import LiteLLMModel

root_agent = Agent(
    name="support",
    model=LiteLLMModel.from_openai_environment(),
    description="Answers product questions and triages support requests.",
)

instructions.md beside agent.py is required. It is the default managed prompt and remains bundle metadata for graphs and advanced targets. Set OPENAI_MODEL, OPENAI_BASE_URL, and, if required, OPENAI_API_KEY. No model or endpoint is selected by default. See Configure a model. history="session" is the default and includes earlier user and assistant turns from the same Harnest session. Use history="turn" for an isolated model call. Do not duplicate the conversation transcript in graph state. Use token_policy to observe usage, enforce budgets, or reduce context per agent. See Token utilisation.

Portable graph

Use a graph for deterministic routing, parallel branches, joins, agent nodes, or a topology that should lower to either framework:

agent.py

from harnest.graph import START, Edge, Event, Graph, Join

def normalize(request):
    return Event(output=request.strip(), route="ready")

root_agent = Graph(
    name="support_flow",
    nodes={
        "normalize": normalize,
        "specialist": "order_specialist",
        "complete": Join(),
    },
    edges=(
        Edge(START, "normalize"),
        Edge("normalize", "specialist", route="ready"),
        Edge("specialist", "complete"),
    ),
)

Return an Event to pass output, route execution, emit text, or update session state. See node event fields. Nodes can be callables, agents, nested graphs, joins, discovered resources, or supported native nodes. Harnest rejects unknown edges, duplicates, and unreachable nodes before execution.

Structured input and output

Pass Pydantic classes from harnest.models.* as input_schema or output_schema. Harnest applies them to JSON, SSE, WebSocket, and OpenAPI. Add an explicit FrameworkMetadata[...] field only when you need native turn metadata.

Advanced target

Use advanced mode only when the portable API cannot express required native behavior:

agent.py

from harnest.agent import Agent

root_agent = Agent.advanced(target=compiled_graph, name="support")

Your code then owns native routing, state, checkpoints, middleware or plugins, and capability wiring. Harnest keeps the neutral server, sessions, auth, approvals, and telemetry.

API reference

Reference: harnest.model.

Overview

Get started

Harnest Studio

Guides

API reference

Agents and graphs

Managed agent

Portable graph

Structured input and output

Advanced target

API reference

​Managed agent

​Portable graph

​Structured input and output

​Advanced target

​API reference

Managed agent

Portable graph

Structured input and output

Advanced target

API reference