npm - agentic-flow - Versions diffs - 1.9.0 → 1.9.2 - Mend

agentic-flow 1.9.0 → 1.9.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1223) hide show

package/agentic-flow/docs/guides/STANDALONE_PROXY_GUIDE.md DELETED Viewed

@@ -1,437 +0,0 @@
-# Standalone Proxy Mode - Use Gemini/OpenRouter with Claude Code & Cursor
-## Overview
-The standalone proxy allows you to use **Gemini** or **OpenRouter** models with tools that expect the Anthropic API, such as:
-- ✅ **Claude Code** (Anthropic's official CLI)
-- ⏳ **Cursor IDE** (when ANTHROPIC_BASE_URL support is added)
-- ✅ Any tool that supports `ANTHROPIC_BASE_URL`
-**Cost Savings:** 85-90% cheaper than direct Anthropic API!
-## Quick Start
-### Start Gemini Proxy (Default)
-```bash
-# Set your API key
-export GOOGLE_GEMINI_API_KEY=your-key-here
-# Start proxy server
-npx agentic-flow@1.1.11 proxy
-```
-### Start OpenRouter Proxy
-```bash
-# Set your API key
-export OPENROUTER_API_KEY=sk-or-v1-your-key-here
-# Start proxy server
-npx agentic-flow@1.1.11 proxy --provider openrouter --model "openai/gpt-4o-mini"
-```
-## Usage with Claude Code
-Claude Code officially supports custom proxy URLs via `ANTHROPIC_BASE_URL`.
-### Terminal 1: Start Proxy
-```bash
-# Gemini
-export GOOGLE_GEMINI_API_KEY=your-key-here
-npx agentic-flow proxy
-# OR OpenRouter
-export OPENROUTER_API_KEY=sk-or-v1-your-key-here
-npx agentic-flow proxy --provider openrouter
-```
-### Terminal 2: Use Claude Code
-```bash
-# Point Claude Code to the proxy
-export ANTHROPIC_BASE_URL=http://localhost:3000
-export ANTHROPIC_API_KEY=sk-ant-proxy-dummy-key  # Any value works
-# Now use Claude Code normally
-claude
-# Or with direct commands
-claude --agent coder --task "Create a REST API in Python"
-```
-**That's it!** Claude Code will now route all requests through the proxy, using Gemini or OpenRouter instead of Anthropic.
-## Usage with Cursor IDE
-**Status:** Cursor does not currently support custom `ANTHROPIC_BASE_URL` for Anthropic models.
-**Workaround:** Use this feature request: https://github.com/cursor/cursor/issues/1604
-Once Cursor adds support, usage will be:
-```bash
-# Start proxy
-export GOOGLE_GEMINI_API_KEY=your-key-here
-npx agentic-flow proxy
-# Configure Cursor
-Settings → API Keys
-  Anthropic Base URL: http://localhost:3000
-  Anthropic API Key: sk-ant-proxy-dummy-key
-```
-## Full Command Reference
-### Start Proxy
-```bash
-npx agentic-flow proxy [OPTIONS]
-```
-### Options
-| Option | Short | Description | Default |
-|--------|-------|-------------|---------|
-| `--provider` | `-p` | Provider (gemini, openrouter) | gemini |
-| `--port` | `-P` | Port number | 3000 |
-| `--model` | `-m` | Model to use (provider-specific) | Auto |
-| `--help` | `-h` | Show help | - |
-### Environment Variables
-| Variable | Required For | Description |
-|----------|--------------|-------------|
-| `GOOGLE_GEMINI_API_KEY` | Gemini | Your Google Gemini API key |
-| `OPENROUTER_API_KEY` | OpenRouter | Your OpenRouter API key |
-| `COMPLETION_MODEL` | Optional | Override default model |
-## Examples
-### Example 1: Gemini with Custom Port
-```bash
-export GOOGLE_GEMINI_API_KEY=AIza...
-npx agentic-flow proxy --port 8080
-# In another terminal
-export ANTHROPIC_BASE_URL=http://localhost:8080
-export ANTHROPIC_API_KEY=sk-ant-proxy-dummy-key
-claude
-```
-### Example 2: OpenRouter with Specific Model
-```bash
-export OPENROUTER_API_KEY=sk-or-v1-...
-npx agentic-flow proxy --provider openrouter --model "anthropic/claude-3.5-sonnet"
-# Use Claude Code
-export ANTHROPIC_BASE_URL=http://localhost:3000
-export ANTHROPIC_API_KEY=sk-ant-proxy-dummy-key
-claude --agent researcher --task "Analyze market trends"
-```
-### Example 3: Gemini with DeepSeek via OpenRouter
-```bash
-export OPENROUTER_API_KEY=sk-or-v1-...
-npx agentic-flow proxy --provider openrouter --model "deepseek/deepseek-chat-v3.1"
-# 98% cost savings vs Claude Sonnet!
-export ANTHROPIC_BASE_URL=http://localhost:3000
-export ANTHROPIC_API_KEY=sk-ant-proxy-dummy-key
-claude --agent coder --task "Build a web scraper"
-```
-## Supported Models
-### Gemini Models (via Google Gemini API)
-Default: `gemini-2.0-flash-exp`
-Available models:
-- `gemini-2.0-flash-exp` - Fast, experimental, free tier
-- `gemini-1.5-pro` - High quality, paid
-- `gemini-1.5-flash` - Fast, cheap
-### OpenRouter Models (via OpenRouter API)
-Default: `meta-llama/llama-3.1-8b-instruct`
-Popular models:
-- `openai/gpt-4o-mini` - Fast, cheap OpenAI model ($0.15/1M tokens)
-- `anthropic/claude-3.5-sonnet` - Claude via OpenRouter (same model, lower cost)
-- `deepseek/deepseek-chat-v3.1` - 98% cheaper than Claude ($0.014/1M tokens)
-- `meta-llama/llama-3.3-70b-instruct` - OSS, very cheap
-- `google/gemini-2.0-flash-exp` - Gemini via OpenRouter
-See full list: https://openrouter.ai/models
-## How It Works
-```
-┌─────────────────┐
-│   Claude Code   │
-│   or Cursor     │
-└────────┬────────┘
-         │ ANTHROPIC_BASE_URL=http://localhost:3000
-         │ Anthropic API format requests
-         ▼
-┌─────────────────────────┐
-│  Agentic Flow Proxy     │
-│  (Port 3000)            │
-│  ┌─────────────────┐    │
-│  │ API Translator  │    │
-│  │ Anthropic →     │    │
-│  │ Gemini/OpenRouter│   │
-│  └─────────────────┘    │
-└────────┬────────────────┘
-         │ Gemini/OpenRouter API format
-         ▼
-┌─────────────────┐
-│ Gemini API      │ OR ┌─────────────────┐
-│ or              │    │ OpenRouter API  │
-│ OpenRouter      │    └─────────────────┘
-└─────────────────┘
-```
-**Translation:**
-1. Claude Code sends Anthropic API request to proxy
-2. Proxy translates to Gemini/OpenRouter format
-3. Provider API returns response
-4. Proxy translates back to Anthropic format
-5. Claude Code receives response as if from Anthropic
-## Cost Comparison
-| Provider | Model | Cost per 1M tokens (input) | Savings vs Anthropic |
-|----------|-------|---------------------------|---------------------|
-| **Anthropic** | Claude Sonnet 4.5 | $3.00 | Baseline |
-| **Gemini** (proxy) | gemini-2.0-flash-exp | $0.00 (free tier) | **100%** 🎉 |
-| **OpenRouter** (proxy) | gpt-4o-mini | $0.15 | **95%** |
-| **OpenRouter** (proxy) | deepseek-chat-v3.1 | $0.014 | **98%** |
-**Real Example:**
-- Task: Generate 10,000 lines of code (500K tokens)
-- Anthropic Claude Sonnet 4.5: $1.50
-- Gemini (free tier): $0.00
-- OpenRouter (DeepSeek): $0.007
-## Features
-### MCP Tools Support (v1.1.11+)
-MCP tools now work through the proxy! Enable with:
-```bash
-# Start proxy
-export GOOGLE_GEMINI_API_KEY=your-key-here
-npx agentic-flow proxy
-# Enable MCP in Claude Code
-export ENABLE_CLAUDE_FLOW_SDK=true
-export ANTHROPIC_BASE_URL=http://localhost:3000
-export ANTHROPIC_API_KEY=sk-ant-proxy-dummy-key
-# MCP tools will be forwarded to Gemini/OpenRouter
-claude --agent coder --task "Use memory_store to save config"
-```
-All 7 MCP tools work:
-1. `memory_store` - Persistent memory
-2. `memory_retrieve` - Retrieve memory
-3. `memory_search` - Search memory
-4. `swarm_init` - Initialize agent swarm
-5. `agent_spawn` - Spawn agents
-6. `task_orchestrate` - Orchestrate tasks
-7. `swarm_status` - Get swarm status
-### Rate Limits
-**Gemini Free Tier:**
-- 10 requests per minute
-- 50 requests per day
-**OpenRouter:**
-- Varies by model
-- Most models: 100+ req/min
-- Free models may have limits
-**Workaround for Gemini limits:** Use OpenRouter for higher throughput.
-## Troubleshooting
-### Proxy not starting
-```bash
-# Check if port is in use
-lsof -ti:3000
-# Use different port
-npx agentic-flow proxy --port 8080
-```
-### Claude Code hanging
-```bash
-# Verify proxy is running
-curl http://localhost:3000/health
-# Should return: {"status":"ok","service":"anthropic-to-gemini-proxy"}
-```
-### API key errors
-```bash
-# Verify key is set
-echo $GOOGLE_GEMINI_API_KEY
-echo $OPENROUTER_API_KEY
-# Re-export if needed
-export GOOGLE_GEMINI_API_KEY=your-key-here
-```
-### Wrong model being used
-```bash
-# Check proxy logs for model selection
-# Proxy prints model on startup
-# Override with --model flag
-npx agentic-flow proxy --provider openrouter --model "openai/gpt-4o-mini"
-```
-## Advanced Configuration
-### Custom .env File
-Create `.env` in your project:
-```bash
-# .env
-GOOGLE_GEMINI_API_KEY=AIza...
-OPENROUTER_API_KEY=sk-or-v1-...
-COMPLETION_MODEL=gemini-2.0-flash-exp
-PROXY_PORT=3000
-```
-Then start proxy:
-```bash
-npx agentic-flow proxy  # Reads .env automatically
-```
-### Run Proxy in Background
-```bash
-# Linux/Mac
-npx agentic-flow proxy &
-# Or with nohup for persistence
-nohup npx agentic-flow proxy > proxy.log 2>&1 &
-# Check if running
-ps aux | grep agentic-flow
-# Stop
-pkill -f agentic-flow
-```
-### Docker Deployment
-```dockerfile
-FROM node:22-slim
-RUN npm install -g agentic-flow@1.1.11
-EXPOSE 3000
-CMD ["npx", "agentic-flow", "proxy", "--provider", "gemini"]
-```
-```bash
-docker build -t agentic-flow-proxy .
-docker run -d -p 3000:3000 -e GOOGLE_GEMINI_API_KEY=your-key agentic-flow-proxy
-```
-## Security Considerations
-### Local Network Only
-By default, proxy binds to all interfaces (0.0.0.0). For security:
-```bash
-# TODO: Add --host option to bind to localhost only
-# Currently: Proxy listens on all interfaces
-```
-**Workaround:** Use firewall rules to restrict access.
-### API Key Protection
-- Never commit `.env` files to version control
-- Use environment variables in CI/CD
-- Rotate keys regularly
-### HTTPS/TLS
-Currently, proxy runs on HTTP (localhost). For production:
-1. Use reverse proxy (nginx, Caddy) with TLS
-2. Or use cloud deployment with built-in TLS (Cloudflare, AWS)
-## FAQ
-**Q: Can I use this with other tools besides Claude Code?**
-A: Yes! Any tool that supports `ANTHROPIC_BASE_URL` environment variable will work.
-**Q: Does this work with streaming responses?**
-A: Yes, streaming is fully supported for both Gemini and OpenRouter.
-**Q: Can I use multiple proxies simultaneously?**
-A: Yes, just use different ports:
-```bash
-# Terminal 1: Gemini on 3000
-npx agentic-flow proxy --port 3000
-# Terminal 2: OpenRouter on 3001
-npx agentic-flow proxy --provider openrouter --port 3001
-```
-**Q: Will Cursor support this?**
-A: Not yet. Track progress: https://github.com/cursor/cursor/issues/1604
-**Q: Can I contribute other provider proxies?**
-A: Yes! See `/src/proxy/anthropic-to-*.ts` for examples. PRs welcome for AWS Bedrock, Azure, etc.
-## What's Next
-### Planned Features
-- [ ] `--host` option to bind to localhost only
-- [ ] Built-in TLS/HTTPS support
-- [ ] Prometheus metrics endpoint
-- [ ] Request/response logging
-- [ ] Multi-provider load balancing
-- [ ] AWS Bedrock proxy
-- [ ] Azure OpenAI proxy
-### Related Documentation
-- [MCP Proxy Validation](./MCP_PROXY_VALIDATION.md) - MCP tool forwarding details
-- [v1.1.11 Release Notes](./V1.1.11_MCP_PROXY_FIX.md) - What's new
-- [Claude Code Docs](https://docs.anthropic.com/en/docs/claude-code) - Official Claude Code guide
-## Support
-- **GitHub Issues:** https://github.com/ruvnet/agentic-flow/issues
-- **Discord:** (coming soon)
-- **Twitter:** @rUv
----
-**Published:** 2025-10-05
-**Version:** 1.1.11
-**Status:** Production Ready ✅

package/agentic-flow/docs/guides/agent-sdk.md DELETED Viewed

@@ -1,234 +0,0 @@
-Yes. Let’s stand up a minimal Claude Agent SDK service that runs multiple sub-agents in parallel inside Docker. It uses Promise.all to fan out tasks and then reconciles results.
-# 1) Project layout
-```
-claude-agents-docker/
-  Dockerfile
-  docker-compose.yml           # optional
-  package.json
-  tsconfig.json
-  src/
-    index.ts
-    agents/
-      webResearchAgent.ts
-      codeReviewAgent.ts
-      dataAgent.ts
-```
-# 2) package.json
-```json
-{
-  "name": "claude-agents-docker",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "start": "node --enable-source-maps dist/index.js",
-    "build": "tsc -p .",
-    "dev": "tsx src/index.ts"
-  },
-  "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.0",
-    "@anthropic-ai/claude-code": "^2.1.0"
-  },
-  "devDependencies": {
-    "tsx": "^4.19.0",
-    "typescript": "^5.6.3"
-  }
-}
-```
-# 3) tsconfig.json
-```json
-{
-  "compilerOptions": {
-    "module": "esnext",
-    "target": "es2022",
-    "moduleResolution": "bundler",
-    "outDir": "dist",
-    "rootDir": "src",
-    "strict": true,
-    "skipLibCheck": true
-  },
-  "include": ["src"]
-}
-```
-# 4) src/agents/*.ts
-These are tiny task-specialized agents. You can swap in real tools later.
-```ts
-// src/agents/webResearchAgent.ts
-import { createAgent } from "@anthropic-ai/claude-agent-sdk";
-export function webResearchAgent() {
-  return createAgent({
-    name: "web-research",
-    systemPrompt: `You perform fast web-style reconnaissance and return a concise bullet list of findings.`,
-    tools: [] // add HTTP/search tools as you wire MCP or your own fetcher
-  });
-}
-// src/agents/codeReviewAgent.ts
-import { createAgent } from "@anthropic-ai/claude-agent-sdk";
-export function codeReviewAgent() {
-  return createAgent({
-    name: "code-review",
-    systemPrompt: `You review diffs and point out risks, complexity, and tests to add.`,
-    tools: [] // later: git, fs, test runner hooks
-  });
-}
-// src/agents/dataAgent.ts
-import { createAgent } from "@anthropic-ai/claude-agent-sdk";
-export function dataAgent() {
-  return createAgent({
-    name: "data-agent",
-    systemPrompt: `You analyze tabular data and produce a short brief with 3 key stats and 1 risk.`,
-    tools: [] // later: CSV/SQL connectors
-  });
-}
-```
-# 5) src/index.ts
-Parallel fan-out with Promise.all, plus a simple reconcile step.
-```ts
-import "dotenv/config";
-import { webResearchAgent } from "./agents/webResearchAgent.js";
-import { codeReviewAgent } from "./agents/codeReviewAgent.js";
-import { dataAgent } from "./agents/dataAgent.js";
-async function main() {
-  const topic = process.env.TOPIC ?? "migrate payments service";
-  const codeDiff = process.env.DIFF ?? "feat: add payments router and mandate checks";
-  const datasetHint = process.env.DATASET ?? "monthly tx volume, refunds, chargebacks";
-  const research = webResearchAgent();
-  const reviewer = codeReviewAgent();
-  const analyst  = dataAgent();
-  // Each agent runs with its own context. Fan out in parallel.
-  const [researchOut, reviewOut, dataOut] = await Promise.all([
-    research.run({ input: `Give me context and risks about: ${topic}` }),
-    reviewer.run({ input: `Review this diff at a high level and propose tests:\n${codeDiff}` }),
-    analyst.run({ input: `Analyze ${datasetHint} and report key stats.` })
-  ]);
-  // Basic reconcile step
-  const summary = [
-    "=== RESEARCH ===",
-    researchOut.output?.trim() ?? "",
-    "=== CODE REVIEW ===",
-    reviewOut.output?.trim() ?? "",
-    "=== DATA ===",
-    dataOut.output?.trim() ?? ""
-  ].join("\n");
-  console.log(summary);
-}
-main().catch(err => {
-  console.error(err);
-  process.exit(1);
-});
-```
-# 6) Dockerfile
-```dockerfile
-FROM node:20-slim
-# Avoid interactive tzdata prompts
-ENV DEBIAN_FRONTEND=noninteractive
-# Install minimal deps if you later add git or build tools
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    ca-certificates curl git \
-  && rm -rf /var/lib/apt/lists/*
-WORKDIR /app
-COPY package.json package-lock.json* pnpm-lock.yaml* yarn.lock* ./
-RUN npm ci --no-audit --no-fund
-COPY tsconfig.json ./
-COPY src ./src
-RUN npm run build
-# Runtime env
-ENV NODE_ENV=production
-# Required by Anthropic
-ENV ANTHROPIC_API_KEY=""
-# Optional task knobs
-ENV TOPIC="payments mandates"
-ENV DIFF="refactor: route validation"
-ENV DATASET="transactions last 30 days"
-CMD ["npm","start"]
-```
-# 7) docker-compose.yml (optional)
-Scale out multiple identical workers for heavier fan-outs.
-```yaml
-services:
-  agents:
-    build: .
-    environment:
-      ANTHROPIC_API_KEY: ${ANTHROPIC_API_KEY}
-      TOPIC: "upgrade checkout flow"
-    deploy:
-      replicas: 1
-    restart: unless-stopped
-```
-# 8) Run it
-```bash
-# 1) set your key
-export ANTHROPIC_API_KEY=sk-ant-...
-# 2) build
-docker build -t claude-agents:latest .
-# 3) run
-docker run --rm -e ANTHROPIC_API_KEY -e TOPIC="pricing page split" claude-agents:latest
-# or with compose
-docker compose up --build
-```
-# 9) Notes on real parallelism
-* The Agent SDK exposes the same harness behind Claude Code and supports subagents plus background tasks. Your fan-out here is true process-level parallelism inside a single Node runtime using Promise.all. For more isolation, run N containers behind a queue. ([docs.claude.com][1])
-* For heavy workflows, use an orchestrator pattern: a lead agent plans, spawns sub-agents in parallel, and aggregates results. This mirrors Anthropic’s multi-agent Research system. ([Anthropic][2])
-* Sonnet 4.5 is positioned as their strongest coding and agenting model. Use it for better tool use and longer runs. ([Anthropic][3])
-# 10) Where to extend
-* Tools: add MCP tools or your HTTP/RPC clients to each agent.
-* Memory: stitch in your Claude Flow memory hooks for pre/post tool use.
-* Safety: isolate file writes per agent or route to separate branches.
-* Scale: front the container with a queue. One “planner” job enqueues subtasks for pooled “worker” containers.
-If you want, I can add MCP tools and a simple Redis queue so your planner container spawns dozens of sub-agents safely.
-**References**
-Anthropic Agent SDK overview. ([docs.claude.com][1])
-Engineering note on subagents, hooks, and background tasks. ([Anthropic][4])
-Anthropic multi-agent research system. ([Anthropic][2])
-Sonnet 4.5 launch for complex agents. ([Anthropic][3])
-[1]: https://docs.claude.com/en/api/agent-sdk/overview?utm_source=chatgpt.com "Agent SDK overview"
-[2]: https://www.anthropic.com/engineering/built-multi-agent-research-system?utm_source=chatgpt.com "How we built our multi-agent research system"
-[3]: https://www.anthropic.com/news/claude-sonnet-4-5?utm_source=chatgpt.com "Introducing Claude Sonnet 4.5"
-[4]: https://anthropic.com/news/enabling-claude-code-to-work-more-autonomously?utm_source=chatgpt.com "Enabling Claude Code to work more autonomously"