Agent SDKs — programmatic agent runtimes
This page is the SDK angle of Pillar 01 · Coding agents + agent runtimes. The two pages cover the same pillar:
- /system/harnesses/ — the runtime view (CLI tools + SDKs together, with the adapter contract)
- /system/agent-sdks/ (this page) — the SDK view (embedded library interfaces, when you build an app around an agent rather than running it as a CLI)
If you’re choosing between a CLI like Claude Code and an embedded SDK like Claude Agent SDK, start at harnesses. If you’re already committed to embedding an SDK and want to know which one, read on.
When an SDK (rather than a CLI)
You embed an SDK when:
- You want agent capabilities inside your own application or service — not a separate CLI process
- You need fine-grained control of session lifecycle, streaming, and tool registration
- You’re building a custom front-end on top of the orchestration substrate
- You’re writing agents that other agents invoke programmatically
You’d use a CLI like Claude Code when:
- The agent runs against a filesystem (a repo, a casefile folder)
- You want a unified session/skill/MCP model you don’t have to reinvent
- You’re invoked by the orchestration runner as a subprocess
Both shapes plug into the same LIFEOSAI adapter contract. The choice depends on where your agent’s work happens.
SDK options today
| SDK | Status | Strengths |
|---|---|---|
| Claude Agent SDK (TS + Python) | ✅ Production | The SDK behind Claude Code. Mature MCP, skills, sessions, hooks. Long-context reasoning. |
| Pi Agent SDK | ✅ Production-ready | The SDK behind Pi Coding Agent. Open-source, OSS-model friendly, custom permissions model. |
SDK options planned
| SDK | Why we plan to add it |
|---|---|
| OpenAI Agents SDK | OpenAI-shaped agents with function calling. Pairs with GPT-5. |
| LangGraph | Graph-shaped multi-agent flows when the structure matters more than the SDK choice. |
| Custom | When none of the above fit, the contract is open — implement the adapter interface and you’re in. |
What an SDK provides
| Concern | What the SDK exposes |
|---|---|
| Tool definitions | A way to declare functions or MCP servers an agent can call |
| Streaming protocol | How tokens, tool calls, and results stream back to your code |
| Session shape | What “conversation state” looks like + how it serialises |
| Hook points | SessionStart, PreCompact, UserPromptSubmit, PostCompact |
| Skill loading | How .md skill files get discovered and injected |
| Permissions | What tools can be invoked without explicit user approval |
How LIFEOSAI invokes any SDK
The orchestration substrate doesn’t import any specific SDK. Each agent’s adapterConfig tells the engine which runtime to dispatch to. The agent-invoker resolves the adapter, spawns or imports the right runtime, streams events back through the Event Normalizer (which unifies non-Claude streams to a single SDKMessage shape), and persists the run.
This is what “any SDK” means at the code level — the orchestration code doesn’t change when you swap which SDK an agent uses.