---

name: agent-core description: "Route ROSA installation, model configuration, construction, invocation, streaming, history, and executor controls." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

ROSA agent core

Use this route when the task is to install or import the Python package, create a ROSA agent, select a tool-calling LangChain chat model, invoke it, stream events, reset conversation state, inspect token behavior, or bound iterations. This route covers the agent lifecycle, not the detailed ROS tool catalog.

First checks

1. Install the distribution with python -m pip install jpl-rosa in a Python >=3.9,<4 environment.
2. Import the public API with from rosa import ROSA, RobotSystemPrompts, ChatModel. The distribution is jpl-rosa; the import package is rosa.
3. Remember that pip installation does not install ROS middleware. ROSA construction loads the selected ROS 1 or ROS 2 tool family, so the matching ROS Python modules/runtime must be installed and sourced separately.
4. Supply a LangChain chat model that supports tool calling. Do not run a live model or ROS system merely to inspect this skill.

For exact signatures and event shapes, read api-reference.md. Use workflows.md for sync/async lifecycle recipes and llm-configuration.md for provider setup. Start with troubleshooting.md when construction or execution fails.

Common lifecycle

install jpl-rosa -> import rosa -> configure tool-calling model
       -> construct ROSA(ros_version=1 or 2, llm=...)
       -> choose invoke() or astream()
       -> inspect/clear chat_history as needed

• Choose ros_version=1 for ROS 1 or ros_version=2 for ROS 2; then follow ros1-operations or ros2-operations, respectively.
• Use invoke(query) for a complete synchronous string. Ordinary exceptions are converted to an An error occurred: ... string; KeyboardInterrupt is propagated.
• Use astream(query) only on an instance created with streaming=True, and consume every event in order. Handle token, tool_start, tool_end, final, and error event types.
• Chat history accumulates successful query/answer pairs by default. Use accumulate_chat_history=False for stateless calls and clear_chat() to reset an existing conversation.
• show_token_usage is effective only for non-streaming OpenAI/Azure models; it is automatically disabled for streaming and for other model classes.
• max_iterations, verbose, and return_intermediate_steps are executor controls. The public invoke() result remains the output string even when intermediate steps are requested.

Route boundaries

• For ROS 1/ROS 2 graph inspection and actions, use the sibling routes above; do not invent entity names or bypass discovery.
• For tools, tool_packages, blacklist, custom robot prompts, or extending the tool registry, use tool-customization.
• For package-wide prerequisites and cross-cutting environment checks, return to the rosa root route.
• Keep credentials, model calls, ROS launches, Docker/TurtleSim, and destructive robot actions out of installation or documentation checks.