feat: Oracle CRM Page, Synthetic Client Data and Live Snapshot when hitting emotion hotpoint
This commit is contained in:
Sagnik
Binary file not shown.
364
.Agent Context/Tech/README-Open Multi-Agent.md
Normal file
364
.Agent Context/Tech/README-Open Multi-Agent.md
Normal file
@@ -0,0 +1,364 @@
|
||||
# Open Multi-Agent
|
||||
|
||||
The lightweight multi-agent orchestration engine for TypeScript. Three runtime dependencies, zero config, goal to result in one `runTeam()` call.
|
||||
|
||||
CrewAI is Python. LangGraph makes you draw the graph by hand. `open-multi-agent` is the `npm install` you drop into an existing Node.js backend when you need a team of agents to work on a goal together. Nothing more, nothing less.
|
||||
|
||||
3 runtime dependencies · 35 source files · Deploys anywhere Node.js runs · Mentioned in [Latent Space](https://www.latent.space/p/ainews-a-quiet-april-fools) AI News (top AI engineering newsletter, 170k+ subscribers)
|
||||
|
||||
[](https://github.com/JackChen-me/open-multi-agent/stargazers)
|
||||
[](./LICENSE)
|
||||
[](https://www.typescriptlang.org/)
|
||||
[](https://github.com/JackChen-me/open-multi-agent/actions)
|
||||
|
||||
**English** | [中文](./README_zh.md)
|
||||
|
||||
## What you actually get
|
||||
|
||||
- **Goal to result in one call.** `runTeam(team, "Build a REST API")` kicks off a coordinator agent that decomposes the goal into a task DAG, resolves dependencies, runs independent tasks in parallel, and synthesizes the final output. No graph to draw, no tasks to wire up.
|
||||
- **TypeScript-native, three runtime dependencies.** `@anthropic-ai/sdk`, `openai`, `zod`. That is the whole runtime. Embed in Express, Next.js, serverless functions, or CI/CD pipelines. No Python runtime, no subprocess bridge, no cloud sidecar.
|
||||
- **Multi-model teams.** Claude, GPT, Gemini, Grok, Copilot, or any OpenAI-compatible local model (Ollama, vLLM, LM Studio, llama.cpp) in the same team. Run the architect on Opus 4.6, the developer on GPT-5.4, the reviewer on local Gemma 4, all in one `runTeam()` call. Gemini ships as an optional peer dependency: `npm install @google/genai` to enable.
|
||||
|
||||
Other features (structured output, task retry, human-in-the-loop, lifecycle hooks, loop detection, observability) live below the fold and in [`examples/`](./examples/).
|
||||
|
||||
## Philosophy: what we build, what we don't
|
||||
|
||||
Our goal is to be the simplest multi-agent framework for TypeScript. Simplicity does not mean closed. We believe the long-term value of a framework is the size of the network it connects to, not its feature checklist.
|
||||
|
||||
**We build:**
|
||||
- A coordinator that decomposes a goal into a task DAG.
|
||||
- A task queue that runs independent tasks in parallel and cascades failures to dependents.
|
||||
- A shared memory and message bus so agents can see each other's output.
|
||||
- Multi-model teams where each agent can use a different LLM provider.
|
||||
|
||||
**We don't build:**
|
||||
- **Agent handoffs.** If agent A needs to transfer mid-conversation to agent B, use [OpenAI Agents SDK](https://github.com/openai/openai-agents-python). In our model, each agent owns one task end-to-end, with no mid-conversation transfers.
|
||||
- **State persistence / checkpointing.** Not planned for now. Adding a storage backend would break the three-dependency promise, and our workflows run in seconds to minutes, not hours. If real usage shifts toward long-running workflows, we will revisit.
|
||||
|
||||
**Tracking:**
|
||||
- **MCP support.** Next up, see [#86](https://github.com/JackChen-me/open-multi-agent/issues/86).
|
||||
- **A2A protocol.** Watching, will move when production adoption is real.
|
||||
|
||||
See [`DECISIONS.md`](./DECISIONS.md) for the full rationale.
|
||||
|
||||
## How is this different from X?
|
||||
|
||||
**vs. [LangGraph JS](https://github.com/langchain-ai/langgraphjs).** LangGraph is declarative graph orchestration: you define nodes, edges, and conditional routing, then `compile()` and `invoke()`. `open-multi-agent` is goal-driven: you declare a team and a goal, a coordinator decomposes it into a task DAG at runtime. LangGraph gives you total control of topology (great for fixed production workflows). This gives you less typing and faster iteration (great for exploratory multi-agent work). LangGraph also has mature checkpointing; we do not.
|
||||
|
||||
**vs. [CrewAI](https://github.com/crewAIInc/crewAI).** CrewAI is the mature Python choice. If your stack is Python, use CrewAI. `open-multi-agent` is TypeScript-native: three runtime dependencies, embeds directly in Node.js without a subprocess bridge. Roughly comparable capability on the orchestration side. Choose on language fit.
|
||||
|
||||
**vs. [Vercel AI SDK](https://github.com/vercel/ai).** AI SDK is the LLM call layer: a unified TypeScript client for 60+ providers with streaming, tool calls, and structured outputs. It does not orchestrate multi-agent teams. `open-multi-agent` sits on top when you need that. They compose: use AI SDK for single-agent work, reach for this when you need a team.
|
||||
|
||||
## Used by
|
||||
|
||||
`open-multi-agent` is a new project (launched 2026-04-01, MIT, 5,500+ stars). The ecosystem is still forming, so the list below is short and honest:
|
||||
|
||||
- **[temodar-agent](https://github.com/xeloxa/temodar-agent)** (~50 stars). WordPress security analysis platform by [Ali Sünbül](https://github.com/xeloxa). Uses our built-in tools (`bash`, `file_*`, `grep`) directly in its Docker runtime. Confirmed production use.
|
||||
- **[rentech-quant-platform](https://github.com/rookiecoderasz/rentech-quant-platform).** Multi-agent quant trading research platform. Five pipelines plus MCP integrations, built on top of `open-multi-agent`. Early signal, very new.
|
||||
- **Cybersecurity SOC (home lab).** A private setup running Qwen 2.5 + DeepSeek Coder entirely offline via Ollama, building an autonomous SOC pipeline on Wazuh + Proxmox. Early user, not yet public.
|
||||
|
||||
Using `open-multi-agent` in production or a side project? [Open a discussion](https://github.com/JackChen-me/open-multi-agent/discussions) and we will list it here.
|
||||
|
||||
## Quick Start
|
||||
|
||||
Requires Node.js >= 18.
|
||||
|
||||
```bash
|
||||
npm install @jackchen_me/open-multi-agent
|
||||
```
|
||||
|
||||
Set the API key for your provider. Local models via Ollama require no API key — see [example 06](examples/06-local-model.ts).
|
||||
|
||||
- `ANTHROPIC_API_KEY`
|
||||
- `OPENAI_API_KEY`
|
||||
- `GEMINI_API_KEY`
|
||||
- `XAI_API_KEY` (for Grok)
|
||||
- `GITHUB_TOKEN` (for Copilot)
|
||||
|
||||
**CLI (`oma`).** For shell and CI, the package exposes a JSON-first binary. See [docs/cli.md](./docs/cli.md) for `oma run`, `oma task`, `oma provider`, exit codes, and file formats.
|
||||
|
||||
Three agents, one goal — the framework handles the rest:
|
||||
|
||||
```typescript
|
||||
import { OpenMultiAgent } from '@jackchen_me/open-multi-agent'
|
||||
import type { AgentConfig } from '@jackchen_me/open-multi-agent'
|
||||
|
||||
const architect: AgentConfig = {
|
||||
name: 'architect',
|
||||
model: 'claude-sonnet-4-6',
|
||||
systemPrompt: 'You design clean API contracts and file structures.',
|
||||
tools: ['file_write'],
|
||||
}
|
||||
|
||||
const developer: AgentConfig = { /* same shape, tools: ['bash', 'file_read', 'file_write', 'file_edit'] */ }
|
||||
const reviewer: AgentConfig = { /* same shape, tools: ['file_read', 'grep'] */ }
|
||||
|
||||
const orchestrator = new OpenMultiAgent({
|
||||
defaultModel: 'claude-sonnet-4-6',
|
||||
onProgress: (event) => console.log(event.type, event.agent ?? event.task ?? ''),
|
||||
})
|
||||
|
||||
const team = orchestrator.createTeam('api-team', {
|
||||
name: 'api-team',
|
||||
agents: [architect, developer, reviewer],
|
||||
sharedMemory: true,
|
||||
})
|
||||
|
||||
// Describe a goal — the framework breaks it into tasks and orchestrates execution
|
||||
const result = await orchestrator.runTeam(team, 'Create a REST API for a todo list in /tmp/todo-api/')
|
||||
|
||||
console.log(`Success: ${result.success}`)
|
||||
console.log(`Tokens: ${result.totalTokenUsage.output_tokens} output tokens`)
|
||||
```
|
||||
|
||||
What happens under the hood:
|
||||
|
||||
```
|
||||
agent_start coordinator
|
||||
task_start architect
|
||||
task_complete architect
|
||||
task_start developer
|
||||
task_start developer // independent tasks run in parallel
|
||||
task_complete developer
|
||||
task_complete developer
|
||||
task_start reviewer // unblocked after implementation
|
||||
task_complete reviewer
|
||||
agent_complete coordinator // synthesizes final result
|
||||
Success: true
|
||||
Tokens: 12847 output tokens
|
||||
```
|
||||
|
||||
## Three Ways to Run
|
||||
|
||||
| Mode | Method | When to use |
|
||||
|------|--------|-------------|
|
||||
| Single agent | `runAgent()` | One agent, one prompt — simplest entry point |
|
||||
| Auto-orchestrated team | `runTeam()` | Give a goal, framework plans and executes |
|
||||
| Explicit pipeline | `runTasks()` | You define the task graph and assignments |
|
||||
|
||||
For MapReduce-style fan-out without task dependencies, use `AgentPool.runParallel()` directly. See [example 07](examples/07-fan-out-aggregate.ts).
|
||||
|
||||
## Examples
|
||||
|
||||
16 runnable scripts in [`examples/`](./examples/). Start with these four:
|
||||
|
||||
- [02 — Team Collaboration](examples/02-team-collaboration.ts): `runTeam()` coordinator pattern.
|
||||
- [06 — Local Model](examples/06-local-model.ts): Ollama and Claude in one pipeline via `baseURL`.
|
||||
- [09 — Structured Output](examples/09-structured-output.ts): any agent returns Zod-validated JSON.
|
||||
- [11 — Trace Observability](examples/11-trace-observability.ts): `onTrace` spans for LLM calls, tools, and tasks.
|
||||
|
||||
Run any with `npx tsx examples/02-team-collaboration.ts`.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ OpenMultiAgent (Orchestrator) │
|
||||
│ │
|
||||
│ createTeam() runTeam() runTasks() runAgent() getStatus() │
|
||||
└──────────────────────┬──────────────────────────────────────────┘
|
||||
│
|
||||
┌──────────▼──────────┐
|
||||
│ Team │
|
||||
│ - AgentConfig[] │
|
||||
│ - MessageBus │
|
||||
│ - TaskQueue │
|
||||
│ - SharedMemory │
|
||||
└──────────┬──────────┘
|
||||
│
|
||||
┌─────────────┴─────────────┐
|
||||
│ │
|
||||
┌────────▼──────────┐ ┌───────────▼───────────┐
|
||||
│ AgentPool │ │ TaskQueue │
|
||||
│ - Semaphore │ │ - dependency graph │
|
||||
│ - runParallel() │ │ - auto unblock │
|
||||
└────────┬──────────┘ │ - cascade failure │
|
||||
│ └───────────────────────┘
|
||||
┌────────▼──────────┐
|
||||
│ Agent │
|
||||
│ - run() │ ┌──────────────────────┐
|
||||
│ - prompt() │───►│ LLMAdapter │
|
||||
│ - stream() │ │ - AnthropicAdapter │
|
||||
└────────┬──────────┘ │ - OpenAIAdapter │
|
||||
│ │ - CopilotAdapter │
|
||||
│ │ - GeminiAdapter │
|
||||
│ │ - GrokAdapter │
|
||||
│ └──────────────────────┘
|
||||
┌────────▼──────────┐
|
||||
│ AgentRunner │ ┌──────────────────────┐
|
||||
│ - conversation │───►│ ToolRegistry │
|
||||
│ loop │ │ - defineTool() │
|
||||
│ - tool dispatch │ │ - 5 built-in tools │
|
||||
└───────────────────┘ └──────────────────────┘
|
||||
```
|
||||
|
||||
## Built-in Tools
|
||||
|
||||
| Tool | Description |
|
||||
|------|-------------|
|
||||
| `bash` | Execute shell commands. Returns stdout + stderr. Supports timeout and cwd. |
|
||||
| `file_read` | Read file contents at an absolute path. Supports offset/limit for large files. |
|
||||
| `file_write` | Write or create a file. Auto-creates parent directories. |
|
||||
| `file_edit` | Edit a file by replacing an exact string match. |
|
||||
| `grep` | Search file contents with regex. Uses ripgrep when available, falls back to Node.js. |
|
||||
|
||||
## Tool Configuration
|
||||
|
||||
Agents can be configured with fine-grained tool access control using presets, allowlists, and denylists.
|
||||
|
||||
### Tool Presets
|
||||
|
||||
Predefined tool sets for common use cases:
|
||||
|
||||
```typescript
|
||||
const readonlyAgent: AgentConfig = {
|
||||
name: 'reader',
|
||||
model: 'claude-sonnet-4-6',
|
||||
toolPreset: 'readonly', // file_read, grep, glob
|
||||
}
|
||||
|
||||
const readwriteAgent: AgentConfig = {
|
||||
name: 'editor',
|
||||
model: 'claude-sonnet-4-6',
|
||||
toolPreset: 'readwrite', // file_read, file_write, file_edit, grep, glob
|
||||
}
|
||||
|
||||
const fullAgent: AgentConfig = {
|
||||
name: 'executor',
|
||||
model: 'claude-sonnet-4-6',
|
||||
toolPreset: 'full', // file_read, file_write, file_edit, grep, glob, bash
|
||||
}
|
||||
```
|
||||
|
||||
### Advanced Filtering
|
||||
|
||||
Combine presets with allowlists and denylists for precise control:
|
||||
|
||||
```typescript
|
||||
const customAgent: AgentConfig = {
|
||||
name: 'custom',
|
||||
model: 'claude-sonnet-4-6',
|
||||
toolPreset: 'readwrite', // Start with: file_read, file_write, file_edit, grep, glob
|
||||
tools: ['file_read', 'grep'], // Allowlist: intersect with preset = file_read, grep
|
||||
disallowedTools: ['grep'], // Denylist: subtract = file_read only
|
||||
}
|
||||
```
|
||||
|
||||
**Resolution order:** preset → allowlist → denylist → framework safety rails.
|
||||
|
||||
### Custom Tools
|
||||
|
||||
Tools added via `agent.addTool()` are always available regardless of filtering.
|
||||
|
||||
### MCP Tools (Model Context Protocol)
|
||||
|
||||
`open-multi-agent` can connect to any MCP server and expose its tools directly to agents.
|
||||
|
||||
```typescript
|
||||
import { connectMCPTools } from '@jackchen_me/open-multi-agent/mcp'
|
||||
|
||||
const { tools, disconnect } = await connectMCPTools({
|
||||
command: 'npx',
|
||||
args: ['-y', '@modelcontextprotocol/server-github'],
|
||||
env: { GITHUB_TOKEN: process.env.GITHUB_TOKEN },
|
||||
namePrefix: 'github',
|
||||
})
|
||||
|
||||
// Register each MCP tool in your ToolRegistry, then include their names in AgentConfig.tools
|
||||
// Don't forget cleanup when done
|
||||
await disconnect()
|
||||
```
|
||||
|
||||
Notes:
|
||||
- `@modelcontextprotocol/sdk` is an optional peer dependency, only needed when using MCP.
|
||||
- Current transport support is stdio.
|
||||
- MCP input validation is delegated to the MCP server (`inputSchema` is `z.any()`).
|
||||
|
||||
## Supported Providers
|
||||
|
||||
| Provider | Config | Env var | Status |
|
||||
|----------|--------|---------|--------|
|
||||
| Anthropic (Claude) | `provider: 'anthropic'` | `ANTHROPIC_API_KEY` | Verified |
|
||||
| OpenAI (GPT) | `provider: 'openai'` | `OPENAI_API_KEY` | Verified |
|
||||
| Grok (xAI) | `provider: 'grok'` | `XAI_API_KEY` | Verified |
|
||||
| GitHub Copilot | `provider: 'copilot'` | `GITHUB_TOKEN` | Verified |
|
||||
| Gemini | `provider: 'gemini'` | `GEMINI_API_KEY` | Verified |
|
||||
| Ollama / vLLM / LM Studio | `provider: 'openai'` + `baseURL` | — | Verified |
|
||||
| llama.cpp server | `provider: 'openai'` + `baseURL` | — | Verified |
|
||||
|
||||
Gemini requires `npm install @google/genai` (optional peer dependency).
|
||||
|
||||
Verified local models with tool-calling: **Gemma 4** (see [example 08](examples/08-gemma4-local.ts)).
|
||||
|
||||
Any OpenAI-compatible API should work via `provider: 'openai'` + `baseURL` (DeepSeek, Groq, Mistral, Qwen, MiniMax, etc.). **Grok now has first-class support** via `provider: 'grok'`.
|
||||
|
||||
### Local Model Tool-Calling
|
||||
|
||||
The framework supports tool-calling with local models served by Ollama, vLLM, LM Studio, or llama.cpp. Tool-calling is handled natively by these servers via the OpenAI-compatible API.
|
||||
|
||||
**Verified models:** Gemma 4, Llama 3.1, Qwen 3, Mistral, Phi-4. See the full list at [ollama.com/search?c=tools](https://ollama.com/search?c=tools).
|
||||
|
||||
**Fallback extraction:** If a local model returns tool calls as text instead of using the `tool_calls` wire format (common with thinking models or misconfigured servers), the framework automatically extracts them from the text output.
|
||||
|
||||
**Timeout:** Local inference can be slow. Use `timeoutMs` on `AgentConfig` to prevent indefinite hangs:
|
||||
|
||||
```typescript
|
||||
const localAgent: AgentConfig = {
|
||||
name: 'local',
|
||||
model: 'llama3.1',
|
||||
provider: 'openai',
|
||||
baseURL: 'http://localhost:11434/v1',
|
||||
apiKey: 'ollama',
|
||||
tools: ['bash', 'file_read'],
|
||||
timeoutMs: 120_000, // abort after 2 minutes
|
||||
}
|
||||
```
|
||||
|
||||
**Troubleshooting:**
|
||||
- Model not calling tools? Ensure it appears in Ollama's [Tools category](https://ollama.com/search?c=tools). Not all models support tool-calling.
|
||||
- Using Ollama? Update to the latest version (`ollama update`) — older versions have known tool-calling bugs.
|
||||
- Proxy interfering? Use `no_proxy=localhost` when running against local servers.
|
||||
|
||||
### LLM Configuration Examples
|
||||
|
||||
```typescript
|
||||
const grokAgent: AgentConfig = {
|
||||
name: 'grok-agent',
|
||||
provider: 'grok',
|
||||
model: 'grok-4',
|
||||
systemPrompt: 'You are a helpful assistant.',
|
||||
}
|
||||
```
|
||||
|
||||
(Set your `XAI_API_KEY` environment variable — no `baseURL` needed anymore.)
|
||||
|
||||
## Contributing
|
||||
|
||||
Issues, feature requests, and PRs are welcome. Some areas where contributions would be especially valuable:
|
||||
|
||||
- **Examples** — Real-world workflows and use cases.
|
||||
- **Documentation** — Guides, tutorials, and API docs.
|
||||
|
||||
## Contributors
|
||||
|
||||
<a href="https://github.com/JackChen-me/open-multi-agent/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=JackChen-me/open-multi-agent&max=20&v=20260411" />
|
||||
</a>
|
||||
|
||||
## Star History
|
||||
|
||||
<a href="https://star-history.com/#JackChen-me/open-multi-agent&Date">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=JackChen-me/open-multi-agent&type=Date&theme=dark" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=JackChen-me/open-multi-agent&type=Date" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=JackChen-me/open-multi-agent&type=Date" />
|
||||
</picture>
|
||||
</a>
|
||||
|
||||
## Translations
|
||||
|
||||
Help translate this README — [open a PR](https://github.com/JackChen-me/open-multi-agent/pulls).
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
73
.Agent Context/Tech/Tools Understanding.md
Normal file
73
.Agent Context/Tech/Tools Understanding.md
Normal file
@@ -0,0 +1,73 @@
|
||||
# JackChen-me/open-multi-agent
|
||||
|
||||
[https://github.com/JackChen-me/open-multi-agent](https://github.com/JackChen-me/open-multi-agent)
|
||||
|
||||
JackChen-me/open-multi-agent is a TypeScript-native framework inspired by Claude Code that utilizes a "goal-to-result" approach, dynamically decomposing user goals into a Task DAG (Directed Acyclic Graph) for execution via a `runTeam()` function. It features parallel task scheduling, multi-model support, Model Context Protocol (MCP) integration, and built-in action tools for file manipulation.
|
||||
|
||||
by Jack Chen is a lightweight, TypeScript-native multi-agent orchestration framework designed to enable goal-driven AI workflows where a team of specialized agents works collaboratively. It focuses on simplifying the process from a high-level goal to a finalized result without requiring manual DAG (Directed Acyclic Graph) wiring, often achieved through a single call.
|
||||
|
||||
First Principles and Core Workflow
|
||||
|
||||
**The framework operates based on a few foundational principles aimed at simplicity and speed:**
|
||||
|
||||
* **Goal-Driven Orchestration:** Rather than explicitly defining a fixed graph of nodes and edges (like LangGraph), the user provides a high-level objective (e.g., "Build a REST API"). A **Coordinator Agent** (an LLM) analyzes this goal at runtime to decompose it into a task Directed Acyclic Graph (DAG).
|
||||
* **Decoupled & Parallel Execution:** The framework resolves dependencies between tasks and automatically executes independent tasks in parallel, maximizing speed.
|
||||
* **Shared Memory/Message Bus:** Agents collaborate by sharing a common memory and message bus, allowing them to view each other's outputs and build upon prior work.
|
||||
* **TypeScript-Native:** It is designed for Node.js, requiring only three main dependencies (@anthropic-ai/sdk, openai, zod), thus avoiding Python subprocess bridges.
|
||||
|
||||
Key Features
|
||||
|
||||
* **Call:** This feature initiates complex multi-agent workflows with a single line of code.
|
||||
* **Multi-Model Teams:** Agents in the same team can use different providers, like Claude, GPT, Gemini, or local models via Ollama/vLLM, for task optimization.
|
||||
* **Structured Output (Zod):** Supports using Zod validation. This ensures agent outputs are structured as JSON and enables auto-retries on validation failures.
|
||||
* **Built-in Tools:** Includes ready-to-use tools for coding tasks such as (shell command execution), , , , and .
|
||||
* **Human-in-the-Loop:** An optional callback in allows pausing execution to request human input before continuing.
|
||||
* **Lifecycle Hooks & Loop Detection:** Includes / hooks for customizing input/output and loop detection to terminate agents repeating actions.
|
||||
* **Observability:** Provides an callback to emit structured spans for tracing LLM calls, tool execution, and task timing with zero overhead when disabled.
|
||||
|
||||
Architectural Components
|
||||
|
||||
1. **Coordinator Agent:** This agent is responsible for task decomposition and assignment.
|
||||
2. **Task Queue:** This component manages task dependencies and parallel execution.
|
||||
3. **Shared Memory:** This shared context allows agents to read output from prior tasks. It is dependency-scoped by default to prevent context leakage.
|
||||
|
||||
Comparison with Other Frameworks
|
||||
|
||||
* **vs. LangGraph JS:** LangGraph is better for fixed, manual, and highly controlled graph workflows. is better for faster, dynamic, goal-driven iteration with less typing.
|
||||
* **vs. CrewAI:** CrewAI is Python-focused, while is native to TypeScript/Node.js.
|
||||
* **vs. Vercel AI SDK:** Vercel AI SDK handles single LLM calls, while uses it as a layer beneath for multi-agent coordination.
|
||||
|
||||
The framework is licensed under MIT and is a lightweight alternative for TypeScript-based AI automation.
|
||||
|
||||
# Nemo Claw
|
||||
|
||||
NVIDIA NeMoClaw (introduced at GTC March 2026\) is an open-source security, privacy, and governance stack designed to wrap **OpenClaw** autonomous AI agents. While OpenClaw enables AI agents to read emails, write code, and act autonomously, NeMoClaw fixes the critical security vulnerabilities—such as prompt injection, unauthorized network access, and data leaks—by placing agents into a "hardened, controlled sandbox".
|
||||
|
||||
First Principles: How NemoClaw Works
|
||||
|
||||
**NemoClaw moves the security control point outside the agent itself, ensuring that even if an agent is compromised, it cannot override its own restrictions.**
|
||||
|
||||
* **1\. Infrastructural Isolation (OpenShell Runtime):** NemoClaw leverages the NVIDIA OpenShell runtime to create an OS-level sandbox (using Landlock, seccomp, and network namespaces). The agent operates inside a restricted container, locked from accessing host resources directly.
|
||||
* **2\. Blueprint-Driven Deployment:** NemoClaw uses a **Blueprint**—a versioned Python artifact (blueprint.yaml)—to create the sandbox. This blueprint defines the network policies, filesystem restrictions, and inference routes before the agent starts.
|
||||
* **3\. External Policy Enforcement:** Security rules are applied at the infrastructure layer (gateway level), not within the agent’s prompt. If an agent tries to reach an unauthorized URL or write to an unlisted folder, the OpenShell gateway blocks it, regardless of the agent's "intent".
|
||||
* **4\. Privacy Routing (Inference Control):** NemoClaw intercepts all inference requests (LLM API calls). The **Privacy Router** classifies queries by data sensitivity: high-sensitivity queries are routed locally to NVIDIA Nemotron models, while low-sensitivity queries are routed through secured cloud APIs.
|
||||
|
||||
**Core Architecture Components**
|
||||
|
||||
1. **TypeScript CLI Plugin (nemoclaw):** Handles user interaction, onboarding, and validation.
|
||||
2. **Blueprint (Python Artifact):** Orchestrates sandbox creation, filesystem mapping, and security policy installation.
|
||||
3. **OpenShell Runtime:** A secure runtime environment that enforces network and file policies at runtime.
|
||||
|
||||
Key Features and Capabilities
|
||||
|
||||
**NemoClaw introduces several enterprise-grade features designed to solve the agent "trust trilemma" (Safety vs. Capability vs. Autonomy):**
|
||||
|
||||
* **OS-Level Agent Sandboxing:** Restricts agent filesystem access to and , preventing access to the host file system.
|
||||
* **Network Egress Control:** Blocks all unauthorized outbound connections, allowing only approved endpoints for API calls.
|
||||
* **Intent Verification:** Analyzes proposed actions against operator-defined policies *before* the agent executes tool calls, preventing malicious actions.
|
||||
* **Local & Cloud Inference Support:** Natively supports NVIDIA Nemotron models via NVIDIA Inference Microservices (NIM) for local, private AI, or routes to cloud frontier models.
|
||||
* **Live Policy Updates:** Allows operators to update network and inference rules on-the-fly, without restarting the sandbox.
|
||||
* **Human-in-the-Loop Operator Approval:** When an agent attempts an unauthorized action, the request surfaces in a Terminal User Interface (TUI) for human approval.
|
||||
* **Audit Logging:** Generates structured, compliance-friendly logs of all significant agentic actions, including tool calls and model queries.
|
||||
* **NeMo Guardrails Integration:** Uses defined configuration rules to enforce topical constraints, ensuring agents stay within their required domain.
|
||||
|
||||
Reference in New Issue
Block a user