# Migrate existing agents to current version

> Migrate existing agents to current version - Migrate Agentic Starter projects from pre-11.8.1 class-
> based agents to the factory-based layout, by framework.

This Markdown file sits beside the HTML page at the same path (with a `.md` suffix). It summarizes the topic and lists links for tools and LLM context.

Companion generated at `2026-05-01T23:10:47.698251+00:00` (UTC).

## Primary page

- [Migrate existing agents to current version](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-starter-migration.html): Full documentation for this topic (HTML).

## Sections on this page

- [Before you start](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-starter-migration.html#before-you-start): In-page section heading.
- [Changes that apply to most frameworks](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-starter-migration.html#changes-that-apply-to-most-frameworks): In-page section heading.
- [custompy_adaptorand the LLM](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-starter-migration.html#custompy-adaptor-and-the-llm): In-page section heading.
- [Configuration](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-starter-migration.html#configuration): In-page section heading.
- [Tests](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-starter-migration.html#tests): In-page section heading.
- [Framework-specific migration](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-starter-migration.html#framework-specific-migration): In-page section heading.
- [LangGraph](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-starter-migration.html#langgraph): In-page section heading.
- [CrewAI](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-starter-migration.html#crewai): In-page section heading.
- [LlamaIndex](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-starter-migration.html#llamaindex): In-page section heading.
- [Base (generic)](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-starter-migration.html#base-generic): In-page section heading.
- [NAT](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-starter-migration.html#nat): In-page section heading.
- [After you migrate](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-starter-migration.html#after-you-migrate): In-page section heading.

## Related documentation

- [Agentic AI](https://docs.datarobot.com/en/docs/agentic-ai/index.html): Linked from this page.
- [Build](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/index.html): Linked from this page.
- [Configure LLM providers with metadata](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-llm-providers-metadata.html): Linked from this page.
- [Customize agents](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-development.html#testing-the-agent-during-local-development): Linked from this page.
- [Agent components](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-overview.html): Linked from this page.

## Documentation content

# Migrate existing agents to current version

Users with agents constructed using the [Agentic Starter template](https://github.com/datarobot-community/datarobot-agent-application) prior to [version 11.8.1](https://github.com/datarobot-community/datarobot-agent-application/releases/tag/v11.8.1) must perform a one-time update to maintain compatibility with newer releases. This is due to a change in the way the template constructs agents and how tools reach the workflow:

- LangGraph, CrewAI, and LlamaIndex no longer rely on a handwritten MyAgent subclass. Build the native framework object (graph, crew, or workflow) first, then wrap it with a datarobot_agent_class_from_* factory that produces MyAgent .
- Base (generic) still subclasses BaseAgent , with simplified construction and LLM wiring. custompy_adaptor passes llm=get_llm(...) , consistent with other templates.
- NAT (NVIDIA NeMo Agent Toolkit) still subclasses NatAgent . __init__ is smaller, custompy_adaptor omits model= , and LLMs stay declarative in workflow.yaml .

Across these patterns, the LLM is decoupled from ad hoc class state. Framework-specific `get_llm()` helpers resolve the model inside `custompy_adaptor` (and, for DRAgent, in `register.py`). MCP and workflow tools are injected at runtime instead of being read from `self.mcp_tools` on a `LangGraphAgent` -style subclass.

This page summarizes migration steps by framework. For step-by-step diffs, before-and-after examples, and test updates, see the [framework migration guides](https://github.com/datarobot-community/datarobot-agent-application/tree/main/docs/agent) in the template repository ( `docs/agent/`).

## Before you start

- Back up your repository and .env file before you merge template updates.
- Update the template (pull the latest Agentic Starter changes, or run dr component update for the agent component) so pyproject.toml , uv.lock , and generated stubs match the version you target.
- Rename environment variables if you still use deprecated names. Deployed LLM configuration expects LLM_DEPLOYMENT_ID (not TEXTGEN_DEPLOYMENT_ID ). See Configure LLM providers with metadata .
- Keep the MyAgent export—infrastructure and tests expect that symbol. Do not rename it.

## Changes that apply to most frameworks

### custompy_adaptor and the LLM

In `custompy_adaptor`, replace passing a `model=` string into `MyAgent(...)` with passing `llm=` from `get_llm(...)` in the appropriate module:

- LangGraph / Base: datarobot_genai.langgraph.llm.get_llm
- CrewAI: datarobot_genai.crewai.llm.get_llm (CrewAI may need extra parameters , for example {"stream_options": None} )
- LlamaIndex: datarobot_genai.llama_index.llm.get_llm

Filter placeholder model names with a small set such as `_PLACEHOLDER_MODELS = frozenset({"unknown"})` so a placeholder `model_name` from DataRobot does not force an invalid model.

### Configuration

In `myagent.py`, remove `from agent.config import Config` where the new pattern delegates configuration to `get_llm()` and the runtime environment. If your template still loads MCP-related settings in `custom.py`, keep `Config` there.

### Tests

Across frameworks, tests that constructed `MyAgent(model=..., api_key=...)` should use `MyAgent(llm=Mock(), ...)` instead. Remove tests that target deleted `llm()` methods or old `__init__` signatures. Add tests for `graph_factory` or other module-level wiring where applicable.

## Framework-specific migration

### LangGraph

- Replace class MyAgent(LangGraphAgent) with:
- A module-level prompt_template
- Remove llm() , __init__ boilerplate, and Config imports from myagent.py as described in the LangGraph migration guide .

### CrewAI

- Move agents, tasks, crew, and kickoff_inputs to module level; call get_llm() once at module scope where appropriate.
- Replace the class with MyAgent = datarobot_agent_class_from_crew(crew, agents, tasks, kickoff_inputs) .
- Tools are injected at runtime; do not rely on self.tools on the old class.
- Crew stream : often False at module scope; DRAgent can adjust streaming at runtime (see the migration guide in the template repository).

### LlamaIndex

- Use a module-level LiteLLM(model="placeholder") (or equivalent) for agents until custompy_adaptor injects the real LLM.
- Move agents, workflow, state tools, and extract_response_text to module level. Remove make_input_message (the factory handles it).
- MyAgent = datarobot_agent_class_from_llamaindex(workflow, agents, extract_response_text) .

### Base (generic)

- MyAgent still subclasses BaseAgent . __init__ is simplified because BaseAgent owns initialization.
- Remove manual _llm , self.config , and Config usage from the class. Pass llm=get_llm(...) from custompy_adaptor as in the Base migration guide .

### NAT

- NAT requires fewer structural changes than other frameworks: MyAgent(NatAgent) still subclasses NatAgent , but __init__ forwards *args / **kwargs to super() and supplies a default workflow_path .
- In custompy_adaptor , omit model= when constructing MyAgent ; LLMs are defined in workflow.yaml .

## After you migrate

1. Run dr task run agent:install (or your template’s install task), then dr task run agent:test .
2. Start the local stack with dr run dev or task dev , exercise the app, and run task agent:cli as described in Customize agents .
3. Deploy to a non-production environment first. Confirm traces and MCP behavior in the DataRobot UI.

For ongoing development tasks after migration, see [Customize agents](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-development.html) and [Agent components](https://docs.datarobot.com/en/docs/agentic-ai/agentic-develop/agentic-overview.html).