Can I use both together?

Yes, and this is increasingly common. Run the Claude Agent SDK on the server for heavy reasoning; run agentlib on the device for UI orchestration, on-device classification, offline fallback. They interoperate over JSON-RPC tool calls or MCP.

Does agentlib's API mirror the Claude SDK's?

Closely. AgentSpec ≈ Anthropic's agent descriptor; subagents map almost 1:1 with parallel + background added; skills use the same markdown bundle layout; hooks are a superset (21 vs ~10). Migrating Claude SDK code to agentlib for mobile use is mechanical.

What does the Claude SDK do that agentlib doesn't?

Anthropic-specific features: Workbench-managed prompts, prompt caching tuned to Claude billing, the batch API, native integration with Claude's MCP catalogue. agentlib uses the standard Anthropic Messages API and doesn't expose Anthropic-specific extras.

compare · vs Claude Agent SDK

agentlib vs the Claude Agent SDK — when to pick which

Side-by-side: agentlib (Dart, mobile-native, on-device + cloud) vs Anthropic's Claude Agent SDK (Python/TS, server-side, Claude). Same shape, different runtime.

The Claude Agent SDK was the first widely-adopted agent SDK with a clean primitive set — subagents, skills, snapshots, hooks. agentlib explicitly mirrors that shape. The difference is where the code runs.

Runtime

Claude Agent SDK: Python (anthropic-agents) or TypeScript (@anthropic/claude-agent-sdk). Runs in a Node, Bun, Deno, or CPython process. Spawns MCP subprocesses for tool servers.
agentlib: Dart (package:agentlib). Runs in a Flutter app process — iOS, Android, macOS. No subprocesses, no exec, no shell escape.

This is the load-bearing difference. The Claude SDK can’t ship inside an iOS app bundle without embedding a Node runtime, which Apple discourages and Android handles through painful JVM ceremony. agentlib is the native option.

Model providers

Claude Agent SDK: Claude only (by design — it’s Anthropic’s SDK).
agentlib: Seven providers — Anthropic, OpenAI, Google for cloud; Apple Foundation Models, Gemini Nano, MediaPipe, Fllama for on-device.

Either you want Claude specifically, or you want the freedom to pick the best provider per request. Pick accordingly.

Primitive surface

Roughly equivalent for the primitives both support:

Primitive	Claude SDK	agentlib
Agent descriptor	✓	`AgentSpec`
Subagents	sync only	sync / parallel / background
Skills	✓ (markdown bundles)	✓ (same shape)
Snapshots	partial	public API, SQLite-backed
Hooks	~10	21
MCP	HTTP	HTTP + WebSocket
Suspend / resume	✗	✓ + push-resume
On-device routing	✗	`ModelRoute.preferOnDevice`
Shell-shaped CLI	bash via Node	`Sh` mini-shell, sandboxed

agentlib adds the things mobile needs (lifecycle, on-device, push). The Claude SDK adds Anthropic-specific niceties (Workbench integration, prompt caching tuned to Claude billing).

Real-world stacks

We see three common patterns:

Backend-only. Claude Agent SDK on a Python/TS server. No mobile component. — Pick Claude SDK.
App-only. Flutter app with AI assistant features, possibly offline. — Pick agentlib.
Backend + mobile. Claude SDK pipeline on the backend; agentlib in the Flutter app. They talk over MCP or HTTPS. The cloud handles heavy lifting; the device handles UI orchestration, on-device classification, push-resume from server-finished jobs. — Use both.

Migration

Moving an existing Claude SDK pipeline to agentlib for mobile use is mostly mechanical:

Tool schemas (Zod / Pydantic) → Schema.object({...}) in Dart.
Subagent dispatch is the same shape; add mode: ParallelMode.parallel if you want concurrent.
Skills are the same markdown bundle layout; copy them across as-is.
Hooks: PreToolUse, PostToolUse, OnHandoff all exist with the same semantics.
MCP servers continue to work — agentlib speaks the same protocol.

The bottom line

If the agent runs on a server and Claude is the model, pick the Claude Agent SDK. It’s the most mature Anthropic-first SDK and there’s nothing to gain by switching.

If the agent runs on a phone — or you want on-device inference, or you need lifecycle handling, or you can’t ship a Node runtime — pick agentlib. The primitive shape is similar enough that the cognitive load of using both is small.

Pick agentlib if…

Your agent runs inside a Flutter, iOS, or Android app.
You need on-device models (Foundation Models, Gemini Nano, llama.cpp).
You can't ship a Node subprocess in your app bundle (App Store review).
You want native suspend/resume + push-resume + battery-aware routing.
You want to use multiple model providers (Anthropic + OpenAI + Google) behind one route.

Pick Claude Agent SDK if…

Your agent runs on a backend service in Python or TypeScript.
You only need Claude as the model and Anthropic-provided primitives.
You're already deep in the Anthropic ecosystem (Workbench, prompt caching, batch API).
You don't need on-device inference.
You want the most battle-tested cloud-only orchestration primitives today.

FAQ

Can I use both together?: Yes, and this is increasingly common. Run the Claude Agent SDK on the server for heavy reasoning; run agentlib on the device for UI orchestration, on-device classification, offline fallback. They interoperate over JSON-RPC tool calls or MCP.
Does agentlib's API mirror the Claude SDK's?: Closely. AgentSpec ≈ Anthropic's agent descriptor; subagents map almost 1:1 with parallel + background added; skills use the same markdown bundle layout; hooks are a superset (21 vs ~10). Migrating Claude SDK code to agentlib for mobile use is mechanical.
What does the Claude SDK do that agentlib doesn't?: Anthropic-specific features: Workbench-managed prompts, prompt caching tuned to Claude billing, the batch API, native integration with Claude's MCP catalogue. agentlib uses the standard Anthropic Messages API and doesn't expose Anthropic-specific extras.