# Robota - AI Agent Framework

A TypeScript framework for building AI agents with multi-provider support, tool calling, and extensible plugin architecture.

![Robota CLI](https://raw.githubusercontent.com/woojubb/robota/main/content/images/cli-demo.png)

## Quick Start

### CLI — AI Coding Assistant

```bash
# Try it now (no install needed)
npx @robota-sdk/agent-cli

# Or install globally for persistent use
npm install -g @robota-sdk/agent-cli
robota
```

> **Beta**: Robota is currently `3.0.0-beta`. Core features are stable but APIs may change before 1.0. See [CHANGELOG.md](./CHANGELOG.md) for upgrade notes.

> **macOS users**: Korean/CJK IME input may crash macOS Terminal.app. Use **[iTerm2](https://iterm2.com/)** instead. This is a known Ink + Terminal.app issue shared with Claude Code.

### SDK — Programmatic Usage

```typescript
import { createQuery } from '@robota-sdk/agent-framework';
import { AnthropicProvider } from '@robota-sdk/agent-provider/anthropic';

const query = createQuery({
  provider: new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY }),
});
const response = await query('List all TypeScript files in src/');
```

### Core — Build Custom Agents

```typescript
import { Robota } from '@robota-sdk/agent-core';
import { AnthropicProvider } from '@robota-sdk/agent-provider/anthropic';

const agent = new Robota({
  name: 'MyAgent',
  aiProviders: [new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY })],
  defaultModel: {
    provider: 'anthropic',
    model: 'claude-sonnet-4-6',
    systemMessage: 'You are a helpful assistant.',
  },
});

const response = await agent.run('Hello!');
```

## Architecture

```
agent-cli              ← Interactive terminal AI coding assistant
  ↓
agent-framework        ← Assembly layer: InteractiveSession, createQuery(), config/context loading
  ↓
agent-session          ← Session lifecycle: permissions, hooks, compaction
agent-tools            ← Tool infrastructure + 8 built-in tools
agent-provider         ← Consolidated AI providers (sub-paths: /anthropic, /openai, /gemini, …)
  ↓
agent-core             ← Foundation: Robota engine, abstractions, plugins
```

## Packages

| Package                                                                                    | Description                                                                             |
| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
| [`@robota-sdk/agent-core`](https://www.npmjs.com/package/@robota-sdk/agent-core)           | Core agent runtime, abstractions, and plugin system                                     |
| [`@robota-sdk/agent-tools`](https://www.npmjs.com/package/@robota-sdk/agent-tools)         | Tool registry, FunctionTool, and 8 built-in tools                                       |
| [`@robota-sdk/agent-session`](https://www.npmjs.com/package/@robota-sdk/agent-session)     | Session with permissions, hooks, and compaction                                         |
| [`@robota-sdk/agent-framework`](https://www.npmjs.com/package/@robota-sdk/agent-framework) | Assembly layer with config/context loading and query()                                  |
| [`@robota-sdk/agent-provider`](https://www.npmjs.com/package/@robota-sdk/agent-provider)   | Consolidated AI providers (Anthropic, OpenAI, Gemini, DeepSeek, Gemma, Qwen, ByteDance) |
| [`@robota-sdk/agent-cli`](https://www.npmjs.com/package/@robota-sdk/agent-cli)             | Interactive terminal AI coding assistant                                                |

## Documentation

Full documentation at **[robota.io](https://robota.io)**

- [Getting Started](https://robota.io/getting-started/)
- [Building Agents](https://robota.io/guide/building-agents.html)
- [SDK Usage](https://robota.io/guide/sdk.html)
- [CLI Reference](https://robota.io/guide/cli.html)
- [Examples](https://robota.io/examples/)

## Repository Scope

This repository now owns the Robota agent SDK, CLI, providers, transports, playground, and related
apps. The DAG product line has moved to a separate `robota-dag` repository; use that repository for
DAG source, issues, docs, and releases once its remote URL is published.

## Development

```bash
pnpm install
pnpm build
pnpm test
```

Node.js 22+ required. See [Development Guide](https://robota.io/development/) for details.

## License

MIT
