Frequently asked questions
The things developers ask in the first hour. If your question isn't here, file an issue on GitHub.
agentlib is the mobile-native AI agent SDK for Flutter and Dart. It's an open-source (MIT) alternative to the Claude Agent SDK and OpenAI Agents SDK that runs natively inside iOS and Android app sandboxes — with both on-device models (Apple Foundation Models, Gemini Nano, llama.cpp via Fllama, MediaPipe) and cloud providers (Anthropic, OpenAI, Google).
Both are Python/TypeScript SDKs that assume a Node or Python runtime. iOS app sandboxes can't ship a Node subprocess, and Android requires a JVM service. agentlib is pure Dart with no subprocess, no exec, and platform channels for native on-device models — so the same agent code runs on a phone with no infrastructure to operate.
Yes. Out of the box it supports four on-device providers — FoundationModelsProvider (iOS 19+), GeminiNanoProvider (Pixel 8+, Samsung S24+), MediaPipeProvider (Gemma 3, Phi, Llama 3.2, Qwen on Android), and FllamaProvider (any GGUF model via llama.cpp). ModelRoute.preferOnDevice([...]) picks the first capable provider and falls back to cloud only when needed.
Frontier LLMs are trained on Unix CLIs. Sh gives the model a strict sandboxed shell with pipes, redirects, $VAR, and $(cmd) — but no real exec, no &, no eval. So Sh("contacts grep 'Mom' | jq -r .number | xargs whatsapp send --message 'Late'") works as one tool call, with the LLM speaking an idiom it already knows fluently.
No. agentlib is MIT licensed and free. You only pay model usage if you use cloud providers (Anthropic, OpenAI, Google). On-device providers are free.
v1.1.0 (current) ships MCP WebSocket transport, SQLite-backed snapshot store, and in-loop handoffs on top of the v1.0 surface. The API is stable and the test suite is comprehensive. We treat 1.x as production for the documented surface; experimental APIs are tagged explicitly.
It works on macOS for development (Foundation Models on macOS 26+ included) and as a Flutter desktop target. Production focus is iOS and Android — that's the mobile-native pitch — but the same agent code runs in a Flutter macOS app.
LangChain and LlamaIndex are Python data-pipeline and RAG frameworks. agentlib is an agent SDK focused on the agent loop itself — streaming, tool calling, subagents, hooks, snapshots — and it's native to mobile. The two solve different problems; if you need retrieval, you'd plug a retrieval tool into an agentlib AgentSpec.
Yes. Implement the ModelProvider interface — it's two methods: stream(request) returning an event stream, and a capabilities getter. Wrap any HTTP API, local llama.cpp binding, or ONNX runtime that way.
FllamaProvider ships family-aware tool-call parsers for Qwen, Llama 3.2, Phi-4, and Gemma 3 — they format tool calls slightly differently and agentlib handles each. For models without native tool calling, Sh-style JSON-in-a-block prompting is the recommended fallback.
Every Runner state is serialisable. agentlib emits OnSuspend hooks before the OS pauses you, and OnResume when you come back. For longer runs, the app can push a snapshot and resume from APNs/FCM via resumeFromPush(payload) — the backend can wake the agent to keep working.
agentlib ships HTTP and WebSocket MCP transports. WebSocket gives you full-duplex notifications on McpClient.notifications. MCP tools are translated to native Tool objects and registered in /bin/mcp.<server>.<tool> — so they show up as CLI commands the model can pipe.
Mark such tools highImpact: true. agentlib auto-snapshots before the dispatch, and the PermissionRequestHook can surface a native consent sheet to the user. If the action goes wrong, revert() rolls everything back to before the snapshot.