opencode-skills-collection 4.0.7 → 4.0.9

package/bundled-skills/n8n-agents/references/MEMORY.md

@@ -0,0 +1,139 @@
+# Agent memory
+
+Memory is a sub-node on the agent, wired via `ai_memory`. Without it, every invocation is stateless. With it, the agent holds a conversation across turns — and across executions, depending on type — keyed by whatever expression you bind to `sessionKey`.
+
+Memory node availability shifts between n8n versions, so confirm what's installed with `search_nodes({ query: 'memory' })`.
+
+---
+
+## The two non-negotiables
+
+1. **Plumb a stable key through.** Memory buckets by whatever you bind to `sessionKey`. The Chat Trigger fills `sessionId` automatically. For other triggers, derive a stable identifier (Slack `thread_ts`, a webhook conversation ID, a generated UUID, a multi-tenant composite) and forward it to memory and any session-keyed tools. Without consistency across the same conversation, memory never matches.
+2. **Default to `memoryBufferWindow`.** It persists across executions via n8n's internal store, keyed on `sessionKey`, and is the right choice for nearly every chat agent. Reach for Postgres/Redis only when memory must be read **outside** the agent.
+
+---
+
+## The memory types
+
+### `memoryBufferWindow` (the default)
+
+In-context memory of the last N exchanges, persisted across executions via n8n's store.
+
+```json
+{
+  "parameters": {
+    "sessionIdType": "customKey",
+    "sessionKey": "={{ $json.sessionId }}",
+    "contextWindowLength": 50
+  },
+  "type": "@n8n/n8n-nodes-langchain.memoryBufferWindow",
+  "typeVersion": 1.3,
+  "name": "Simple Memory"
+}
+```
+
+`contextWindowLength` is the number of exchanges retained. **The default is 5 — very low** for modern chat expectations, where users assume a conversation feels close to endless. **50 is a reasonable starting point.** Higher = more context but more tokens per turn.
+
+**Messages past the window are removed entirely.** Once the buffer fills, the oldest exchanges are dropped and the agent can't recall, search, or even know they existed. If a user said something 60 turns ago and the window is 50, that's gone from the agent's perspective. For recall beyond the window, raise `contextWindowLength`, or persist key facts in a Data Table that's read and injected into the system prompt.
+
+The "window" is a sliding cap on how many messages stay in context — **not** a scope on persistence. With `sessionIdType: 'customKey'` you bind the key to any expression (`{{ $json.sessionId }}`, a Slack `thread_ts`, a multi-tenant composite). Each user/thread/context gets its own bucket.
+
+### `memoryPostgresChat` / `memoryRedisChat`
+
+Reach for these only when memory must be queried or read **outside** the agent: displaying conversation history in your own UI, analytics on past chats, sharing memory across systems, or migrating instances cleanly.
+
+```json
+{
+  "parameters": {
+    "sessionIdType": "customKey",
+    "sessionKey": "={{ $json.sessionId }}"
+  },
+  "type": "@n8n/n8n-nodes-langchain.memoryPostgresChat",
+  "typeVersion": 1.3,
+  "name": "Postgres Memory"
+}
+```
+
+**Wrong for** the default chat case — `memoryBufferWindow` already survives across executions and is the cleaner pick.
+
+---
+
+## Custom patterns (Chat Memory Manager)
+
+Most agents don't need this. But when a fixed window isn't enough, the `@n8n/n8n-nodes-langchain.memoryManager` node operates against any wired memory backend and exposes three modes:
+
+- **`load`** (default) — read current memory into the workflow (for inspection, branching on size, feeding a summarizer).
+- **`insert`** — append a message. An optional `hideFromUI` flag covers messages that should affect the agent but not show in the chat UI.
+- **`delete`** — remove some or all messages.
+
+### Pattern: rolling summarization
+
+When a conversation runs long and you want the gist of older turns instead of dropping them:
+
+1. After each turn, `load` the buffer.
+2. If it's approaching the cap, route to a summarizer (otherwise no-op).
+3. Summarize the older turns with an LLM.
+4. `delete` the buffer.
+5. `insert` the summary as one message, plus the most recent few turns for continuity.
+
+The agent now sees `[summary of turns 1-40] + [recent 5 turns]`, paying far fewer input tokens while keeping long-history context.
+
+Other patterns built the same way: **prune by relevance** (`load` → filter → `delete` → `insert` the keepers), **inject runtime facts** (`insert` with `hideFromUI: true`), **reset on command** (`delete` all on `/clear`).
+
+The Memory Manager node is more recent than the rest of n8n's memory tooling — verify the modes against your installed version before relying on them in production.
+
+---
+
+## Session ID handling by trigger
+
+### Chat Trigger
+Sets `sessionId` automatically. Wire it everywhere consistently:
+- Memory: `sessionKey: ={{ $('Chat Trigger').first().json.sessionId }}`
+- Tools: `sessionId: ={{ $('Chat Trigger').first().json.sessionId }}` (**NOT** through `$fromAI`)
+- Storage keying: derive bucket keys / filenames from `sessionId` for trivial per-session cleanup.
+
+### Webhook trigger
+You manage it: the caller passes a header or body field (`body.sessionId`) and you forward it, or you issue one on first call and expect it back. Either way, it must be consistent across the whole conversation, including reconnections.
+
+### Manual / scheduled
+Usually no session. Use a stable identifier per "conversation" if one exists (ticket ID, thread ID); otherwise memory adds nothing — omit it.
+
+---
+
+## Memory and tools
+
+When a tool is invoked, the tool's sub-workflow does **NOT** see conversation memory — memory is the agent's context, not the tool's input. Pass needed context through `$fromAI` parameters explicitly. For session-keyed state, plumb `sessionId` and have the tool look up state from a Data Table or storage keyed by session.
+
+---
+
+## Memory and binary
+
+Memory stores **text turns**. Binary uploaded mid-conversation is NOT in memory — it's in the Chat Trigger's `files[]` for that turn only. The text memory captures that "the user mentioned uploading a file," but to actually use the file in a later tool call it must still be in storage and its key must be in **that** turn's system prompt. In practice, inject the session's file inventory into the system prompt every turn (loaded by `sessionId`). → **n8n-binary-and-data**.
+
+---
+
+## Common mistakes
+
+- **Hardcoding `sessionId: 'default'`** — all conversations share one bucket; memory becomes meaningless.
+- **Different `sessionId` on memory vs tools** — memory looks right but tools can't find related state.
+- **Unbounded `memoryBuffer` for chat** — token cost grows until timeout. Use BufferWindow with a sane limit.
+- **Adding memory where there's no session** — a "summarize this article" workflow doesn't need it.
+- **Expecting tools to see memory** — they see only their `$fromAI` parameters and plumbed context.
+- **Drift between the surface and memory** — if anything posts to the conversation outside the agent (a scheduled reply, a human writing directly), the agent operates on an incomplete view and will contradict messages it can't see. Whatever shows on the user-facing surface must also be `insert`ed into memory.
+
+---
+
+## Operational notes
+
+- **Memory size drives token cost.** A 15-turn buffer of 200-token messages is 3000 tokens of input every turn before the user even speaks. Plan for it.
+- **Rate limits.** A model that hits a limit fails mid-conversation; memory holds everything until then, and the next turn resumes (assuming session-id continuity).
+- **Concurrent sessions.** Persistent backends key on `sessionId`, so concurrent conversations don't interfere. Verify with two simultaneous tests.
+
+---
+
+## Cross-references
+
+- Where the agent fits → parent **SKILL.md**
+- Passing session-keyed state into tools → **SUBWORKFLOW_AS_TOOL.md**
+- Threading-as-session on chat surfaces → **CHAT_AGENT_PATTERNS.md**
+- Session-keyed file storage → **n8n-binary-and-data**

