ADK and LangGraph

Every project selects a framework and authoring mode in config.yaml:

apiVersion: harnest.dev/v1alpha1
kind: Agent
spec:
  entrypoint: agent:root_agent
  framework:
    name: adk          # adk or langgraph
    mode: managed      # managed or advanced

Managed mode

Managed mode is the portable default. Harnest discovers your resources and builds the selected framework target.

Moves between frameworks	Remains native
Agents, graphs, instructions, contracts, and named sandbox assignments	ADK plugins, evals, and native executor providers
Tools, MCP clients, Agent Plugins, Harnest Extension content, and Agent Skills	LangGraph middleware and native nodes
Portable lifecycle hooks	Framework-owned checkpoints
Sessions, auth, approvals, transports, and tests	Arbitrary native framework calls

A nested LangGraph Agent cannot consume a discovered child subagents/ folder. Express that topology in the portable root graph.

Advanced mode

In advanced mode, you construct a native target and export it through Agent.advanced(...).

Harnest still owns	Your native target owns
Neutral server and transports	Routing and state
Sessions and request authentication	Native checkpoints
Approvals and tracing	Middleware or plugins
Portable invocation hooks	Capability wiring and native model calls

Agent Runtime Principals are best-effort in advanced mode. Harnest enforces them at Harnest-owned tool, MCP, invocation, and Task boundaries, but it does not rewrite your native graph or wrap tools you wire directly. Apply equivalent policy in user-owned graph paths and downstream gateways when you need complete coverage. See Agent Runtime Principals. Before moving a project from managed to advanced mode, run the read-only audit:

harnest mode advanced AGENT_DIR --check

Preserve agent.py; do not run init over the project.

Switch frameworks

Changing spec.framework.name is simple. Validating the behavior is the migration.

Establish the current baseline

Preserve the source and run the existing unit tests.

Find native dependencies

Inspect agent.py, native extensions, custom graph nodes, nested SubAgents, sandboxes, eval assets, and active checkpoints.

Change the framework

Update only spec.framework.name. Do not add Harnest-owned framework packages to pyproject.toml.

Test the target

Run harnest test AGENT_DIR, any authorized smoke tests, and harnest serve AGENT_DIR.

Committed session state can survive a switch. Active framework checkpoints cannot be translated. Finish or deliberately abandon in-progress runs first.

Choose a framework

Choose	When
Managed ADK	You want portability plus ADK’s ecosystem
Managed LangGraph	You want portability plus LangGraph’s ecosystem
Advanced ADK	ADK-native agents, plugins, evals, or code execution define the design
Advanced LangGraph	Native graph state, middleware, or graph primitives define the design

All choices use the same Harnest agent card, sessions, API, events, WebSocket protocol, and playground. Durable managed tools use each framework’s native suspension boundary. Review the different replay semantics in Durable execution.

Version compatibility

Harnest installs a tested framework version and records it in the manifest. Upgrade Harnest to adopt a newer version; do not override it in pyproject.toml.

Overview

Get started

Guides

ADK and LangGraph

Managed mode

Advanced mode

Switch frameworks

Choose a framework

Version compatibility

​Managed mode

​Advanced mode

​Switch frameworks

​Choose a framework

​Version compatibility

Managed mode

Advanced mode

Switch frameworks

Choose a framework

Version compatibility