Skip to content

Robota SDK

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

Robota CLI

Overview

Robota SDK ships three layers you can use independently or together:

  • CLI (agent-cli) — A ready-to-use AI coding assistant in your terminal. Install and run immediately, no code required.
  • Assembly Layer (agent-sdk) — A programmable interface for embedding the same assistant capabilities into your own scripts, tools, or workflows.
  • Agent Library (agent-core, agent-tools, agent-sessions, and providers) — Low-level building blocks for constructing any AI agent system from scratch.

The CLI is built on top of the Assembly Layer. The Assembly Layer is assembled from the Agent Library. You can enter at any layer.

Quick Start

Build an Agent (agent-core)

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

const provider = new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY });

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

const response = await agent.run('Explain TypeScript generics.');
console.log(response);

Add Tools

typescript
import { Robota } from '@robota-sdk/agent-core';
import { AnthropicProvider } from '@robota-sdk/agent-provider-anthropic';
import { createZodFunctionTool } from '@robota-sdk/agent-tools';
import { z } from 'zod';

const provider = new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY });

const calculatorTool = createZodFunctionTool(
  'calculator',
  'Perform arithmetic calculations',
  z.object({
    expression: z.string().describe('Math expression to evaluate'),
  }),
  async ({ expression }) => {
    // WARNING: eval() is used here for brevity only. Do not use in production.
    return { data: String(eval(expression)) }; // eslint-disable-line no-eval
  },
);

const agent = new Robota({
  name: 'ToolAgent',
  aiProviders: [provider],
  defaultModel: { provider: 'anthropic', model: 'claude-sonnet-4-6' }, // see CLAUDE_MODELS for available model IDs
  tools: [calculatorTool],
});

const response = await agent.run('What is 42 * 17?');

Use the SDK (agent-sdk)

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

const provider = new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY! });
const query = createQuery({ provider });

const response = await query('List all TypeScript files in src/');

Use the CLI (agent-cli)

bash
npm install -g @robota-sdk/agent-cli
robota                              # Interactive TUI
robota -p "Explain this project"    # Print mode

Why Robota SDK?

  • Type-Safe: Strict TypeScript with zero any in production code
  • Multi-Provider: Anthropic Claude, OpenAI, Gemini, Gemma, Qwen, and OpenAI-compatible endpoints — same API, seamless switching
  • Tool Calling: Zod-based schema validation for type-safe function calls
  • Subagents: Runtime-managed background jobs, transcripts, and batch Agent tool requests
  • Plugin System: Extensible lifecycle hooks for logging, analytics, error handling
  • Streaming: Real-time text delta streaming from all providers
  • CLI Ready: Built-in coding assistant CLI with permission system and context management

Architecture

agent-cli              ← Interactive terminal AI coding assistant
agent-command-agent    ← /agent command module for background subagent control
agent-transport-http   ← HTTP transport (Hono; Cloudflare Workers / Node.js / Lambda)
agent-transport-mcp    ← MCP transport (Model Context Protocol server)
agent-transport-ws     ← WebSocket transport (framework-agnostic)
agent-transport-headless ← Non-interactive transport for text/json/stream-json output
  ↓ (all five consume)
agent-sdk              ← Assembly layer: InteractiveSession, config, context, createQuery()

agent-sessions         ← Session lifecycle: permissions, hooks, compaction
agent-runtime          ← Background task and subagent lifecycle primitives
agent-tools            ← Tool infrastructure + 8 built-in tools
agent-provider-*       ← AI provider implementations (anthropic, openai, gemini, google, gemma, qwen)

agent-core             ← Foundation: Robota engine, abstractions, plugins

Packages

PackageDescription
@robota-sdk/agent-coreCore agent runtime, abstractions, and plugin system
@robota-sdk/agent-toolsTool registry, FunctionTool, and 8 built-in tools
@robota-sdk/agent-sessionsSession with permissions, hooks, and compaction
@robota-sdk/agent-runtimeBackground task and subagent lifecycle primitives
@robota-sdk/agent-sdkAssembly layer with config/context loading and createQuery()
@robota-sdk/agent-command-agent/agent command module for background subagent jobs
@robota-sdk/agent-provider-anthropicAnthropic Claude provider
@robota-sdk/agent-provider-openaiOpenAI provider
@robota-sdk/agent-provider-geminiCanonical Google Gemini provider
@robota-sdk/agent-provider-googleGemini compatibility wrapper for legacy Google imports/settings
@robota-sdk/agent-provider-gemmaGemma-family local provider for LM Studio/OpenAI-compatible endpoints
@robota-sdk/agent-provider-openai-compatibleReusable OpenAI-compatible transport primitives
@robota-sdk/agent-provider-qwenQwen/DashScope provider with optional provider-side web tools
@robota-sdk/agent-cliInteractive terminal AI coding assistant
@robota-sdk/agent-transport-headlessNon-interactive text/json/stream-json transport
@robota-sdk/agent-transport-httpHTTP/REST transport adapter (Hono; Cloudflare Workers / Node / Lambda)
@robota-sdk/agent-transport-mcpMCP transport adapter (Model Context Protocol server)
@robota-sdk/agent-transport-wsWebSocket transport adapter (framework-agnostic)

Documentation

Installation

bash
# Core — build custom agents
npm install @robota-sdk/agent-core

# Provider
npm install @robota-sdk/agent-provider-anthropic @anthropic-ai/sdk
npm install @robota-sdk/agent-provider-openai openai
npm install @robota-sdk/agent-provider-gemini @google/genai
npm install @robota-sdk/agent-provider-google @google/genai
npm install @robota-sdk/agent-provider-qwen
npm install @robota-sdk/agent-provider-gemma
npm install @robota-sdk/agent-provider-openai-compatible

# Tools — FunctionTool, Zod tools, built-in CLI tools
npm install @robota-sdk/agent-tools

# SDK — assembly layer with createQuery() and InteractiveSession
npm install @robota-sdk/agent-sdk

# Command module — /agent background jobs
npm install @robota-sdk/agent-command-agent

# Transports
npm install @robota-sdk/agent-transport-headless
npm install @robota-sdk/agent-transport-http
npm install @robota-sdk/agent-transport-mcp
npm install @robota-sdk/agent-transport-ws

# CLI — terminal AI coding assistant
npm install -g @robota-sdk/agent-cli

License

MIT

Released under the MIT License.