agents.components.cortex

Module Contents

Classes

Cortex

The Cortex component is an LLM-powered task planner and executor that also serves as the system monitor.

API

class agents.components.cortex.Cortex(*, actions: Optional[List[agents.ros.Action]] = None, output: Optional[agents.ros.Topic] = None, model_client: Optional[agents.clients.model_base.ModelClient] = None, db_client: Optional[agents.clients.db_base.DBClient] = None, config: Optional[agents.config.CortexConfig] = None, component_name: str, **kwargs)

Bases: agents.components.model_component.ModelComponent, agents.ros.Monitor

The Cortex component is an LLM-powered task planner and executor that also serves as the system monitor.

Named after the cerebral cortex, the brain region responsible for higher-order planning, reasoning, and action sequencing, this component takes a high-level task, uses an LLM to decompose it into sub-tasks, and executes them by dispatching Actions registered on other components.

Task execution follows a two-phase approach:

  1. Planning – A single LLM call with all available actions as tools produces a step-by-step plan (returned as multiple tool_calls). Optional RAG context from a vector DB is injected during this phase.

  2. Execution – Each planned step is executed sequentially. Before each step, a brief LLM confirmation call decides: EXECUTE, SKIP, or ABORT, based on the original plan and results so far.

The component runs as a ROS2 action server, receiving task goals and providing feedback during execution.

Parameters:

  • actions (list[Action]) – The action palette – a list of Action objects with descriptions, representing the actions available to the planner.

  • output (Topic) – Output topic for publishing results for tasks where an action is not required or a plan is not generated.

  • model_client (Optional[ModelClient]) – The model client for LLM inference. Optional if enable_local_model is set to True in the config.

  • db_client (Optional[DBClient]) – Optional database client for RAG context during planning.

  • config (Optional[CortexConfig]) – Configuration for the Cortex component.

  • component_name (str) – The name of this component.

Example usage:

from agents.components import Cortex
from agents.config import CortexConfig
from agents.ros import Action, Topic, Launcher

cortex = Cortex(
    actions=[
        Action(method=nav.go_to, description="Navigate to a location"),
        Action(method=arm.grasp, description="Grasp an object"),
    ],
    model_client=my_client,
    config=CortexConfig(max_planning_steps=10, max_execution_steps=15),
    component_name="cortex",
)
add_documents(ids: List[str], metadatas: List[Dict], documents: List[str]) → None

Add documents to vector DB for RAG context during planning.

main_action_callback(goal_handle)

Action server callback. Iterative plan-execute loop.

Plans a batch of steps, executes them, then feeds the results back into the planning conversation so the LLM can continue with additional steps if needed. The loop ends when the planner returns no more tool calls or an abort/failure occurs.

Parameters:

goal_handle – Incoming action goal

Returns:

Action result