npm package: @researchcomputer/agents-sdk
Description: Coding agent SDK built on pi-ai and pi-agent-core
Latest version: 0.1.2

# @researchcomputer/agents-sdk

A TypeScript SDK for building coding agents powered by large language models. Built on `@mariozechner/pi-agent-core`, it provides a high-level framework for creating agents with file operations, shell execution, web access, permission controls, memory, sessions, MCP servers, and multi-agent swarms.

[![npm version](https://img.shields.io/npm/v/@researchcomputer/agents-sdk)](https://www.npmjs.com/package/@researchcomputer/agents-sdk)
[![Node.js >= 20](https://img.shields.io/badge/node-%3E%3D%2020-brightgreen)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7%2B-blue)](https://www.typescriptlang.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Features

- 🔧 **Built-in Tools** — File operations (Read, Write, Edit, Glob, Grep), shell execution (Bash), web access (WebFetch, WebSearch), Jupyter notebook editing, and user interaction
- 🔒 **Permission System** — Capability-based access control with multiple modes (default, allowAll, rulesOnly) and interactive prompting
- 🧠 **Memory** — Persistent, queryable per-agent memories with relevance scoring
- 💾 **Sessions** — Snapshot-based conversation persistence and resumption
- 🔌 **MCP** — Connect external tool servers via Model Context Protocol (stdio, SSE, HTTP transports)
- 🐝 **Swarm** — Multi-agent coordination with mailbox messaging and task delegation
- 🌿 **Snapshot & Fork** — Checkpoint agent state and branch into parallel explorations
- 🪝 **Middleware & Hooks** — Observe and modify agent behavior at lifecycle points
- 📊 **Observability** — Token/cost tracking and trace IDs for debugging

## Documentation

| Document | Description |
|---|---|
| [Getting Started](./docs/getting-started.md) | Installation, quick start, and first agent |
| [Core Concepts](./docs/concepts.md) | Architecture, tools, permissions, memory, sessions, MCP, swarm |
| [API Reference](./docs/api-reference.md) | Complete API documentation with types and examples |
| [Examples](./docs/examples.md) | Practical usage patterns and recipes |

## Quick Start

### Installation

```bash
npm install @researchcomputer/agents-sdk @researchcomputer/ai-provider
```

### Minimal Example

```typescript
import { createCodingAgent } from '@researchcomputer/agents-sdk';
import { getModel } from '@researchcomputer/ai-provider';

const agent = await createCodingAgent({
  model: getModel('openai', 'gpt-4o'),
  cwd: process.cwd(),
});

await agent.prompt('List all TypeScript files and summarize what they do');
await agent.dispose();
```

## Architecture Overview

```
@researchcomputer/agents-sdk
├── Factory            createCodingAgent() — main entry point
├── Tools              Built-in: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, NotebookEdit, AskUser
├── Permissions        Capability-based access control with multiple modes
├── Memory             Persistent, queryable per-agent memories
├── Sessions           Snapshot-based conversation persistence
├── MCP                Connect external tool servers via Model Context Protocol
├── Swarm              Multi-agent coordination with mailbox messaging
├── Middleware         Hooks, permission gates, and pipeline composition
├── Context            Message conversion, system prompt construction, compression
└── Observability      Token/cost tracking and trace IDs
```

## Bridge Server

The SDK includes an HTTP bridge server that exposes agents over a REST+SSE API, enabling non-TypeScript clients to interact with agents.

Build and run:

```bash
npm run build
npm run bridge:start
```

The server supports:
- Job queuing with concurrency limits
- Real-time SSE event streaming
- Multi-turn conversations via reply endpoints
- Idle timeouts and job cancellation
- Custom model endpoints per request

Python example clients are available in [`examples/bridge/`](./examples/bridge).

### Environment Variables

| Variable | Default | Description |
|---|---|---|
| `PORT` | `3000` | HTTP port |
| `CONCURRENCY` | `5` | Max concurrent jobs |
| `JOBS_DIR` | `/tmp/rc-agent-jobs` | Working directory for jobs |
| `API_KEY` | — | Fallback API key |
| `IDLE_TIMEOUT_MS` | `300000` | Idle timeout (5 minutes) |
| `MODEL_ENDPOINT` | — | OpenAI-compatible base URL |
| `MODEL_ID` | `gpt-4o-mini` | Default model |
| `MODEL_PROVIDER` | `openai` | Default provider |

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run tests
npm run test

# Type check
npm run lint

# Start bridge server
npm run bridge:start
```

## Requirements

- Node.js >= 20.0.0
- TypeScript >= 5.7.0 (for development)

## License

MIT