Migrate a project

Choose the migration that matches your project:

Migration	Change
Existing portable agent	Start in managed mode
Existing native agent	Start in advanced mode
Upgrade a Harnest project	Run `harnest upgrade`
Switch a managed framework	Change `spec.framework.name`

Bring an existing agent into Harnest

Choose the mode that preserves the agent’s current behavior:

Agent today	Start with	Why
Portable agent, tools, or graph	Managed mode	Harnest can discover and wire the capabilities
Native plugins, middleware, state, or framework APIs	Advanced mode	Your code keeps direct framework control

Create a Harnest project beside the existing agent

harnest init migrated-agent --framework adk

harnest init migrated-agent --framework adk --mode advanced

Use --framework langgraph for an existing LangGraph agent.

Move the agent and its dependencies

Move the source into migrated-agent, then export a managed Agent or Graph, or wrap the existing native target with Agent.advanced(...). Add only agent-owned packages to pyproject.toml.

Test through the harness

cd migrated-agent
harnest test .
harnest serve .

Advanced mode is not a dead end. Move tools, skills, MCP connections, lifecycle hooks, and other compatible pieces into managed folders when useful.

Upgrade an older Harnest project

Preview the migration

cd existing-agent
harnest upgrade .

This command is read-only. Review its plan before continuing.

Apply the reviewed migration

harnest upgrade . --apply

This splits old package-root imports into their owning feature modules, rewrites lifecycle and context decorators to their first-class namespaces, and updates released OutputPolicy forms. It also migrates retired same-process Runtime Plugin packages to Harnest Extensions:

Before	After
`plugins/<name>/plugin.yaml`	`extensions/<name>/extension.yaml`
`plugin.py` and `plugin`	`extension.py` and `extension`
`kind: RuntimePlugin`	`kind: Extension`
`requires.plugins`	`requires.extensions`
`harnest.plugins`	`harnest.extensions`
`<name>` distribution	`harnest-extension-<name>` distribution
inferred content folders	explicit `contributes` paths

The upgrade declares each existing Runtime Plugin tools/, mcp/, skills/, and subagents/ directory under the matching contributes key. It moves the old package extensions/ hook directory to lifecycle/ and declares that path under contributes.lifecycle. New Harnest Extensions do not infer content from directory names.Agent Plugin folders containing plugin.json stay under plugins/; they are declarative packages and are not part of this executable-code migration. Harnest no longer infers manifestless plugins/<name>/{mcp,skills} packages; install or rebuild those packages against the Agent Plugins standard before compiling the upgraded project.

Test the upgraded project

harnest test .

Harnest checks that reviewed files have not changed and creates backups under .harnest/upgrade-backups/. It stops when a change needs your judgment.

Switch between ADK and LangGraph

For a managed agent, change spec.framework.name in config.yaml:

spec:
  framework:
    name: langgraph # or adk
    mode: managed

Then validate the target framework:

harnest test .
harnest serve .

Review native extensions, evals, sandboxes, custom nodes, and active checkpoints first. Advanced projects need a manual migration.

Follow the framework migration checklist.

Overview

Get started

Guides

Migrate a project

Bring an existing agent into Harnest

Upgrade an older Harnest project

Switch between ADK and LangGraph

​Bring an existing agent into Harnest

​Upgrade an older Harnest project

​Switch between ADK and LangGraph

Bring an existing agent into Harnest

Upgrade an older Harnest project

Switch between ADK and LangGraph