# AI Agent Nodes & Real-Time Stream Piping
### *Transforming Nodestr from a modular prompt IDE into a living, autonomous multi-agent execution pipeline.*
Nodestr's **AI Agent Node** architecture brings spatial execution directly to your canvas. Instead of copying and pasting compiled prompts into external web interfaces, you can now trigger, stream, and chain autonomous AI agents directly within the visual node graph—powered by your own API credentials or local offline models.
---
## 1. Overview & Spatial AI Concept
Traditional AI workflows are split between two disconnected worlds:
1. **Prompt Builders & Scratchpads**: Where instructions and variables are drafted in isolation.
2. **Chat UIs & Playgrounds**: Where generation occurs in single-threaded vertical chat feeds without visual lineage.
Nodestr unifies prompt authoring and execution into a **single spatial canvas**:
- **Living Execution Pipeline**: An AI Agent Node receives instructions, variables, and context from upstream canvas nodes, streams generation in real time, and exposes its live output downstream to other agents, the Primary Output Hub, or document exporters.
- **Visual Multi-Agent Workflows**: Break complex reasoning into modular steps—such as Outline Agent → Draft Agent → Critic Agent → Polish Agent—all connected with visible, reactive noodles.
- **Zero Lock-In & Zero Markup**: Nodestr never charges per-token markups or routes your prompts through intermediary proprietary proxy servers. All requests stream directly from your browser to provider endpoints using native streaming APIs (Server-Sent Events) or to local offline instances.
---
## 2. Node Anatomy & Port Handles
Every AI Agent Node features an intuitive, color-coded structure designed for clear visual routing:
### Header Bar & Status Controls
- **Node Title & Icon**: Customizable agent name (e.g. "Research Analyst", "Drafting Specialist") with a dedicated violet AI badge.
- **Provider & Model Badge**: Displays the active model family (e.g. DeepSeek V3, Claude 3.5 Sonnet, Gemini 2.5 Flash, or Local Llama 3).
- **Execution Actions**:
- **`▶ Run` / `■ Stop`**: Trigger individual agent execution or cleanly stop in-flight generation at any time with the Stop button.
- **`Run Upstream Pipeline`**: Automatically resolves all upstream dependencies, detects circular references, and executes the entire pipeline in sequence.
- **`[ 👁 Expand ]`**: Opens the enlarged modal editor with rich Markdown rendering, full-screen prompt editing, and telemetry breakdown.
### Input Ports (Left Edge)
1. **Task Directive (Amber / Top)**: Primary user directive or task instructions. Supports variable interpolation tokens.
2. **System Persona (Slate / Middle)**: Persona definition, behavioral constraints, tone guides, or system instructions.
3. **Context Reference (Emerald Green / Bottom)**: Background reference material, upstream research data, or connected table records.
### Output Port (Right Edge)
- **Response Output (Signature Purple)**: Transmits the generated markdown response downstream. Downstream agents, Custom nodes, Output Hubs, or Exporter nodes can consume this output in real time.
---
## 3. Client-Side Key Protection & Security
Security and user sovereignty are paramount. Nodestr connects directly from your browser to each AI provider:
### In-Browser Key Protection
- **Zero Server Storage**: Your third-party API keys are **never transmitted to or stored on Nodestr servers**.
- **Hardware-Backed In-Browser Encryption**: Keys are encrypted client-side directly in your browser using secure local storage.
- **Non-Extractable Master Keys**: Encryption keys are scoped to your local browser origin and cannot be extracted via script inspection.
- **Tamper Protection**: Ciphertext tampering immediately invalidates decryption, preventing key injection attacks.
- **Cloud Masking**: When cloud workspace syncing occurs, API keys and encrypted key vaults are strictly excluded from workspace JSON payloads.
> [!IMPORTANT]
> Because API keys never leave your browser, you retain 100% control over billing, rate limits, and data retention policies directly with each AI provider.
---
## 4. Supported Providers & Models
Nodestr natively integrates with the industry's leading AI providers across both frontier cloud reasoning engines and high-speed inference hosts:
| Provider | Notable Preset Models | Best Used For |
| :--- | :--- | :--- |
| **DeepSeek** | DeepSeek V3, DeepSeek R1 (Reasoning) | Complex mathematical reasoning, coding, cost-effective deep thinking |
| **Google Gemini** | Gemini 2.5 Flash, Gemini 1.5 Pro | Massive context windows (up to 1M tokens), multimodal analysis, high throughput |
| **OpenAI** | GPT-4o, GPT-4o-mini, o1-preview | Structured reasoning, creative prose, instruction following |
| **Anthropic Claude** | Claude 3.5 Sonnet, Claude 3.5 Haiku | Nuanced literary drafting, sophisticated critique, code generation |
| **Groq** | Llama 3.3 70B, Mixtral 8x7B | Ultra-low latency inference (>500 tokens/sec), real-time streaming pipelines |
| **OpenRouter** | 200+ Unified Models | Accessing any frontier or open-source model through a single unified API key |
---
## 5. Running Local LLMs (Ollama & LM Studio)
For complete privacy, zero API costs, and offline development, Nodestr provides native support for local inference engines:
### Ollama Integration (`http://localhost:11434`)
1. Download and run Ollama on your machine (`ollama serve`).
2. Pull your model of choice (e.g. `ollama run llama3:8b` or `ollama run mistral`).
3. In Nodestr, open **Settings → AI Providers**, select **Ollama**, and click **"Discover Local Models"**.
4. Nodestr queries the local discovery endpoint (`/api/tags`), automatically populating the model dropdown with your installed models.
5. In an AI Agent Node, select your local model and click **Run**. Prompts stream directly via localhost with **zero external network requests**.
### LM Studio & OpenAI-Compatible Local Servers
- Connect to LM Studio or custom llama.cpp servers via OpenAI-compatible endpoints (typically `http://localhost:1234/v1`).
- Custom context window ceilings and temperature sliders give you granular control over local hardware utilization.
> [!TIP]
> Local models are 100% free, run completely offline, and maintain total data confidentiality—ideal for proprietary manuscripts, legal documents, and medical research.
---
## 6. Multi-Step Pipeline Execution & Stream Piping
The true power of AI Agent Nodes emerges when chaining multiple agents into **autonomous multi-tier pipelines**:
### Multi-Step Pipeline Execution
When you click **"Run Upstream Pipeline"** on any downstream agent or terminal node:
1. **Dependency Analysis**: Nodestr traverses the graph backwards from the target node, constructing an execution dependency tree.
2. **Cycle Detection**: The engine automatically detects circular dependencies and halts with a clear error trace before execution begins.
3. **Execution Order**: Agents are sorted such that upstream producers always execute and finalize before downstream consumers begin.
4. **Fluid Real-Time Streaming**: Streaming tokens are rendered smoothly at 60fps, giving you instant readability as your agent writes.
### Inline Variable Token Interpolation
Downstream agents and Custom Nodes can dynamically interpolate upstream agent responses using variable pills or double-curly syntax:
- `{{Agent Title}}` or `[+ Response]`: Injects the complete compiled response of the connected upstream agent.
- `{{Agent Title.summary}}`: Injects labeled output sections if structured output was generated.
- Unmatched or in-flight tokens gracefully maintain safe fallbacks without throwing runtime errors.
---
## 7. Exporting Outputs & Document Generation
AI Agent Nodes seamlessly integrate with Nodestr's compilation and export ecosystem:
1. **Primary Output Hub (Purple Attribution)**:
- When an AI Agent Node's response port connects to an Output Hub, its output is rendered with distinct purple attribution bars in both the Raw and **`[ 👁 Rich Preview ]`** tabs.
- Multiple agents compile in spatial reading order into a cohesive multi-part manuscript.
2. **Document Exporter Node Integration**:
- Wire an AI Agent Node directly into a **Document Exporter Node** (`Document / Text` port).
- Export generated multi-agent research or drafts to **Microsoft Word (`.docx`)**, **PDF (`.pdf`)**, or **Markdown (`.md`)**.
- With a single click, push generated text directly into a native **Google Doc** via Google Drive Cloud Export.
---
## 8. Usage Telemetry & Cost Transparency
Nodestr includes granular usage telemetry so you can monitor consumption and budget:
- **Per-Run Micro-Stats**: After every generation, the agent node footer displays:
- **Latency**: Duration in milliseconds (e.g. `1,240ms`).
- **Token Counts**: Prompt tokens, completion tokens, and total tokens.
- **Calculated Cost**: Estimated cost in USD calculated with 6-decimal precision based on official provider pricing models.
- **Aggregated Macro Ledger**: In the AI Settings drawer, review global token consumption across all providers, models, and workspaces—with 1-click **CSV Export** for accounting and record keeping.
---
## 9. Troubleshooting & Quick Fixes
| Issue | Potential Cause | Solution |
| :--- | :--- | :--- |
| **Ollama connection fails** | Ollama is not running or localhost is blocked | Start Ollama locally with `ollama serve` and verify `http://localhost:11434` is accessible in your browser. |
| **API Key error (401/403)** | Key is inactive, mistyped, or lacks provider credits | Open **AI Settings**, re-enter your key, and click **Test Connection** to verify your account balance. |
| **Circular pipeline warning** | Two or more agents are wired in an endless loop | Disconnect the feedback wire so data flows in a single direction (Agent A → Agent B → Agent C). |