Known issues and limitations - IBM watsonx Orchestrate ADK

Get a quick overview of the known issues and limitations for IBM watsonx Orchestrate ADK.

Issue	Description
`orchestrate --version` command	`orchestrate --version` command might not work or return the wrong version. To solve it, run `which orchestrate` to ensure it’s using your Python virtual environment (venv); if not, remove conflicting versions until it does, and if the issue persists even with the correct venv, delete and recreate the venv and reinstall the ADK.
Tool import after upgrade	If you upgraded your watsonx Orchestrate Developer Edition and try to import a tool, you might run into permission issues. Run `docker volume rm docker_tools-runtime-data` to remove the existing tools and trigger a clean reinstall.
MCP tool upload	When you upload MCP tools from the filesystem, you must zip the tool folder. You should be able to point to the root folder instead, but that isn’t working as expected.
Renaming tools	When a tool name is modified within watsonx Orchestrate, the change is not propagated back to MCP. Currently, tool updates are unidirectional, flowing only from MCP to watsonx Orchestrate. As a result, any renaming or updates made in watsonx Orchestrate will not be reflected in MCP, potentially leading to inconsistencies or communication issues between the two systems.
Agentic workflow tool	If you delete an OpenAPI tool from the CLI and then import the same tool again, agentic workflow tool fails. The re-imported tool gets a different tool ID, so it no longer matches the original reference.
Tools running prematurely	Depending on the LLM you use, tools might start running before you provide all required inputs. To solve this, try a different LLM in your agent.
First interaction with an agent might fail to call a tool	Sometimes, when you start the Developer Edition, the first message that the user sends to the agent might fail. This issue can happen because the system did not have enough time to properly start its services, or because of a pod failure. To solve this, you can try sending the same message again after a couple of minutes, after the system has enough time to restart the pod and reload the tools.
Agent returns an empty message	In certain scenarios, asking multiple queries to the agent or even otherwise on shorter conversations, the LLM might respond with a message “None” instead of making tool calls. In such cases, try switching the agent’s style to `default`.
Agent makes multiple calls for the same tool after every message	The agent might run the same tool multiple times after every interaction. To solve this, you can try providing clear instructions in your agent definition to run the tool only once, or you can try switching the agent’s model.
Agent ignores valid tools	Occasionally, agents might return incomplete responses with invalid tool calls. This can happen if the agent recognizes the tool’s response as invalid. To solve this issue, you can try defining the tool as a YAML file, and provide a clear and more concise tool description. You can also provide clear instructions in your agent definition to interpret the tool’s responses directly and to consider the tool’s expected return data types.
Incosistent transfer between multi-agent collaborators	When using multi-agent collaboration, agent-to-agent communication might fail due to improper instruction formatting or invalid responses. To solve this issue, you must provide clear instructions in your agent definition, explicitly detailing that one agent must transfer to another agent after completing its task.
Async openAPI tools in watsonx Orchestrate Developer Edition	In watsonx Orchestrate Developer Edition, external async tools can’t access the auto-detected local IP, which isn’t publicly reachable. Set CALLBACK_HOST_URL to a public endpoint (e.g., via ngrok) to enable callbacks.
watsonx Developer Edition on WSL	If you run watsonx Orchestrate Developer Edition on WSL, stop the Orchestrate server before shutting down WSL. Otherwise, both Docker and watsonx Orchestrate may hang or become unresponsive.
Tool call	Tool call not working for `watsonx/mistralai/pixtral-12b` model.
Gemini tool invocation	Gemini models occasionally fail when invoking a tool, returning an UNEXPECTED_TOOL_CALL error. A temporary workaround is to retry the request.
Gemini-2.0-flash usage	The gemini-2.0-flash model does not support React-style usage.
Array of strings in LLaMA models	LLaMA models accept only a single string as an argument. If passed an array of strings, they convert it into a single string, which may lead to incorrect results when calling a tool that expects an array.

Troubleshooting