Migrating to ReAct Core agent style

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

pip install --upgrade ibm-watsonx-orchestrate

​

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

​

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

1. Export your agent configuration:
   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:
   orchestrate agents import -f agent-config.yaml
   

​

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

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.
2. Update the style:
   1. Export your agent configuration:
      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:
      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:
      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:
      orchestrate agents import -f agent-config.yaml
      
   Rerun the benchmarks and compare the new results against the old baseline.

Troubleshooting

​

Scenario 3: Agents that use Plan-Act

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

​

Migrating custom join tools

Plan-Act configuration (before)

style: planner
custom_join_tools: my_formatting_tool

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)

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.

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

Plan-Act configuration (before)

style: planner
structured_output:
  type: object
  properties:
    summary:
      type: string
    confidence:
      type: number

ReAct Core configuration (after)

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

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

Monitor after migration

• 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

1. Review the Choosing a style for the agent documentation.
2. Review ADK agent examples.