What is an agent SDK? Claude, Codex, Cursor and Grok
By Flavio
An agent SDK is a library that runs an agent from your own program. How Claude Code, the Codex SDK, Cursor's two packages, and Grok Build differ.
An agent SDK is a library your program calls so an agent runs without you sitting in the terminal. Your code starts a task. The SDK runs the agent loop and returns the result.
How to use the OpenAI Agents API owns the OpenAI split. That post separates the Agents API, which OpenAI runs for you, the Agents SDK, which runs the loop inside your app, and the Responses API, where you write the loop. This entry is the short definition, then the libraries Claude Code, Codex, and Cursor document. Grok Build does not document one under that name.
How an agent SDK works
The terminal agent and the library share a harness. The harness calls the model, runs tools, and keeps the session. In the terminal, you are the one sending messages. With an SDK, your program sends them.
You still choose the model, the instructions, and which tools are allowed. The difference is who sits in the loop. Headless mode is the one-shot command-line version of the same idea. An SDK is the version you import.
Agent SDK in each tool
| Claude Code | Codex | Cursor | Grok Build | |
|---|---|---|---|---|
| Library | Agent SDK, Python and TypeScript. It runs the Claude Code binary | @openai/codex-sdk on Node, openai-codex on Python. Local Codex threads | Two packages. @cursor/sdk calls the IDE agent. @grok/agent-sdk defines an agent as code | Not documented. grok -p and ACP are the programmatic paths |
| Who runs the loop | The SDK, in a process you operate | The SDK, against local Codex | @cursor/sdk runs Cursor’s agent. Agent SDK runs a loop you defined in files | You write it, if you call the API yourself |
| Hosted alternative | Managed Agents, on Anthropic’s side | The Agents API, covered in the post linked above | Cloud runtime in @cursor/sdk, or Cursor-managed hosting for Agent SDK | The API. Not a Build SDK |
Claude Code
The Agent SDK gives you Claude Code’s tools, permissions, sessions, and hooks from Python or TypeScript. It runs the Claude Code binary. The overview separates it from the CLI, which is the interactive terminal, from the Client SDK, where you call the Claude API and write the tool loop yourself, and from Managed Agents, where Anthropic hosts the harness.
A third-party product cannot offer claude.ai login or those rate limits for an agent built on this SDK, unless Anthropic has approved it. The quickstart’s API key is the documented sign-in. See the Agent SDK overview.
OpenAI Codex
The Codex SDK controls local Codex from your program. The TypeScript package is @openai/codex-sdk. The page says to use it server-side, on Node.js 18 or later. startThread() opens a thread, and run() sends the prompt. The Python package is openai-codex, on Python 3.10 or later, and it talks to the local app-server.
The page lists CI, an internal tool, and embedding Codex in your own application. It points custom clients that need their own transcript and approval UI at the app server, not at this SDK. The Agents API in the post above is the hosted harness. This SDK is the local one. See the Codex SDK.
Cursor
Cursor documents two libraries, and they do not do the same job.
@cursor/sdk calls the agent that runs in the IDE, the CLI, and the web app. A local runtime runs the loop in your Node process against files on disk. A cloud runtime runs in a Cursor-hosted VM with the repo cloned in.
The Agent SDK, package @grok/agent-sdk, used to be @cursor/bdk. You define the agent as Markdown and TypeScript. Cursor runs the model loop that calls your tools. The page says that harness is the one behind Bugbot, Security Review, Approval Bot, and Rollouts. Install is npm install --global @grok/agent-sdk, then agent-sdk init. See Cursor TypeScript SDK and Agent SDK.
Grok Build
The Build overview does not document a library named a Grok Build SDK. The programmatic paths it does document are headless grok -p and the Agent Client Protocol.
The same page shows how to call grok-4.7 on the xAI API from the Vercel AI SDK, the OpenAI SDK, or xai_sdk. That snippet is a model call. You still write the loop around it. See Grok Build.
Details checked against each vendor’s documentation in November 2026.
A real example
This is the Codex SDK page’s TypeScript shape. It runs server-side, with the Codex SDK installed and a Codex login available to that process:
import { Codex } from '@openai/codex-sdk'
const codex = new Codex()
const thread = codex.startThread()
const result = await thread.run(
'Make a plan to diagnose and fix the CI failures'
)
console.log(result.finalResponse)run() again on the same thread continues the conversation. resumeThread() picks up a past one by id. The page uses those two when the plan should be implemented in a later step.
LangChain and LangGraph is the other place on this site where the loop lives in your TypeScript app, with a pause for approval. That guide is not the Codex SDK.
When to use an agent SDK
Use one when a program has to start the agent. A CI job, a bot, or a button in your own app are that case. Claude’s overview sends interactive daily work to the CLI instead.
Use the OpenAI Agents API, from the post linked at the top, when you want OpenAI to keep the session and run the harness. Use @cursor/sdk when the agent you want is Cursor’s. Use @grok/agent-sdk when you are defining a new agent as a folder of files.
Skip the SDK when you are already in the terminal and the task is one conversation. Headless mode covers the one-shot command if you only need a script.
Pitfalls
The Claude Agent SDK, the Codex SDK, Cursor’s @cursor/sdk, and Cursor’s @grok/agent-sdk are four libraries. Installing one does not give you the others. @grok/agent-sdk does not script the Cursor IDE agent. That is @cursor/sdk.
Claude’s overview blocks claude.ai login for third-party products built on the Agent SDK, unless that use was approved. The API key in the quickstart is the path the page allows.
The Codex SDK page’s TypeScript library is server-side. The sample above is not a browser snippet. The Python library talks to a local Codex app-server, and published builds pin a CLI runtime. Pointing it at a different codex binary is an explicit option, not the default.
Grok Build’s API sample is a single generateText or responses.create call. It does not start a grok session, and it does not load the project’s MCP servers for you.
Related on flaviocopes.com
- How to use the OpenAI Agents API is the hosted Codex harness, and the table that separates it from an SDK you run yourself.
- LangChain and LangGraph builds the loop in your own TypeScript process, including a stop for human approval.
- Headless mode is the command-line one-shot, for when you do not need a library.
Related glossary entries
- Headless mode: Headless mode runs a coding agent from a script, with no chat UI. How claude -p, codex exec, the Cursor CLI and grok -p differ on permissions.
- Agent loop: The agent loop is the cycle a coding agent repeats: look, act, check, and go again. How Claude Code names that cycle, and what the other tools document.
- Coding agent: A coding agent uses a model and tools to read a repo, edit files and run commands in a loop. How Claude Code, Codex, Cursor and Grok Build each do that job.
Want me to talk about your product? You can sponsor this site.