Skip to content
Robotadocs

5-Minute Quick Start

Two ways to use the same agent foundation: the CLI, or the SDK in your own code.

Prerequisites

  • Node.js 22.12 or later (node --version)
  • An API key for a model provider. The examples on this page use Anthropic (platform.claude.com). No key? The CLI can use a local model instead — see Local LLM Setup.

Option A — Run the CLI

# No install needed
npx @robota-sdk/agent-cli

On first run, the CLI asks whether you have an API key, then either configures that provider, walks you through getting a free Gemini key, connects to a local model server (LM Studio) or connects to OpenRouter. If ANTHROPIC_API_KEY, GEMINI_API_KEY, DASHSCOPE_API_KEY, DEEPSEEK_API_KEY or OPENROUTER_API_KEY is already set and no provider is configured, it skips the questions and starts with that provider's default model. Then it opens the interactive terminal UI.

Tip: in the terminal UI, /workflows create "<describe a multi-step task>" asks the model to design a DAG workflow from your description, saves it under .workflows/ once you confirm, and runs it. See the CLI reference.

Option B — Use the SDK in your code

npm install @robota-sdk/agent-framework @robota-sdk/agent-tools @robota-sdk/agent-provider @anthropic-ai/sdk

Save this as agent.mts and run it with npx tsx agent.mts:

import { createQuery } from '@robota-sdk/agent-framework';
import { createNodeFrameworkHost } from '@robota-sdk/agent-framework/node';
import { createAnthropicProvider } from '@robota-sdk/agent-provider/anthropic';
import { createDefaultTools } from '@robota-sdk/agent-tools/defaults';
 
// The framework runs on the platform you pass as `host`. On Node, createNodeFrameworkHost lends the
// files, processes and environment, and createDefaultTools is the set of built-in tools. createQuery
// returns a function that runs one prompt, with the tools the host builds, and resolves with the
// reply. cwd is the absolute directory the tools work in; it has no default. permissionMode defaults
// to 'default': reads and searches run, and with no permissionHandler a call that would ask for
// approval (an edit, a shell command) is denied. Pass permissionMode: 'bypassPermissions' for
// unattended runs.
const query = createQuery({
  host: createNodeFrameworkHost({ createDefaultTools }),
  cwd: process.cwd(),
  provider: createAnthropicProvider({
    apiKey: process.env.ANTHROPIC_API_KEY,
  }),
});
 
const response = await query('Hello, what can you do?');
console.log(response);

Pass model to createQuery with any provider other than Anthropic: without it the query asks the provider for claude-opus-4-5 unless a settings file names a model. Without a projectAccess decision it also runs Restricted: the project's AGENTS.md, CLAUDE.md and settings are not loaded. A host that lends no createDefaultTools (host: {}) gives the query no built-in tools. The SDK guide covers all three.

Use another provider

InteractiveSession takes the host, the provider and the model to use:

import { InteractiveSession } from '@robota-sdk/agent-framework';
import { createNodeFrameworkHost } from '@robota-sdk/agent-framework/node';
import { OpenAIProvider } from '@robota-sdk/agent-provider/openai';
import { createDefaultTools } from '@robota-sdk/agent-tools/defaults';
 
const session = new InteractiveSession({
  host: createNodeFrameworkHost({ createDefaultTools }),
  cwd: process.cwd(),
  provider: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
  model: 'gpt-5.1',
});
 
const turn = await session.submit('Hello, what can you do?');
const { response } = await turn.completed;
console.log(response);

Supported providers: Anthropic, OpenAI, Google Gemini, DeepSeek, Qwen, and any OpenAI-compatible endpoint, including local servers such as Ollama and LM Studio. Install the vendor SDK of the provider you import: openai for OpenAI, DeepSeek, Qwen and Gemma, @google/genai for Gemini.

Through an AI gateway (Vercel AI Gateway, LiteLLM, OpenRouter): use the OpenAI provider with the gateway's baseURL, and pass a gateway model slug — non-OpenAI models included. Streaming and tool calling use the same chat-completions protocol:

import { InteractiveSession } from '@robota-sdk/agent-framework';
import { createNodeFrameworkHost } from '@robota-sdk/agent-framework/node';
import { OpenAIProvider } from '@robota-sdk/agent-provider/openai';
import { createDefaultTools } from '@robota-sdk/agent-tools/defaults';
 
const session = new InteractiveSession({
  host: createNodeFrameworkHost({ createDefaultTools }),
  cwd: process.cwd(),
  provider: new OpenAIProvider({
    apiKey: process.env.AI_GATEWAY_API_KEY,
    baseURL: 'https://ai-gateway.vercel.sh/v1',
  }),
  model: 'anthropic/claude-sonnet-4-5',
});

See Providers Reference — Through an AI gateway for LiteLLM, OpenRouter and Azure variants.

Next steps