Build AI agents that use tools, connect to MCP servers, and work with any AI provider (OpenAI, Anthropic, Gemini, Groq, local models). Each agent is a portable JSON manifest that anyone can share, install, and run.

✨ Features

🔌 Full MCP Support — stdio, SSE, and WebSocket transports
🔧 Built-in Tools — HTTP fetch, JSON parse, text transform, date/time
🎨 Custom Tools — Write JS handlers, sandboxed via VM
🤖 Any AI Provider — Bring your own: OpenAI, Anthropic, Gemini, Ollama, anything
📦 Portable Agents — JSON manifests that anyone can share and install
⚡ Event Streaming — Real-time execution tracking via EventEmitter
🖥️ CLI Included — Create, run, and manage agents from the terminal

🚀 Quick Start

# Install globally
npm install -g openforge

# Create your first agent
openforge create my-agent "A helpful assistant"

# Run it (needs an API key)
OPENAI_API_KEY=sk-xxx openforge run my-agent "What's the weather in NYC?"

📦 Programmatic Usage

const { AgentBuilder } = require('openforge');

const builder = new AgentBuilder({
  aiProvider: async (messages, model, tools) => {
    // Use any AI provider — OpenAI, Anthropic, Gemini, etc.
    const { OpenAI } = require('openai');
    const client = new OpenAI();
    return await client.chat.completions.create({
      model: model || 'gpt-4o-mini',
      messages,
      tools: tools?.length > 0 ? tools : undefined,
    });
  },
});

await builder.initialize();

// Run an agent
const result = await builder.runAgent('my-agent', 'Hello!');
console.log(result.output);

// Stream execution events
const { runtime, resultPromise } = await builder.runAgentStreaming('my-agent', 'Hello!');
runtime.on('tool_call', (data) => console.log(`🔧 ${data.tool}`));
runtime.on('agent_response', (data) => console.log(`💬 ${data.content}`));
const finalResult = await resultPromise;

await builder.shutdown();

🏗️ Architecture

┌──────────────────────────────────────────┐
│              OpenForge                    │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│  │ Runtime   │ │ Registry │ │  Loader  │ │
│  │(executor) │ │ (tools)  │ │ (agents) │ │
│  └─────┬─────┘ └─────┬────┘ └────┬─────┘ │
│        │              │           │        │
│  ┌─────┴──────────────┴───────────┤       │
│  │         Tool Registry          │       │
│  ├────────┬────────┬──────────────┤       │
│  │  MCP   │Built-in│   Custom     │       │
│  │ Client │ Tools  │  JS/VM       │       │
│  └──┬─────┘────────┘──────────────┘       │
└─────┼─────────────────────────────────────┘
      │
  MCP Servers (any!)
  - stdio (spawn local process)
  - SSE (HTTP streaming)
  - WebSocket (persistent)

📋 Agent Manifest

Every agent is defined by a .agent.json file:

{
  "name": "my-agent",
  "version": "1.0.0",
  "description": "What this agent does",
  "systemPrompt": "You are a helpful assistant...",
  "runtime": {
    "model": "gpt-4o-mini",
    "maxLoops": 10,
    "timeoutMs": 60000
  },
  "tools": {
    "require": ["builtin:http_fetch", "builtin:json_parse"],
    "optional": ["mcp:calendar"]
  },
  "ui": {
    "icon": "🤖"
  }
}

🔌 MCP Support

Full Model Context Protocol support — connect to any MCP server:

// stdio — spawn a local MCP server
await builder.addMcpServer('calculator', {
  transport: 'stdio',
  command: 'npx',
  args: ['-y', '@example/mcp-calculator'],
});

// SSE — connect to an HTTP MCP server
await builder.addMcpServer('api', {
  transport: 'sse',
  url: 'http://localhost:3001/sse',
});

// WebSocket — persistent connection
await builder.addMcpServer('realtime', {
  transport: 'websocket',
  url: 'ws://localhost:8080',
});

🔧 Tool Providers

Provider	Prefix	Description
Built-in	`builtin:`	`http_fetch`, `json_parse`, `text_transform`, `date_time`, `wait`
MCP	`mcp:`	Any MCP-compliant server (stdio, SSE, WebSocket)
Custom	`custom:`	Agent-local JS handlers (sandboxed via VM)

🎨 Creating Custom Tools

Define custom tools in your agent manifest:

{
  "tools": {
    "custom": [
      {
        "name": "analyze_data",
        "description": "Analyze data from a CSV",
        "parameters": {
          "type": "object",
          "properties": {
            "data": { "type": "string" }
          }
        },
        "handler": "./tools/analyzeData.js"
      }
    ]
  }
}

Handler file (tools/analyzeData.js):

module.exports = async function(args, context) {
  const { data } = args;
  // Your analysis logic here
  return { success: true, result: 'Analysis complete' };
};

🖥️ CLI Reference

openforge list                          # List installed agents
openforge info <name>                   # Show agent details
openforge create <name> [description]   # Create from template
openforge run <name> <input>            # Run (needs OPENAI_API_KEY)
openforge tools                         # List available tools
openforge validate <path>               # Validate manifest

⚡ Event Streaming

The runtime emits events during execution for real-time tracking:

const { runtime, resultPromise } = await builder.runAgentStreaming('my-agent', input);

runtime.on('execution_started', (data) => { /* { id, agent } */ });
runtime.on('loop_iteration', (data) => { /* { id, loop, maxLoops } */ });
runtime.on('tool_call', (data) => { /* { id, tool, args } */ });
runtime.on('tool_result', (data) => { /* { id, tool, result } */ });
runtime.on('agent_response', (data) => { /* { id, content } */ });
runtime.on('execution_completed', (data) => { /* { id, agent, duration, loops } */ });

const result = await resultPromise;

📖 API Reference

`new AgentBuilder(options)`

Option	Type	Required	Description
`aiProvider`	`Function`	✅	`async (messages, model, tools, meta) => OpenAI-format response`
`agentDir`	`string`		Custom agent directory (default: `~/.openforge/agents/`)
`mcpServers`	`Object`		Initial MCP server configs
`additionalAgentDirs`	`string[]`		Extra directories to scan for agents

Methods

Method	Returns	Description
`initialize()`	`Promise`	Must be called before any operations
`runAgent(name, input, ctx)`	`Promise<Result>`	Run an agent synchronously
`runAgentStreaming(name, input, ctx)`	`{ runtime, resultPromise }`	Run with event streaming
`createAgent(config)`	`AgentManifest`	Create a new agent
`deleteAgent(name)`	`boolean`	Delete an agent
`listAgents(filter)`	`Agent[]`	List all agents
`addMcpServer(name, config)`	`Promise<Server>`	Connect MCP server
`removeMcpServer(name)`	`Promise`	Disconnect MCP server
`listTools()`	`Tool[]`	List all available tools
`shutdown()`	`Promise`	Graceful shutdown

🤝 Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.

📄 License

MIT — build whatever you want.