# agent_rocketride RocketRide's native wave-planning agent ("RocketRide Wave"), an experimental agent node that plans each step as a wave of parallel tool calls and uses keyed memory to stay token-efficient. ## What it does Runs an iterative planning loop built directly on the RocketRide architecture: there is no third-party agent framework underneath. Each iteration the LLM plans a batch of tool calls, all tools in the batch run in parallel, results are stored in keyed memory, and the loop repeats until the LLM signals `done` or `max_waves` is reached. Token efficiency comes from a two-level memory model: the planning prompt only ever sees structural summaries of tool results (field names, array lengths, sample values). Raw data stays in the memory store and is pulled on demand via the built-in `memory.peek` tool (JMESPath extraction, implemented with the **jmespath** library) or embedded into the final answer via `{{memory.ref:...}}` template tags resolved at render time. The node has `classType` `["agent", "tool"]`: besides answering questions on its own lane, it exposes a `run_agent` tool so parent agents can invoke it for hierarchical agent orchestration. This node is **experimental**. --- ## Configuration | 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's planning and responses. | | `max_waves` | integer | Default 10. Maximum number of planning iterations before the synthesis fallback fires. | | `profile` | string | Default "default". | A single `default` profile exposes all three fields. --- ## Connections ### Invoke channels (control-plane) | Channel | Required | Description | |----------|--------------|---------------------------------------------------| | `llm` | yes (max 1) | LLM used by the agent for planning and synthesis | | `tool` | no | Tools available to the agent via control-plane invoke | | `memory` | yes (max 1) | Keyed memory store for the agent | The `memory` channel is required. Connect a memory node before running. ### Lanes | Lane | Direction | Description | |-------------|-----------|-----------------------------------------------| | `questions` | in | Incoming questions that start an agent run | | `answers` | out | Final answer emitted when the run completes | --- ## Agent-callable tools ### `run_agent` Exposes this node as a tool to parent agents (addressed as `.run_agent`). | Field | Type | Description | |-----------|--------------------|-------------------------------------------------------| | `query` | string (required) | The question for the agent. Must be a non-empty string. | | `context` | object (optional) | Extra context passed to the agent as a JSON context block. | Output: `{content, meta, stack}`. When invoked as a tool, the result is returned to the caller instead of being emitted on the `answers` lane. ### `memory.peek` Built-in tool executed locally inside the executor (not routed through the tool pipeline). Lets the LLM extract specific values from memory on demand. | Field | Type | Description | |----------|--------------------|-----------------------------------------------------------------------------| | `key` | string (required) | Memory key to read from (e.g. `wave-0.r1`). | | `path` | string (optional) | JMESPath expression to extract a specific field or slice (e.g. `rows[0:5].city`). Arrays are capped at 50 items per call. | | `offset` | integer (optional) | Character offset for chunk reading (default `0`). Only when `path` is omitted. | | `length` | integer (optional) | Characters to return for chunk reading (default `8000`). Only when `path` is omitted. | Peek results are not stored back into memory. The LLM should capture extracted values in `scratch` and then remove the peek result key in the same response. --- ## How the wave loop works 1. **Plan**: one LLM call per wave. The prompt contains all connected tool descriptors (one compact JSON line each, plus the `memory.peek` descriptor), the operator's `instructions`, memory-usage rules, persistent scratch notes, and structural summaries of all prior results. The LLM responds with either `{"thought", "scratch", "remove", "tool_calls": [...]}` or `{"thought", "scratch", "remove", "done": true, "answer": "..."}`. 2. **Execute**: all tool calls in the batch run concurrently (max 8 threads, 120 s timeout each). Each result is stored in memory under a key like `wave-0.r0` and only a structural summary is kept in the wave history. `{{memory.ref:...}}` tags inside tool arguments are resolved before invocation, so the LLM can compose tool inputs from previously stored results. 3. **Prune**: memory keys listed in the LLM's `remove` field are cleared from the store and stripped from wave history, keeping the planning prompt lean on long-running tasks. Tool errors are returned to the LLM as context rather than aborting the run, so it can recover or change approach. 4. **Repeat** until `done: true` or `max_waves` is hit. On `done`, any `{{memory.ref:...}}` references in the answer are resolved before delivery. If the wave limit is reached without `done`, a synthesis fallback asks the LLM to produce a best-effort answer from all gathered result summaries. An empty plan (no `tool_calls`, no `done`) also short-circuits to synthesis instead of looping. Progress is surfaced to the UI over the `thinking` SSE lane: per-wave planning status, the LLM's one-sentence `thought`, which tools are running, and step completion. --- ## Memory system The agent uses a two-level memory model to stay token-efficient: - **Structural summaries**: always visible in the planning prompt as "Previous tool results". Show data shape (field names, array lengths, first rows, truncated string previews with char counts) without loading raw values into context. - **`memory.peek`**: built-in tool the LLM calls on demand to extract specific values via JMESPath (e.g. `rows[0:5].city`). Arrays are capped at 50 items per call; large raw values can be paged as text with `offset`/`length` (default chunk 8000 chars, with `total_chars` reported so the LLM can page). Peek results are not stored back into memory. - **`{{memory.ref:key}}`**: embeds the stored value by key at render time. An exact full-string match returns the native type (dict, list, and so on); inside larger strings the value is substituted as text. - **`{{memory.ref:key:format}}`**: renders bulk data in a specific format without ever loading it into LLM context. - **`{{memory.ref:key:format:path}}`**: extracts a nested JMESPath path from the stored value before formatting (e.g. `rows[0:20]`). The path is the last segment, so it may itself contain colons (slice notation). All variants are resolved by the executor at render time, in tool arguments and in the final answer. The LLM also maintains a **scratch** field: persistent working notes (memory keys, extracted values, intermediate calculations) that carry forward across waves. When the LLM is done with a result key it signals `remove: ["wave-0.r0"]` to evict it. --- ## Formats Built-in formatters for `{{memory.ref:key:format}}` (no LLM call): | Format | Output | |------------------|-----------------------------------------------------------| | `markdown_table` | Markdown table with header and separator rows | | `html_table` | HTML `` with ``/``, values escaped | | `csv` | CSV with header row (proper quoting via Python `csv` module) | | `json` | Pretty-printed JSON | | `text` | Plain-text `key: value` blocks per row | Tabular formatters accept several input shapes: a bare list of dicts, `{"rows": [...]}` (standard database-driver output), a dict with a single list-of-dicts value, or a single dict treated as a one-row table. Any unknown format string (e.g. `"bullet list"`) falls back to a secondary LLM call that renders the data in the requested style. --- ## Schema | Field | Type | Description | Default | |---|---|---|---| | `agent_description` | `string` | **Agent description**
What does this agent do? Describe its purpose and capabilities, this helps parent agents select and invoke it correctly. | `""` | | `agent_rocketride.profile` | `string` | **Profile** | `"default"` | | `instructions` | `array` | **Instructions**
Additional instructions to guide the agent's planning and responses. | | | `max_waves` | `integer` | **Max Waves**
Maximum number of planning iterations before the synthesis fallback fires. | `10` | ## Dependencies - `jmespath` ## Source [ View source](https://github.com/rocketride-org/rocketride-server/tree/develop/nodes/src/nodes/agent_rocketride)