> ## Documentation Index
> Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating to ReAct Core agent style

Use this guide to migrate agents that use Default, ReAct, or Plan-Act styles to ReAct Core. This guide includes configuration snippets and tool examples to show what changes during migration. Use the examples as patterns that you can adapt to your agent configuration, prompts, tool names, and model settings.

Before you begin:

* Export your current agent configuration so that you can compare the before and after states.
* Review any custom instructions, tools, or output requirements that your agent depends on.
* Validate the migration in a test or draft environment before you update production agents.

<Note>
  Ensure that you have ADK version 2.5.0 or later. Update it with the following command:

  ```bash theme={null}
  pip install --upgrade ibm-watsonx-orchestrate
  ```
</Note>

The migration steps depend on your agent's current style and model. [Identify your migration path](#identify-your-migration-path) before you begin.

## Why migrate to ReAct Core

* **Improve performance**: ReAct Core consistently outperforms deprecated styles in benchmarks.
* **Support current and future models**: Works with modern model capabilities.
* **Simplify agent configuration**: Removes hidden style overrides.
* **Increase model compatibility**: Supports more LLM models with native chain-of-thought capabilities.

## Identify your migration path

| Current configuration                         | Migration path                                                               |
| --------------------------------------------- | ---------------------------------------------------------------------------- |
| Uses the `gpt-oss-120b` model                 | [Scenario 1](#scenario-1-agents-that-use-gpt-oss-120b)                       |
| Uses Default or ReAct style with other models | [Scenario 2](#scenario-2-agents-that-use-default-or-react-with-other-models) |
| Uses Plan-Act style                           | [Scenario 3](#scenario-3-agents-that-use-plan-act)                           |

## Scenario 1: Agents that use GPT-OSS-120B

If your agent uses the `gpt-oss-120b` model, it already uses ReAct Core internally. This migration does not change agent behavior.

1. Export your agent configuration:

   ```bash theme={null}
   orchestrate agents export -n <agent-name> -o agent-config.yaml
   ```

2. Edit your agent configuration file, for example, `agent-config.yaml`. Change `style: default` or `style: react` to `style: react_core`.

3. Update your agent:

   ```bash theme={null}
   orchestrate agents import -f agent-config.yaml
   ```

Your agent continues to work exactly as before with no behavior changes.

## Scenario 2: Agents that use Default or ReAct with other models

If your agent uses other models, such as `llama-3-3-70b-instruct`, test the migration carefully because behavior might change.

<Note>
  * The ReAct style includes Llama-specific optimizations that ReAct Core does not use.
  * If agent performance decreases after migration, consider migrating to `gpt-oss-120b` and rerun your evaluations.
</Note>

1. Create benchmark evaluations:

   Before you start the migration, create benchmark evaluations to compare agent performance before and after the change. This comparison helps you confirm that the migration does not reduce agent performance.

   For more information about evaluations, see [Evaluating agents and tools](../evaluate/evaluate).

2. Update the style:

   1. Export your agent configuration:

      ```bash theme={null}
      orchestrate agents export -n <agent-name> -o agent-config.yaml
      ```

   2. Edit your agent configuration file, for example, `agent-config.yaml`. Change `style: default` or `style: react` to `style: react_core`.

   3. Update your agent:

      ```bash theme={null}
      orchestrate agents import -f agent-config.yaml
      ```

3. Validate the changes:

   Rerun your benchmarks against the updated agent and compare the results to confirm that the migration did not have a negative impact. If performance degrades, proceed to step 4.

4. (Optional) Update the model:

   If benchmark performance worsens significantly after the style change, update the model to the recommended `gpt-oss-120b`.

   1. Export your agent configuration:

      ```bash theme={null}
      orchestrate agents export -n <agent-name> -o agent-config.yaml
      ```

   2. Edit your agent configuration file, for example, `agent-config.yaml`. Change the LLM to `groq/openai/gpt-oss-120b`. For example, from `llm: watsonx/meta-llama/llama-...` to `llm: groq/openai/gpt-oss-120b`.

   3. Update your agent:

      ```bash theme={null}
      orchestrate agents import -f agent-config.yaml
      ```

   Rerun the benchmarks and compare the new results against the old baseline.

##### Troubleshooting

| Issue                   | Solution                                                                                                     |
| ----------------------- | ------------------------------------------------------------------------------------------------------------ |
| Tool calling problems   | Ensure your model natively supports tool calling. Verify that your tool descriptions are clear and detailed. |
| Response format changes | Update your prompts to guide the desired output format.                                                      |
| Performance degradation | Consider switching to `gpt-oss-120b` or a newer third-party model.                                           |

## Scenario 3: Agents that use Plan-Act

The Plan-Act style has unique features that require special consideration during migration.

Plan-Act agents have two key capabilities:

* **Custom join tools**: Tools that handle response formatting.
* **Structured output**: Enforced output schemas.

You can achieve similar results in ReAct Core through careful prompting and configuration.

#### Migrating custom join tools

Instruct your agent to call a formatting tool before it responds to the user. In that formatting tool, use `audience` to provide a direct response without LLM interpretation. For more information, see [Tool response structure and annotations](https://developer.watson-orchestrate.ibm.com/tools/tool_response_structure).

##### Plan-Act configuration (before)

The following is the Plan-Act configuration before migration:

```yaml theme={null}
style: planner
custom_join_tools: my_formatting_tool
```

In the `my_formatting_tool.py`:

````python wrap theme={null}
import json
from typing import Dict, List, Any
from ibm_watsonx_orchestrate.agent_builder.tools import tool, ToolPermission
from ibm_watsonx_orchestrate.agent_builder.tools.types import PythonToolKind

@tool(permission=ToolPermission.READ_ONLY, kind=PythonToolKind.JOIN_TOOL)
def format_task_results(original_query: str, task_results: Dict[str, Any], messages: List[Dict[str, Any]]) -> str:
    """
    Format the results from various tasks executed by a planner agent into a cohesive response.

    Args:
        original_query (str): The initial query submitted by the user.
        task_results (Dict[str, Any]): A dictionary containing the outcomes of each task executed within the agent's plan.
        messages (List[Dict[str, Any]]): The history of messages in the current conversation.

    Returns:
        str: A formatted string containing the consolidated results.
    """
    output = f"## Results for: {original_query}\n\n"
    for task_name, result in task_results.items():
        output += f"### {task_name}\n"
        if isinstance(result, dict):
            output += "```json\n"
            output += json.dumps(result, indent=2)
            output += "\n```\n\n"
        elif isinstance(result, list):
            output += "\n".join([f"- {item}" for item in result])
            output += "\n\n"
        else:
            output += f"{result}\n\n"
    output += "## Summary\n"
    output += f"Completed {len(task_results)} tasks related to your query about {original_query.lower()}.\n"
    return output
````

##### ReAct Core configuration (after)

The following is the ReAct Core configuration after migration:

```yaml theme={null}
style: react_core
instructions: |
  ...
  IMPORTANT: After calling the required tools to answer a user's query,
  call my_formatting_tool to consolidate results and format the response.
```

In `my_formatting_tool.py`:

````python theme={null}
import json
from typing import Dict, Any
from ibm_watsonx_orchestrate.agent_builder.tools import tool

@tool()
def format_task_results(original_query: str, task_results: Dict[str, Any]) -> str:
    """
    Format the results from various tools into a cohesive response.

    Args:
        original_query (str): The initial query submitted by the user.
        task_results (Dict[str, Any]): A dictionary containing the outcomes of each task executed within the agent's plan. The key should be the tool name and the value should be the result.

    Returns:
        str: A formatted string containing the consolidated results.
    """
    output = f"## Results for: {original_query}\n\n"
    for task_name, result in task_results.items():
        output += f"### {task_name}\n"
        try:
            result = json.loads(result)
        except:
            pass
        if isinstance(result, dict) or isinstance(result, list):
            output += "```json\n"
            output += json.dumps(result, indent=2)
            output += "\n```\n\n"
        else:
            output += f"{result}\n\n"
    output += "## Summary\n"
    output += f"Completed {len(task_results)} tasks related to your query about {original_query.lower()}.\n"
    return {
        "content": [
            {
                "type": "text",
                "text": output,
                "annotations": {"audience": ["user"]}
            }
        ]
    }
````

#### Migrating structured output

Include the schema in the `instructions` field instead of in the `structured_output` field.

##### Plan-Act configuration (before)

The following is the Plan-Act configuration before migration:

```yaml theme={null}
style: planner
structured_output:
  type: object
  properties:
    summary:
      type: string
    confidence:
      type: number
```

##### ReAct Core configuration (after)

The following is the ReAct Core configuration before migration:

```yaml theme={null}
style: react_core
instructions: |
  Always format your final response as JSON with the following schema:
  {
    "type": "object",
    "required": ["summary"],
    "properties": {
      "summary": {
        "type": "string"
      },
      "confidence": {
        "type": "number"
      }
    }
  }

  Ensure the response is valid JSON and includes all required fields.
```

## Migration best practices

##### Test before deploying

Always test in the draft environment:

* Create a copy of your agent for testing.
* Run comprehensive test cases.
* Use evaluation datasets when possible.

##### Monitor after migration

After you migrate to production:

* Monitor agent performance metrics.
* Watch for unexpected behaviors.
* Keep a rollback plan ready.

##### Update documentation

* Update internal documentation to reflect the new style.
* Inform users of any behavior changes.
* Document any prompt adjustments you made.

## Getting help

If you encounter issues during migration:

1. Review the [Choosing a style for the agent](/agent-styles/agent-style) documentation.
2. Review [ADK agent examples](https://github.com/IBM/ibm-watsonx-orchestrate-adk/tree/main/examples).