Map / Outline
SDKs and frameworks
What agent SDKs give you, mapped onto parts you have already built by hand.
What it is and why it exists
What
An agent SDK packages the harness: the tool loop, state handling, streaming, tracing, and often handoffs and guardrails. Frameworks differ in how much of the loop they own and how much you can replace.
Why
If you can name the part an SDK feature replaces, you can adopt or leave any framework without rewriting your system. The reference build is hand-written, which makes it a clear map for reading any SDK's documentation.
How it works
- Tool loop: every SDK has one. Compare its round limit, parallel tool handling, and what it does when the limit is hit.
- State: graph frameworks make state and merge rules explicit with reducers. That is merge_state under another name.
- Tools: most accept Python functions with type hints and MCP servers.
- Guardrails and hooks: input and output checks, and callbacks around tool calls.
- Tracing: spans per model call and tool call. It replaces JSON-lines logs.
- Keep your tools, skills, evals, and guard logic outside the framework so they survive a switch.
Where it sits in the build order
Needs first
- Harness engineeringYou evaluate an SDK by comparing it with a loop you understand. Without that, every framework's defaults look like requirements.Build out of order Stub it with: Follow a framework quickstart first, then return to the harness module to see what it hid.
- Tools and MCPTools are the part you carry between SDKs. Having them as MCP servers makes the comparison a configuration change.Build out of order Stub it with: One inline function tool.
Unlocks
Nothing depends on this. It is an end point of the map.
In the reference build
| Path | Role |
|---|---|
| apps/agent-server/ | The hand-built reference for every part an SDK provides. |
| study-notes/03_Agent_Harness_Deep_Dive.md | Notes on the harness design. |
| study-notes/08_Extending_The_Harness_Agent.md | How to add capabilities without breaking the contract. |
The same idea on other platforms
| Platform | How this module maps |
|---|---|
| Databricks | The agent framework accepts agents written with MLflow's agent interfaces, LangGraph, or the OpenAI Agents SDK, and adds deployment, tracing, and evaluation around them. |
| IBM watsonx | The Orchestrate ADK defines agents and tools in files and a CLI. It also imports agents built with LangGraph and similar frameworks. |
| Codex | The OpenAI Agents SDK provides the loop, handoffs, guardrails, sessions, and tracing. Codex itself can be run headless and scripted. |
| Cursor | Cursor provides a command-line agent and background agents. For your own service use a general SDK. |
| Claude Code / Agent SDK | The Claude Agent SDK exposes the coding agent's loop, tools, hooks, subagents, and MCP support as a library in Python and TypeScript. |
| Another machine | Any SDK that speaks the OpenAI-compatible API can target a local engine by base URL. |
Explain it back
Answer aloud first. Then open the answer and compare.
A framework advertises reducers for state channels. What is that in the reference build?
A strong answermerge_state. Keys that extend or sum are reducers. Keys that overwrite are plain channels.
What should stay outside any SDK?
A strong answerTools behind MCP, skill files, eval sets and scripts, and answer checks. Those hold your domain knowledge and should not be rewritten when the loop changes.
From the live build
Recent changes and files the sync job filed under this module.
- Claude Code → your own models
- Double-click button: gives Claude Code access to the knowledge bank. Built 2026-08-23, after a Claude Code session on local-qwen38 was asked about the agency a commodity spending and answered "I don't have that in my knowledge" — while brain.db held 144,781 atoms and the spending tables ...
- LocalAPI-Claude.command rev 2026-08-22b The one command for the Claude Code local API. Start, restart, or re-run after pulling a model. Idempotent.
- LocalAPI-Claude.command rev 2026-08-22b The one command for the Claude Code local API. Start, restart, or re-run after pulling a model. Idempotent.
- Disaster Emergency Fund Codes: the shared vocabulary. DEFC is how a federal dollar says which emergency, disaster or supplemental law it came from.
- Restart-Claude-Code-Gateway.command The one to double-click after editing config.yaml.