> ## 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.

# Migrate a project

> Bring an existing agent into Harnest, upgrade a project, or switch frameworks.

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       |

<Steps>
  <Step title="Create a Harnest project beside the existing agent">
    <CodeGroup>
      ```bash Managed theme={null}
      harnest init migrated-agent --framework adk
      ```

      ```bash Advanced theme={null}
      harnest init migrated-agent --framework adk --mode advanced
      ```
    </CodeGroup>

    Use `--framework langgraph` for an existing LangGraph agent.
  </Step>

  <Step title="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`.
  </Step>

  <Step title="Test through the harness">
    ```bash theme={null}
    cd migrated-agent
    harnest test .
    harnest serve .
    ```
  </Step>
</Steps>

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

<Steps>
  <Step title="Preview the migration">
    ```bash theme={null}
    cd existing-agent
    harnest upgrade .
    ```

    This command is read-only. Review its plan before continuing.
  </Step>

  <Step title="Apply the reviewed migration">
    ```bash theme={null}
    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.
  </Step>

  <Step title="Test the upgraded project">
    ```bash theme={null}
    harnest test .
    ```
  </Step>
</Steps>

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`:

```yaml theme={null}
spec:
  framework:
    name: langgraph # or adk
    mode: managed
```

Then validate the target framework:

```bash theme={null}
harnest test .
harnest serve .
```

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

Follow the [framework migration checklist](/docs/harnest/runtime/adk-and-langgraph#switch-frameworks).