package/bundled-skills/n8n-agents/references/RAG.md

@@ -0,0 +1,102 @@
+# RAG (retrieval augmented generation)
+
+RAG in n8n is built on the LangChain primitives — document loaders, text splitters, embeddings, vector stores, retrievers, rerankers. They wire onto agents and chains the same way models and memory do (via `ai_*` connections).
+
+This reference is intentionally **thin**. The pieces work, but opinionated end-to-end recipes ("which vector store, which chunking, when to rerank") depend heavily on data shape and scale. Verify defaults against current n8n docs and your team's choices.
+
+---
+
+## Before you go vector: rule out cheaper lookups
+
+Not every retrieval problem needs a vector store. Three cheaper alternatives to eliminate first:
+
+- **Database or Data Table for exact lookups.** "Look up customer X's record", "fetch issue #1234", "get rows where status = 'open'" are NOT RAG problems — use a query directly. → **n8n-node-configuration** for DB nodes.
+- **Live search for freshness.** Information not in anything you've indexed (current news, live API state, anything time-sensitive) wants a search tool (Tavily, etc.), not RAG.
+- **Grep/file-browse tools for small or structured doc sets.** When the documents are few enough to list (a repo, a docs site, a few hundred markdown files), give the agent list/fetch/search tools and let it navigate. As an example, an agent browsing a GitHub repo can use `githubTool` (list files) plus an HTTP Request Tool against the repo contents endpoint to fetch raw text — no ingest, no embeddings, full source paths in citations.
+
+Reach for vector RAG when there are too many documents to list, queries are semantic rather than navigational, and you need similarity-based retrieval at low latency.
+
+---
+
+## Quickest start: in-memory vector store
+
+The fastest path to a working RAG flow uses `@n8n/n8n-nodes-langchain.vectorStoreInMemory` — no external service, no provisioning, no extra credential beyond whichever embedding / chat-model provider you already use. Data is lost on workflow restart, so it's right for prototypes, learning, and tests, not production.
+
+- **Ingest**: any trigger producing documents → Default Data Loader → Vector Store In-Memory (`mode: 'insert'`) with an Embeddings node wired into `ai_embedding`. A Form Trigger with a file-upload field is a quick way to drop in PDFs/CSVs without scripting.
+- **Query**: Chat Trigger → Agent → Vector Store In-Memory (`mode: 'retrieve-as-tool'`), same `memoryKey` and the same embedding model as ingest.
+
+When the data must survive restarts or scale beyond one instance, swap the in-memory node for a persistent store — the rest of the wiring stays the same.
+
+---
+
+## Vector RAG: the pieces
+
+n8n exposes the LangChain primitives as sub-nodes:
+
+- **Document loaders** (`documentDefaultDataLoader`) — pull from sources, optionally with metadata. Wires into a vector store's `ai_document`.
+- **Text splitters** (`textSplitter*`) — chunk into retrievable pieces. The default loader can do this inline for simple cases.
+- **Embeddings** (`embeddingsOpenAi`, `embeddingsCohere`, …) — turn chunks into vectors. Wires into `ai_embedding` on **both** ingest and query.
+- **Vector stores** — `vectorStoreInMemory`, `vectorStoreQdrant`, `vectorStoreSupabase` (Postgres pgvector), `vectorStorePinecone`. Each has modes: `insert` (ingest), `retrieve-as-tool` (the agent's `ai_tool` slot), and others for direct querying.
+
+The Default Data Loader's `metadata` field is **load-bearing**: anything you want to filter or display alongside results (source URL, document type, tenant ID) goes there. Without it, results are just chunks with no provenance.
+
+---
+
+## Vector RAG: two workflows
+
+### Ingest
+
+```
+[Trigger]
+  →  [Vector Store, mode: 'insert']
+        ai_document   <- [Default Data Loader (with metadata)]
+        ai_embedding  <- [Embeddings]
+```
+
+**Ingest does not have to be a tool.** Most often it's a separate scheduled workflow pre-populating the store on a cadence (e.g. nightly), or a webhook-triggered workflow. Wire it as an agent tool only when the documents change dynamically based on conversation (the agent learns something it should remember). For static or system-managed sets, a standalone workflow is simpler.
+
+### Query
+
+```
+[Chat / webhook trigger]
+  →  [Agent]
+        ai_tool          <- [Vector Store, mode: 'retrieve-as-tool']
+                               ai_embedding <- [Embeddings (SAME model as ingest)]
+        ai_languageModel <- [Chat Model]
+        ai_memory        <- [Memory]
+```
+
+Wired as `ai_tool`, the vector store becomes a tool the agent calls when it judges retrieval relevant. Wire retrieval directly into the main flow (pre-agent) only when **every** turn requires retrieval — rare in practice.
+
+**The embedding model must match.** Whatever embedded the documents on ingest must embed the query. Mismatched models produce garbage retrieval. Change models → re-ingest.
+
+---
+
+## Open decisions (verify per context)
+
+### Vector store selection
+
+- **In-memory** — zero ops, lost on restart. Prototypes and tests.
+- **Qdrant** — open-source, self-hostable, fast, mature in n8n.
+- **Postgres pgvector / Supabase** — ideal if you already run Postgres; SQL-side metadata filters and relational joins compose nicely.
+- **Pinecone** — fully managed, per-request pricing.
+
+### Embedding model
+
+OpenAI `text-embedding-3-large`, Cohere `embed-v3`, and open-source models are common. Cost, dimension count, and quality differ — choose carefully upfront to avoid re-embedding.
+
+### Retrieval-as-tool vs retrieval-before-agent
+
+- **Retrieve-as-tool**: the agent decides when retrieval is relevant AND phrases the query itself (reformulate, decompose, expand vague wording). One extra round trip per retrieval, but fewer wasted retrievals and a better hit rate.
+- **Retrieve-before-agent**: simpler and predictable, but pays the cost every turn AND uses the user's raw input as the query, so vague phrasing ("remind me how that thing works again?") goes straight into the search.
+
+Tool-based composes better in multi-capability agents (retrieval is one tool among several). Always-retrieve is fine for narrow Q&A bots where every question is a knowledge-base question.
+
+---
+
+## Cross-references
+
+- Agent fundamentals → parent **SKILL.md**
+- Wiring sub-workflows (and agentic retrieval tools) → **SUBWORKFLOW_AS_TOOL.md**
+- Tool naming/descriptions on retrieval tools → **TOOLS.md**
+- Data Tables as an alternative to a vector store for small structured data → **n8n-node-configuration**

package/bundled-skills/n8n-agents/references/STRUCTURED_OUTPUT.md

@@ -0,0 +1,163 @@
+# Structured output
+
+Non-negotiable: the output parser must **parse AND retry on failure**. Without retry, one malformed model response halts the entire workflow.
+
+The parser is the `@n8n/n8n-nodes-langchain.outputParserStructured` node, wired into the agent (or Basic LLM Chain) via the `ai_outputParser` connection.
+
+---
+
+## The pattern (node objects)
+
+The parser, with `autoFix` and its own fixer model:
+
+```json
+{
+  "parameters": {
+    "schemaType": "manual",
+    "inputSchema": "{ \"type\": \"object\", \"properties\": { \"score\": { \"type\": \"integer\", \"minimum\": 1, \"maximum\": 5 }, \"reason\": { \"type\": \"string\" } }, \"required\": [\"score\", \"reason\"] }",
+    "autoFix": true
+  },
+  "type": "@n8n/n8n-nodes-langchain.outputParserStructured",
+  "typeVersion": 1.3,
+  "name": "Structured Output Parser"
+}
+```
+
+Wire the parser to the agent, and a **coding-capable fixer model** to the parser:
+
+```json
+"Structured Output Parser": {
+  "ai_outputParser": [[{ "node": "AI Agent", "type": "ai_outputParser", "index": 0 }]]
+},
+"Fixer LLM": {
+  "ai_languageModel": [[{ "node": "Structured Output Parser", "type": "ai_languageModel", "index": 0 }]]
+}
+```
+
+On the agent, set `hasOutputParser: true` so the slot is active.
+
+---
+
+## Why a schema, not an example
+
+`schemaType: 'manual'` with a real JSON Schema is the default. `jsonSchemaExample` (`schemaType: 'fromJson'`) looks easier, but an example **cannot** express:
+
+- **Required vs optional fields** — an example is one snapshot; the parser can't tell which keys are mandatory.
+- **Enums** — `"category": "compliance"` doesn't constrain the model to `compliance | history | risk`; it will invent new categories.
+- **Numeric ranges** — `"score": 3` doesn't say `1-5`; the model returns `7` or `0.85` and passes.
+- **Array constraints** — min/max items, item-type uniformity.
+- **String formats** — email, UUID, ISO date, regex.
+
+A schema gives the model clearer rules and the parser real validation:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "decision":   { "type": "string", "enum": ["approve", "reject", "escalate"] },
+    "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+    "reasons": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "category": { "type": "string", "enum": ["compliance", "history", "risk"] },
+          "weight":   { "type": "number", "minimum": 0, "maximum": 1 },
+          "note":     { "type": "string" }
+        },
+        "required": ["category", "weight"]
+      }
+    },
+    "follow_up_required": { "type": "boolean" }
+  },
+  "required": ["decision", "confidence", "reasons", "follow_up_required"]
+}
+```
+
+Reach for `fromJson` + `jsonSchemaExample` only for one-off shapes you're certain will never grow constraints. Once a field needs to be optional, enum-ed, or range-bounded, you're rewriting the parser anyway — start with the schema.
+
+---
+
+## `autoFix: true` and the fixer model
+
+The model can produce almost-but-not-quite-valid JSON: trailing comma, missing field, wrong type, or JSON wrapped in a markdown code block. Without `autoFix`, the workflow halts. With it, the parser sends the bad output to a model with a "fix this" prompt, retries, and continues.
+
+The fixer is wired as a **separate** sub-node into the parser's `ai_languageModel` slot. **Use a coding-capable model** (Sonnet-class or better). Reconciling broken JSON against a schema with enums, ranges, and required fields is a structured-output / coding task — a weak or generic model routinely produces another malformed retry, defeating the point and burning tokens.
+
+When you want to customize the retry prompt, set `customizeRetryPrompt: true` and provide `prompt`. The placeholders `{instructions}`, `{completion}`, `{error}` are filled at retry time:
+
+```
+Instructions:
+--------------
+{instructions}
+--------------
+Completion:
+--------------
+{completion}
+--------------
+Above, the Completion did not satisfy the constraints in the Instructions.
+Error:
+--------------
+{error}
+--------------
+Please try again with an answer that satisfies the constraints.
+This is a structured output parser tool in n8n. Ensure the output format is correct to pass parsing.
+DO NOT wrap the output in a markdown code block.
+```
+
+Generally, leave the retry prompt as default unless you have a specific reason to override it.
+
+---
+
+## "DO NOT wrap the output in a markdown code block"
+
+This line is **load-bearing**. Models default to wrapping JSON in triple-backtick `json` fences, which breaks the parser. If you see parse failures on output that's clearly valid JSON inside a code block, this instruction is the fix — in both the retry prompt and, if the main model wraps aggressively, the **main** system prompt:
+
+> When responding with structured output, return raw JSON only. DO NOT wrap in markdown code blocks. DO NOT include any prose before or after the JSON.
+
+---
+
+## System prompt + parser: belt and suspenders
+
+The parser tells the model the schema; the system prompt should ALSO state the shape:
+
+```
+## Output Format
+Respond with a JSON object matching this exact shape:
+{ "score": 1-5 integer, "reason": "brief explanation" }
+
+ONLY output the JSON. No prose, no markdown wrapping.
+```
+
+It's repetition, but the model takes the system prompt seriously and reinforcement helps. The parser catches what slips through.
+
+---
+
+## Common parse failures and fixes
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| "Failed to parse output" but the text looks like JSON | Wrapped in a markdown code block | Add "DO NOT wrap in markdown" to retry prompt and system prompt |
+| Empty fields where the schema expects values | Model thinks it can omit unknowns | "Use empty string '' or null for unknown fields, never omit" |
+| Wrong types (number as string) | Schema/example wasn't typed clearly | Use a real number in the schema, not a string |
+| Truncated JSON (unclosed brace) | Hit max tokens mid-response | Increase max tokens, tighten the prompt to produce shorter output |
+| Field names paraphrased ("Score" vs "score") | Schema didn't pin the name | "Field names are exactly as shown" in the system prompt |
+| `autoFix` retries forever | Fixer model too weak for the schema | Swap in a coding-capable (Sonnet-class) fixer; tighten the retry prompt |
+
+---
+
+## When NOT to use a parser
+
+- **Free-form chat replies to the user** — conversational text doesn't need parsing.
+- **Tool calls only, no final structured output** — if the user-visible output is text, skip it.
+- **Trivial key-value extraction** — a Set node with `JSON.parse($json.output)` covers it.
+
+The parser is for when downstream nodes must consume strict JSON.
+
+---
+
+## Cross-references
+
+- Why and where to use agents at all → parent **SKILL.md**
+- The system-prompt half of structured output → **SYSTEM_PROMPT.md**
+- Block Kit / adaptive cards need the manual schema even more (union types) → **CHAT_AGENT_PATTERNS.md**

package/bundled-skills/n8n-agents/references/SUBWORKFLOW_AS_TOOL.md

@@ -0,0 +1,199 @@
+# Sub-workflow as agent tool
+
+The default agent-tool shape for anything beyond one node is the Tool Workflow node (`@n8n/n8n-nodes-langchain.toolWorkflow`). Any sub-workflow becomes a tool the agent calls, with typed inputs filled by `$fromAI()`. It composes with everything good about n8n: branching, error handling, sub-workflow reuse, native nodes, custom logic.
+
+For the sub-workflow primitive itself (Execute Workflow Trigger inputs/outputs, stateless design, naming, search-before-build), see **n8n-subworkflows** — this reference only covers the *agent-tool* angle.
+
+---
+
+## Why this is the default in n8n
+
+In raw LangChain a tool is a function. In n8n a tool can be a whole workflow, so it can:
+
+- Branch on input (IF / Switch).
+- Call multiple APIs and aggregate.
+- Have its own retries, fallbacks, error handling.
+- Call other sub-workflows.
+- Read/write Data Tables.
+- Be tested independently with `n8n_test_workflow` and pinned data.
+- Be reused across agents AND non-agent workflows.
+
+A function-as-tool can't do most of that without growing into a workflow anyway. n8n gives you the workflow primitive directly.
+
+---
+
+## The shape: two halves
+
+### 1. The sub-workflow side — an Execute Workflow Trigger with typed inputs
+
+```json
+{
+  "parameters": {
+    "workflowInputs": {
+      "values": [
+        { "name": "imagePrompt", "type": "string" },
+        { "name": "imageName",   "type": "string" },
+        { "name": "sessionId",   "type": "string" }
+      ]
+    }
+  },
+  "type": "n8n-nodes-base.executeWorkflowTrigger",
+  "typeVersion": 1.1,
+  "name": "When Executed by Another Workflow"
+}
+```
+
+Each declared input becomes a parameter the caller can fill. **The trigger must be in "Define Below" mode (typed fields), not passthrough** — passthrough has no schema, so the agent has nothing to fill via `$fromAI`. Two exceptions: (a) the sub-workflow needs binary (it can't be an agent tool directly — pre-stage to storage and pass storage keys as typed string fields, see **n8n-binary-and-data**), or (b) the tool takes no inputs at all (passthrough is the only option, and the tool's only decision is whether to invoke).
+
+Type enforcement happens on the **agent side** via the `type` argument of `$fromAI`, not at the trigger. Allowed types: `string`, `number`, `boolean`, `json`. Match them.
+
+### 2. The Tool Workflow side — points at the sub-workflow, binds params
+
+```json
+{
+  "parameters": {
+    "description": "Use to create a new image from a prompt OR edit an existing image. Pass imageName as the storage key (e.g. \"abc123.png\") to edit; leave empty to generate from scratch. Returns { imageUrl, imageKey }.",
+    "workflowId": { "__rl": true, "value": "<sub-workflow-id>", "mode": "list" },
+    "workflowInputs": {
+      "mappingMode": "defineBelow",
+      "value": {
+        "imagePrompt": "={{ $fromAI('imagePrompt', 'Detailed prompt describing the desired image', 'string') }}",
+        "imageName":   "={{ $fromAI('imageName', 'Storage key of an existing image to edit, or empty for new generation', 'string') }}",
+        "sessionId":   "={{ $('Chat Trigger').first().json.sessionId }}"
+      },
+      "schema": [
+        { "id": "imagePrompt", "displayName": "imagePrompt", "type": "string", "display": true },
+        { "id": "imageName",   "displayName": "imageName",   "type": "string", "display": true },
+        { "id": "sessionId",   "displayName": "sessionId",   "type": "string", "display": true }
+      ]
+    }
+  },
+  "type": "@n8n/n8n-nodes-langchain.toolWorkflow",
+  "typeVersion": 2.2,
+  "name": "Generate or edit image"
+}
+```
+
+Wire it into the agent with `ai_tool`:
+
+```json
+"Generate or edit image": {
+  "ai_tool": [[{ "node": "AI Agent", "type": "ai_tool", "index": 0 }]]
+}
+```
+
+The mapping is per-input:
+
+- **Agent-filled**: `={{ $fromAI('paramName', 'description', 'string') }}` — the agent decides.
+- **Plumbed**: `={{ $('SourceNode').first().json.field }}` — your workflow fills it.
+
+The `sessionId` line is critical: it is **NOT** an agent decision. Plumb it from the trigger so memory and session-keyed work stay consistent. **Never put `sessionId` behind `$fromAI`** — the agent will fabricate a UUID.
+
+---
+
+## What the agent sees (and doesn't)
+
+The agent sees the tool's **name** (the Tool Workflow node's name) and **description** (a parameter on the node) — both follow the **TOOLS.md** rules: specific, API-doc style, treated as prompt.
+
+It does **not** see: the sub-workflow internals, the sub-workflow's own name, or plumbed values like `sessionId`. Only `$fromAI` parameters appear in the tool schema. So you can refactor the sub-workflow heavily without changing what the agent sees.
+
+---
+
+## Worked example: one tool, two modes
+
+Goal: an agent that can generate or edit images. Both share most logic; they differ only in whether they download an existing image first.
+
+```
+[Execute Workflow Trigger: { imagePrompt, imageName, sessionId }]
+   ↓
+[Crypto: hash for new filename]
+   ↓
+[IF: imageName empty?]
+   ├── empty (generate)     → [Gemini: generate] ──┐
+   └── not empty (edit):                            │
+       [S3: Download by imageName]                  │
+          ↓                                         │
+       [Gemini: edit with downloaded binary] ───────┤
+                                                     ↓
+                                            [S3: Upload result]
+                                                     ↓
+                                            [Set: { imageUrl, imageKey }]
+```
+
+The agent picks the mode by what it puts in `imageName`. Two near-identical tools would have made selection harder — collapse them.
+
+---
+
+## Patterns inside the sub-workflow
+
+### Return a stable shape (it's a contract)
+
+The caller receives whatever the last node outputs. Pick a shape and keep it across modes:
+
+```json
+{ "imageUrl": "https://...", "imageKey": "abc123.png" }
+```
+
+Don't sometimes return `{ url, key }` and other times `{ result: { url, key } }`. The output shape is a contract every caller depends on — agents read it as part of the prompt, deterministic callers wire downstream nodes to specific paths. Drift breaks callers silently.
+
+For calls that fail "expectedly" (search with no results), return a branchable shape:
+
+```json
+{ "ok": false, "error": "no_results", "message": "No matches found for query" }
+```
+
+### When to throw instead: Stop and Error
+
+For unexpected-but-handled errors (auth failure, upstream down, unrecoverable input), use a `Stop and Error` node with a detailed message. It propagates as a thrown error: agents see a tool error and can retry/switch/report; deterministic callers catch it via `onError: 'continueErrorOutput'`. Pick this over `{ ok: false }` when the outcome is a true error, not a normal branch. For the full error story (4xx/5xx mapping, retries, error workflows) → **n8n-error-handling**.
+
+### Wire `onError: 'continueErrorOutput'` on fallible nodes
+
+Inside the sub-workflow, fallible nodes (HTTP, S3, DB) should set `onError: 'continueErrorOutput'` and route to a clean error response, so both agent and deterministic callers receive a structured error instead of a silent halt.
+
+### Treat the input contract as an API and document it
+
+The Execute Workflow Trigger's declared inputs ARE this tool's API. Document them in the sub-workflow's `description`:
+
+```
+Generates or edits an image.
+Inputs:
+  imagePrompt (string, required): detailed image description.
+  imageName   (string, optional): storage key of existing image to edit. Empty = new generation.
+  sessionId   (string, required): chat session ID, used for storage keying.
+Returns:
+  { imageUrl, imageKey }
+```
+
+### Keep tool sub-workflows discoverable
+
+Name them with a standard prefix (`Subworkflow:` or domain-specific). The Tool Workflow node references them by ID (stable), but humans browse the UI by name.
+
+---
+
+## Testing the sub-workflow independently
+
+A sub-workflow tool can be tested without the agent:
+
+1. Pin representative input on the Execute Workflow Trigger.
+2. `n8n_test_workflow` runs it with that pinned data.
+3. Verify the output shape matches what the agent will receive.
+
+---
+
+## When NOT to use sub-workflow as tool
+
+- **Simple one-node wrappers** — "call this endpoint and return" is shorter as an HTTP Request Tool.
+- **One-off code-only logic specific to this agent** — a few lines of pure JS/Python that exist nowhere else work fine as a Custom Code Tool (`.toolCode`, see **n8n-code-tool**). Decision rule: reusable business logic → sub-workflow; one-off agent-specific transform → Code Tool.
+- **Capabilities that already exist as native tool nodes** — don't wrap `slackTool` in a sub-workflow.
+
+For everything else, sub-workflow as tool is the default.
+
+---
+
+## Cross-references
+
+- The four tool types overview → **TOOLS.md**
+- How `$fromAI` descriptions affect behavior → **TOOLS.md** "`$fromAI()`"
+- The sub-workflow primitive (stateless design, naming, I/O) → **n8n-subworkflows**
+- Passing binary into tools → **n8n-binary-and-data**
+- The Custom Code Tool exception → **n8n-code-tool**