# agent_llamaindex

A RocketRide agent node that runs a single-agent ReAct loop using LlamaIndex.

## What it does

Receives a question on the `questions` lane, reasons step by step (selecting and
invoking tools as needed), and emits the final answer on the `answers` lane.

Uses **llama-index-core** for the ReAct scaffolding (`ReActChatFormatter`,
`ReActOutputParser`), but drives the loop by hand: the agent's LLM invocation channel
returns plain text synchronously, so each turn the node formats the ReAct prompt, calls
the host LLM with the stop word `Observation:`, and parses the model's
`Thought / Action / Action Input` (or final `Answer`) output. Tool execution happens
through the host's control-plane `call_tool`, not inside LlamaIndex. Connected tools are
wrapped as metadata-only `FunctionTool`s whose descriptions carry the tool's input JSON
schema.

Because the loop is text-based, it works with any LLM that can follow the ReAct format;
no native function-calling support is required. The agent still reaches multimodal
capabilities (OCR, transcription, image embedding, etc.) by invoking those as tools.

The loop runs up to 10 iterations. If no final `Answer` is produced within the budget,
the node returns `"Agent stopped after reaching the maximum number of reasoning steps."`.
If the model's output cannot be parsed as a ReAct step it is treated as a direct answer
(a leading `Thought:` is stripped so loop scaffolding does not leak to the user). A tool
call that raises is not fatal: the error is fed back to the model as the observation
(`{tool, error, type}`).

Progress is streamed over the `thinking` SSE lane ("Starting LlamaIndex agent...",
"Calling <tool>..."), and every tool step (`action`, `action_input`, `observation`) is
recorded in the returned reasoning stack.

The node registers with `classType: ["agent", "tool"]`. It runs standalone on the
questions lane and can also be invoked as a tool by parent agents (see "Using as a tool").

---

## Configuration

### Lanes

| Lane        | Direction | Description                        |
|-------------|-----------|------------------------------------|
| `questions` | in        | Questions for the agent to answer  |
| `answers`   | out       | The agent's final answer           |

### Fields

A single `default` profile with two fields:

| Field | Type | Description |
|---|---|---|
| `agent_description` | string | Default empty. What does this agent do? Describe its purpose and capabilities, this helps parent agents select and invoke it correctly. |
| `instructions` | array | Additional instructions to guide the agent. |
| `profile` | string | Default "default".  |

---

## Invoke channels

Control-plane channels the agent uses during its reasoning loop:

| Channel | Required    | Description                                             |
|---------|-------------|---------------------------------------------------------|
| `llm`   | yes (min 1) | LLM the agent thinks with                               |
| `tool`  | no (min 0)  | Tools available to the agent (via control-plane invoke) |

---

## Using as a tool

The node exposes itself as `<nodeId>.run_agent`, so parent agents can delegate to it in
hierarchical pipelines. The configured `agent_description` is prepended to the tool
description to help the parent pick the right sub-agent.

| Direction | Shape                                                       |
|-----------|-------------------------------------------------------------|
| Input     | `{query: string, context?: object}` (`query` must be a non-empty string) |
| Output    | `{content, meta, stack}`                                    |

An optional `context` object is passed to the sub-agent as a context entry of type
`RocketRide.agent.tool_context.v1`. When invoked as a tool the answer is returned to the
caller instead of being emitted on the `answers` lane.

---

## Upstream docs

- [LlamaIndex agents](https://docs.llamaindex.ai/en/stable/understanding/agent/)

---

<!-- ROCKETRIDE:GENERATED:PARAMS START -->
<!-- Generated by nodes:docs-generate. Do not edit by hand. -->

## Schema

| Field | Type | Description | Default |
|---|---|---|---|
| `agent_description` | `string` | **Agent description**<br/>What does this agent do? Describe its purpose and capabilities, this helps parent agents select and invoke it correctly. | `""` |
| `agent_llamaindex.profile` | `string` | **Profile** | `"default"` |
| `instructions` | `array` | **Instructions**<br/>Additional instructions to guide the agent. |  |

## Dependencies

- `llama-index-core`

## Source

[<svg viewBox="0 0 16 16" width="15" height="15" fill="currentColor" aria-hidden="true" style="vertical-align:-0.15em;margin-right:0.35em"><path d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"/></svg> View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/agent_llamaindex)
<!-- ROCKETRIDE:GENERATED:PARAMS END -->