Migrating to 3.x

SDK packages version independently, so read each package's version from your lockfile or the registry instead of assuming one number for the whole SDK. Architecture lists the current packages.

This guide has three parts: moving from the 2.x packages, changes since the 3.0 betas, and the packages that are now subpaths of merged ones.

From 2.x

Package map

The 2.x packages had short names; 3.x packages are named by role.

-  "@robota-sdk/agents": "^2.0.9",
-  "@robota-sdk/openai": "^2.0.9",
-  "@robota-sdk/anthropic": "^2.0.9",
-  "@robota-sdk/google": "^2.0.9",
+  "@robota-sdk/agent-core": "^3.3.0",
+  "@robota-sdk/agent-plugin": "^3.2.3",
+  "@robota-sdk/agent-provider": "^3.3.1",
+  "openai": "^6.0.0",
+  "@anthropic-ai/sdk": "^0.114.0",
+  "@google/genai": "^1.52.0",

@robota-sdk/agent-provider has no root export: each vendor is a subpath, and the vendor SDKs (openai, @anthropic-ai/sdk, @google/genai) are optional peers that your application installs for the subpaths it imports.

What stays the same

Most of the 2.x @robota-sdk/agents API is in @robota-sdk/agent-core under the same names: Robota, AbstractAIProvider, AbstractPlugin, PluginCategory, PluginPriority, EventEmitterPlugin, FunctionTool, ToolRegistry, AgentFactory, AgentTemplates, ConversationHistory, the error classes, and the I*/T* types such as IAgentConfig, IToolSchema and TUniversalMessage. ConversationAgent is the same class as Robota under its neutral name. The constructor takes the same core options (name, aiProviders, defaultModel, tools, plugins, systemMessage), and run(), runStream() and setModel() work as before.

The OpenAI and Anthropic providers keep their exports (OpenAIProvider, IOpenAIProviderOptions, AnthropicProvider, IAnthropicProviderOptions, createAnthropicProvider); only the import path changes:

// 2.x
import { Robota } from '@robota-sdk/agents';
import { OpenAIProvider } from '@robota-sdk/openai';
import { AnthropicProvider } from '@robota-sdk/anthropic';
 
// 3.x
import { Robota } from '@robota-sdk/agent-core';
import { OpenAIProvider } from '@robota-sdk/agent-provider/openai';
import { AnthropicProvider } from '@robota-sdk/agent-provider/anthropic';

Renamed: the Google provider

The provider now uses Google's @google/genai SDK. Check your options against Providers — Gemini.

Moved out of @robota-sdk/agents

Plugins moved to @robota-sdk/agent-plugin: ConversationHistoryPlugin, ErrorHandlingPlugin, ExecutionAnalyticsPlugin, LimitsPlugin, LoggingPlugin, PerformancePlugin, UsagePlugin, WebhookPlugin, their option and stats types (ILoggingPluginOptions, TLimitsStrategy, TErrorHandlingStrategy, TWebhookEventName, …), the usage and performance storages (MemoryUsageStorage, FileUsageStorage, RemoteUsageStorage, SilentUsageStorage, MemoryPerformanceStorage) and aggregateUsageStats; NodeSystemMetricsCollector is on @robota-sdk/agent-plugin/node.

// 2.x
import { LoggingPlugin, UsagePlugin } from '@robota-sdk/agents';
 
// 3.x
import { LoggingPlugin, UsagePlugin } from '@robota-sdk/agent-plugin';

Tool factories createFunctionTool and createZodFunctionTool moved to @robota-sdk/agent-tools.

Removed from @robota-sdk/agents

Sessions

@robota-sdk/sessions (ChatInstance, SessionManager, TemplateManagerAdapter) has no direct replacement. Choose by what you need:

• A single agent conversation in your own code: Robota from @robota-sdk/agent-core, which keeps its own history.
• A ready-made agent session with built-in file, shell and web tools, permissions, hooks, context compaction and persistence: InteractiveSession, createQuery() or createAgentRuntime() from @robota-sdk/agent-framework. See Using the SDK.
• The session layer on its own: Session from @robota-sdk/agent-session, with its file-system adapters (NodeSessionStore and the log, spill and prompt-history files) on @robota-sdk/agent-session/node.

Multi-agent work

@robota-sdk/team (the assign-task relay tools and templates) was removed. In 3.x, an agent session delegates work to subagents: agent-framework sessions include an Agent tool that runs isolated subagent sessions with their own tools and history, and the robota CLI exposes the same through /agent. See Using the SDK and the CLI Reference.

Upgrade steps

1. Replace the packages as in the package map and reinstall, adding the vendor SDKs for the provider subpaths you import.
2. Update imports: @robota-sdk/agents → @robota-sdk/agent-core (plugins from @robota-sdk/agent-plugin, tool factories from @robota-sdk/agent-tools), and the provider packages → subpaths of @robota-sdk/agent-provider.
3. Rename GoogleProvider to GeminiProvider.
4. Run npx tsc --noEmit; the compiler points at every remaining removed or moved name.
5. Replace @robota-sdk/sessions and @robota-sdk/team usage as described above.

From the 3.0 betas

Package names from earlier betas

API changes

• Built-in tools need a working directory. The ready-made tool instances readTool, writeTool, editTool, globTool, grepTool, shellTool and bashTool are gone from @robota-sdk/agent-tools; create them with createReadTool({ cwd }), createWriteTool({ cwd }), createEditTool({ cwd }), createGlobTool({ cwd }), createGrepTool({ cwd }), createShellTool({ cwd }) and createBashTool({ cwd }), imported from @robota-sdk/agent-tools/node. A tool without a root refuses to run.
• createSession is not exported from @robota-sdk/agent-framework; use InteractiveSession, createAgentRuntime().createSession(...) or createQuery().
• Headless default permission mode. createQuery() and headless sessions default to default mode: with no approver, a call that would ask is denied. Pass permissionMode: 'bypassPermissions' explicitly for unattended runs that should not be asked.
• Node-only helpers (canonicalizePath, isPathInside, CommandExecutor, HttpExecutor and the owner-only file helpers) moved from @robota-sdk/agent-core to @robota-sdk/agent-core/node.
• MCP. IMCPToolConfig and IToolFactory.createMCPTool() were removed from agent-core; MCP server definitions and the client are in @robota-sdk/agent-mcp.
• ESM only. @robota-sdk/agent-cli and @robota-sdk/agent-ui-terminal have no CommonJS entry; load them with import.
• Node.js 22.12.0 or newer. Every published package declares engines.node as >=22.12.0.

Packages merged into subpaths

Fewer packages are published: each former package below is now a subpath of the merged one. Import paths change; exported names and signatures do not. A merged package ships its subpaths from the version shown, and a bundle that imports one subpath contains no other subpath's code.

@robota-sdk/agent-provider, @robota-sdk/agent-os and @robota-sdk/agent-interface have no root export. @robota-sdk/agent-transport keeps its root, /client and /node entries beside the carrier subpaths, and @robota-sdk/agent-product keeps its root export beside its subpaths.

The libraries a subpath needs are optional peer dependencies, so install the ones for the subpaths you import: @anthropic-ai/sdk, openai or @google/genai for a provider; ws, hono, the MCP or ACP SDKs and, for webrtc and link, @robota-sdk/agent-remote-pairing and @robota-sdk/agent-keyring for a transport carrier; koffi for agent-os/file-authority and agent-os/node-lock; and @robota-sdk/agent-core for an agent-interface family other than analytics and tui.

Need Help?

• GitHub Issues — report upgrade problems
• Getting Started — start fresh with 3.x patterns
• Architecture — how the 3.x packages fit together