Agent SDKs and APIs

Picture a service that reviews code changes. When a pull request is opened, an agent (an application that steers the steps of a model and its tools towards a defined result) has to read the description and the code diff, run the permitted checks, write a short report and hand it to a human. Do you need a dedicated agent software development kit (SDK) for this, or is it enough to call the model through an application programming interface (API)? And if the work is interrupted just after a comment has been posted, who makes sure it is not posted twice?

This unit shows how to tell apart a model, an API, a client library, an agent SDK and a managed agent service; how to choose where responsibility sits between your own application and the provider; and how to decide where to store state, how to handle retries and stopping, and what counts as proof of completion. It assumes familiarity with the agent's tool loop from how AI coding agents work, the real-system examples in AI agent security and continuous integration, reliable delivery as covered in production incidents and incident runbooks, and agent observability.

Find the boundary between the model, the SDK and the runtime

One word, "agent", names different parts

A model generates the next piece of content from the context it is given. An application programming interface is a network contract through which a program sends a request to a service and receives a response. A software development kit is a library plus supporting code for calling an API or running an agent from a program. An SDK can simplify authentication, event streaming, retries or type conversion, but having one does not mean the provider executes your business logic.

An agent loop is the sequence in which a program gives the model a goal, receives a response or a tool request, carries out the permitted action, returns the result and continues until it stops. A harness is the implementation of that loop together with the rules for tools, context, stopping, permissions and observation; it is the term the providers themselves use. In your application, the harness can be a small function, an SDK or a separate provider service.

Part	What it does	Typical responsibility
Model	Produces text, structured data or a tool request	Choice of model, version, request limits and token budget
API	Accepts a request and returns a response or events	Network interaction, the contract and product-specific capabilities
Client SDK	Helps call the API from a particular programming language	Network requests, types, streamed events, errors, sometimes an automatic tool loop
Agent SDK	Runs a ready-made loop or provides building blocks for one	State of an individual run, tool routing, coordination
Application	Connects the agent's work to users and domain systems	Identity, business rules, access, permissions, audit and acceptance
Runtime environment	Gives the agent process a file system, network, shell or isolation	Resources, secrets, limits and the execution life cycle

The word "session" has no universal meaning either. It can mean a model conversation, a record in the provider's storage, a process in a sandbox, or your own domain request for a review. Before integrating, find exactly the resource you need in the documentation, along with its lifetime, deletion, versioning, limits, reconnection behaviour and retention policy. OpenAI explicitly separates an Agents API session, an SDK session, a Responses API conversation and a sandbox; Anthropic separately describes the Messages API, the Claude Agent SDK and Managed Agents.

The current map of provider tools

The state described below was checked on 10 October 2026. It describes the products and documentation on that date and is not a guarantee that they will stay the same. Before starting a new project, confirm the status, supported features, compatibility, region, plan and retention rules in the current official sources.

Need	OpenAI	Anthropic
Call the model and build the control logic yourself	Responses API; your application implements the loop for client-side functions and the rules for continuing	Messages API; your own loop or the beta Tool Runner in the client SDK
Run a managed agent loop	Agents API: a managed Codex harness, sessions, orchestration and managed context compaction; public beta	Managed Agents API: agent, environment, sessions and event stream; beta
Use a coding agent on your own infrastructure	Codex SDK: runs the Codex harness under the control of your own infrastructure	Claude Agent SDK: a Python or TypeScript library that runs Claude Code as a programmable process
Use a general-purpose client library	Official API clients for the languages and environments listed in the documentation	Messages API clients for Python, TypeScript, C#, Go, Java, PHP and Ruby

OpenAI. The documentation distinguishes three boundaries. The Agents API hands control of the loop, sessions, context compaction and recovery to a server-side Codex harness; the application supplies the tools and chooses the runtime environment. The Agents SDK runs the agent loop inside your application and gives the team control over deployment, storage, approvals and integrations. The Responses API gives direct access to the model and managed capabilities, while your own loop for functions and the rules for finishing remain the application's responsibility. The Agents API is in public beta: it was announced on 10 September 2026.

The Agents API stores session state so that work can continue, and that fact has to be reflected in your data policy: at present data residency is available only in the United States, and Zero Data Retention (ZDR) mode is not supported. Choosing your own sandbox does not make the service ZDR-eligible. Sessions and published artefacts can be deleted once the work is finished; before integrating, check the current retention rules for the specific product and contract.

Codex SDK. This is a separate way to drive local Codex threads through an app server; it is not another name for the Agents API or for a direct Responses API call. The TypeScript library runs in a server-side Node.js 18 or later environment; the stable Python package openai-codex requires Python 3.10 or later. Requirements and available capabilities depend on the language and version, so pin the package version and the lock file.

Anthropic. The Messages API gives direct access to the model: the client SDK handles network requests, and your application executes its own client-side tools and returns their results. The beta Tool Runner runs a common agent loop and manages conversation state, but leaves the process and the product integration in your application. The Claude Agent SDK provides Claude Code's tools, loop and context management as a programmable library for Python or TypeScript; the Claude Code CLI remains a separate interactive tool.

Managed Agents moves the harness onto Anthropic's infrastructure. Every request to it needs the beta header anthropic-beta: managed-agents-2026-04-01; sessions keep the conversation history, sandbox state and results on the server. For that reason Managed Agents does not currently support ZDR and is not covered by a Business Associate Agreement (BAA) under the Health Insurance Portability and Accountability Act (HIPAA), the US law on health insurance portability and accountability. On Claude Platform on AWS, an autonomous session with no user events can run for up to six hours, after which it needs to re-authenticate; a session in a self-hosted environment cannot attach an agent memory store there, although a session in a cloud environment can. These are limitations of the AWS surface: Claude Managed Agents accessed directly has no such autonomous session limit and supports memory stores in self-hosted environments as well. Do not carry these properties over from one Anthropic product to another.

Package versions are a fast-changing snapshot, not a recommendation to install the latest release. As of 10 October 2026, the manifests of the main Python repositories list openai-agents 0.23.1 and claude-agent-sdk 0.2.165; the latter carries the Alpha classifier, meaning an early stage of development. This is repository metadata, not a guarantee of identical publication in every environment. For a reproducible build, pin the package version and the dependency lock file rather than relying on latest.

A function call is not yet its execution

A tool call is a structured request from the model that proposes an operation name and arguments. By itself it does not confirm that the operation was carried out. In a typical loop, the application sends the model a description and schema of the available tools; the model returns a call request; the application checks the arguments, authorisation and policy; a permitted handler performs the action; and the application returns the result and asks the model to continue. If the tool runs on the provider's side, as some search tools do, that step is handled there under the provider's contract.

An argument schema helps check the shape of the data, but it does not replace authorisation. The model must not decide which database rows, repositories or accounts a user can access. Check the subject identifier, the resource and the action in your own server-side code. For every tool, decide whether it reads, changes or deletes state, what data it can return, how long it may run, and whether it needs human consent.

Fully worked example 1: the agent looks up task status but does not create a task. An engineer asks: "What is blocking release 2.4?" The application provides a read-only tool, lookup_tasks(project, release), which reads only the projects and releases available to that engineer. The model returns a call with project="payments" and release="2.4". The server checks the read permission again, retrieves two tasks with their status and owner, masks the field containing internal notes and passes a short result to the model. The model replies: "The release is blocked by A-18, payment schema review, owner Nina; and A-23, confirmation from the provider, owner Marko."

The observable result is two links to existing tasks and their actual statuses. A piece of advice in the text, such as "create a separate task for the review", does not create a Jira record: that would need a different tool with write permission, its own authorisation and a defined approval process. The trace should keep the run identifier, the tool name, the read scope, the duration and the result, without needlessly copying private text. The example works because reading and recommending have an explicit boundary and a verifiable result.

The sketch below is explanatory pseudocode, not the syntax of any particular SDK:

PSEUDOCODE
response = model.respond(question, tools=[lookup_tasks])
if response.requests_tool("lookup_tasks"):
    args = validate_schema(response.tool_input)
    authorize(user, action="read", project=args.project)
    result = task_store.lookup(project=args.project, release=args.release)
    response = model.continue_with(tool_result=result)
return render_answer(response)

Decide where to keep context and state

Conversation context is not durable work state

Context is the data the model sees in a particular request or turn. It can include messages, a summary of earlier work, retrieved documents and tool results. Context is limited by the model's window; it does not become durable memory just because the conversation is called a "session".

Durable state is a record that the application or a managed service can restore after a process restart. For a domain request, such as a review of a pull request (PR), store your own identifier, the owner, the code revision, the current stage, permissions, the deadline, attempts, links to artefacts and the review summary. Store the provider's keys if you need them to continue, but do not make an external session the only source of your business state when the work has to carry a result through to the product.

Data	Example	Where it is usually kept
Conversation or turn	The engineer's question and the previous answer	Responses or Messages history, or an SDK session, subject to the retention policy
Task progress	"The scan passed; two of four files reviewed"	The application's durable store or a workflow engine
Artefact	A report, patch, test log or comment identifier	A controlled store or a runtime artefact, with a link in the domain record
Runtime environment	Working directory, container, process	The life cycle of the managed session or the team's infrastructure
Memory	A conclusion that can be reused later	An explicit store with a lifetime, access rules, provenance and a way to correct it

Storing a conversation and having memory are also different things. History is the recorded earlier messages. Memory is selected information that a future run can include in a new context. It has to be curated, versioned, restricted by permissions, and deletable if its source is withdrawn or goes out of date. A session can restore a conversation, but it will not necessarily restore your message queue, a local file, a transaction or a right to act.

Retries, stopping and recovery are separate contracts

Distinguish four states:

• A timeout means the caller stopped waiting after the allotted time; the server or the external tool may already have performed the action.
• Cancellation asks the process to stop further work, but it does not roll back a payment, a database write or a command that has already happened.
• A dropped stream may mean only that the client lost its connection while the agent carries on working.
• A task deadline defines when the product must receive an acceptable result.

Set the network timeout, the agent's time limit, the cancellation signal, the user-facing task deadline and the reconnection behaviour separately.

Idempotency is the property of an operation whereby repeating the same logical request creates no additional side effects. It is usually implemented by the service that performs the write: the application passes a stable operation key, and the service atomically stores the key together with the result. The key must represent one intended action, not each network attempt. If the external service does not support idempotency keys, you need a reconciliation read, a deduplication rule or manual handling of the uncertain outcome; a blind retry can double the action. This design rests on the contract of the service performing the write, not on a promise from the model.

Fully worked example 2: the process crashed after the write but before confirmation. The agent opened a pull request (PR; a request to merge changes into a shared branch) and called post_review_comment. The PR service accepted the comment, but the local process lost its connection before it recorded the tool response in its session. On recovery, a naive loop sees "no result" and posts the same comment a second time. The Anthropic Python client has a reported narrow scenario with a similar failure boundary: after a failure to submit a tool result, the tool was re-queued while the stream was being resumed; the reporter supplied a test showing two executions instead of one. Issue #1749 was opened on 11 July 2026, and the page showed it as open on the date it was checked. The report concerns one specific SDK code path; it is not a claim about all Agent SDKs or Managed Agents. Details and the limits of the reproduction.

A more reliable path first records the intent in a durable store with the state pending and a unique idempotency key (a stable identifier for one intent) such as pr-912-review-comment-v3. Before the network call it stores in_flight, and it moves to confirmed only after a response or an unambiguous reconciliation with the external resource. After a timeout or failure, in_flight remains uncertain until the application finds that exact unique key, or a client-side operation marker, in the external system, if the API lets you store and search for one. Similar text or a matching revision is not enough: the match may be unrelated or belong to an earlier attempt. If the API supports an idempotency key, retry the request with the same key. If it does not, reconcile state using the unique marker; if the marker cannot be found or matched unambiguously, leave the operation as unknown for manual review and do not create the record automatically. Storing state, making the external write and confirming it cannot always be combined into one transaction; that gap is exactly why reconciliation is needed. The Amazon Web Services (AWS) guidance on safe retries explains idempotency keys and their atomic link to the side effect.

In practice, separate retries by boundary: retrying a read-only network request, re-fetching a stream, re-executing a function, and resubmitting an external write. For each, specify the maximum count, a delay with random jitter, the error class, the time budget and the stopping condition. Argument validation errors or authorisation refusals are usually not worth retrying without changing the request. Some SDKs let you serialise or restore run state; before relying on that, find out which parts it covers and whether it is safe to repeat tool calls that had already started.

Design a controlled and verifiable runtime

Streaming and orchestration need visible completion rules

Streaming sends the result in pieces before the whole turn has finished. It shortens the time to the first signal and lets you show progress, but partial text is not a finished domain result. Event names depend on the product: in the OpenAI Responses API, response.completed marks a finished response; in the Agents API, agent.session.turn.completed marks a finished turn; in Anthropic Managed Agents, the session.status_idle event can indicate that the agent is waiting for an external action (stop_reason.type = requires_action). These are technical states under different contracts, not proof of an accepted business result: idle can mean waiting, and a finished turn does not guarantee that every tool succeeded. OpenAI Responses streaming events, OpenAI Agents session events and the Anthropic event stream describe different names and states.

Orchestration is the control of the sequence of work across agents, tools and checks. In a simple case it can be a "model → tool → model" loop. Longer work adds a queue, a deadline, a state store, recovery, human approval and notification of the result. Several agents are useful when they have independent sources or roles and the merging of their results can be verified. Additional agents do not remove the shared budget, access control or idempotency; merging their conclusions also needs a defined rule.

Before a production launch, give every session or task:

• an overall deadline and separate timeouts for the model, the tool and the external service;
• limits on concurrency, number of cycles, tokens and money;
• a cancellation signal, behaviour on client loss and a recovery rule;
• explicit states such as queued, running, waiting_for_approval, retrying, completed, failed, cancelled and unknown;
• a criterion that turns technical completion into a result accepted by the product.

Do not infer the state of a business task from a successful server response or a closed socket. An API response may only confirm that the work was accepted into a queue. Conversely, a dropped stream does not mean the server stopped the job. Subscribing to events, polling for status and webhooks are all ways to receive updates; the choice between them depends on delivery guarantees, session lifetime and freshness requirements. Event and webhook handlers must accept duplicate messages without changing domain state twice.

Security, observability and cost belong to the design

Give the model only the data the task needs; keep secrets in a secret store and inject them into the process only during a permitted operation. Run shell commands and file operations in the least privileged environment, and limit network access, directories, duration and resource usage. Treat text from files, web pages, pull requests and tool results as untrusted input: it must not override server policy. For writing, publishing, deleting, paying or changing access, apply separate permissions and, where the risk calls for it, human approval. OpenAI's sandbox security guidance specifically emphasises isolation, network restrictions and keeping secrets outside the agent's code.

For investigation, store the identifiers of the user and the task, and the versions of the model, SDK and configuration, the prompt or rule set, the tools, the environment, the run and any related external actions. Record start and end, states, latencies, costs, errors, the reason for each retry and links to artefacts. Do not record the model's hidden reasoning and do not copy full private content into logs by default; trace retention must match access rules, retention periods and data requirements. This continues the practice of correlating tasks, events and confirmed results described in agent observability. In the OpenAI Agents API documentation, recorded usage may be missing or may still change, so null does not mean zero and is not a final bill; see Observability and usage and Tracing. For a formal improvement cycle, add control sets and scores: Evaluate agent workflows; task evaluation is covered in depth in agent evaluation.

Do not judge only the price of a single call. Count the costs of the session, tool execution, the environment, the queue, retries, infrastructure and human review. Add automatic scoring on a set of real tasks and checks of dangerous scenarios; agent evaluation keeps evaluating an agent separate from observability, and the economics of an AI studio includes support and review in the full cost. A provider's built-in limit is not necessarily the same as your client's spending ceiling: check when it stops, the currency, the counter and the behaviour after the limit is reached. The full economics and stopping policy are covered in the economics of an AI studio.

Choose the smallest boundary of control that fits

Start from the business requirements: can the work last minutes or hours, who executes the code, what data is stored, and do you need a detailed audit and full control over execution time? Then match the answers to a runtime approach:

Approach	When it fits	What stays with your team
Direct API and your own loop	A short, bounded task, or you need precise control over every step	The loop, state, retries, tools, budget, telemetry, continuation and stopping
Agent SDK inside your own service	You want ready-made tool and orchestration primitives, but with your own product rules and infrastructure	Deployment, persistent state, permissions, integrations, observability and SDK upgrades
Managed agent API	You want a ready-made managed loop, events and long-running sessions without maintaining the whole harness yourself	Product integration, the tool handler, permissions, data, acceptance, costs and an exit plan

A managed service can reduce code and operational load while tying part of your state and interfaces to the provider. An SDK on your own infrastructure gives you more control, but the team takes on maintaining the runtime, version compatibility, isolation, secrets and recovery. A short loop of your own has the fewest new concepts, but you have to implement retries and timeouts responsibly. Task duration is only one axis of the choice: also weigh data boundaries, regions, contract terms, expected volume, skills and the cost of ongoing maintenance.

Fully worked example 3: choosing a runtime for PR review. A team receives about thirty PRs a day. Each has up to fifteen files; the agent has to check style, run up to three read-only checks, draft comments without posting them automatically, and finish within two minutes. The code does not need its own file sandbox, and the team already has a web service with a queue, identity and logging.

The team has three options:

• Responses API. A short controlled loop on the team's server fits, because the work is bounded, the tools are read-only, and the server already has the necessary access boundaries and tracing. At a few hundred reviews a day, scaling your own loop may be simpler than maintaining a general-purpose harness.
• Agents SDK. It fits if the team wants to standardise routing, handoffs to checks and tracing across several agent processes. It is not an automatic advantage for a simple pattern; the team remains responsible for deployment, state, permissions, integrations and SDK upgrades.
• Agents API. It is worth considering if longer reviews, managed sessions and environment isolation become necessary, and the price, processing region and retention terms meet the requirements.

The team starts with a short Responses API loop: the existing queue already enforces time and concurrency limits, and the output report is shown to the PR author for review. The choice is tested on a set of completed PRs, measuring the share of useful findings, missed defects, costs and latency; every suggestion goes through human review. If the need for long sessions or a sandbox appears, the team will reassess the Agents API and estimate the cost of migrating. The decision rests on the actual requirements, not on a rule such as "managed is always better" or "your own is always cheaper".

Summary

An API describes a network contract, an SDK simplifies working with it or provides agent primitives, and a harness runs the loop and connects the model to its tools. Managed and self-run runtimes differ in where execution happens, how much control you have and who is responsible; neither replaces the application's business rules. Treat a timeout as an unknown outcome, keep durable state separately, and reconcile retries of external writes with an idempotency key or a recovery read. Judge the choice on the task you actually need done, with evidence of quality, cost, security and maintenance effort.

Sources and further reading

• OpenAI, Agents, compares the Agents API, Agents SDK and Responses API and divides control of the loop and state between them; Agents API overview describes sessions, data retention, residency and ZDR limits; Agents API architecture covers the harness, environments and the application's responsibility; the API changelog records the Agents API's release into public beta on 10 September 2026. Checked 10 October 2026.
• OpenAI, Agents SDK, describes code-level control of the loop, state, tools and integrations; Function calling explains the tool request and the return of its result; Responses API: conversation state covers the boundary between API context and application state. Checked 10 October 2026.
• OpenAI, Codex SDK, describes the local app server, TypeScript support and the stable Python SDK, and the environment requirements; Agents API quickstart gives the current beta header OpenAI-Beta: agents=v1. Checked 10 October 2026.
• Anthropic, Claude Agent SDK overview, distinguishes the CLI, the Agent SDK, the Client SDK and Managed Agents; Tool Runner describes the beta loop and its supported languages; How tool use works covers client-side and server-side tools and the request/result loop. Checked 10 October 2026.
• Anthropic, Managed Agents overview, describes the beta status, Agent/Environment/Session/Events, server-side storage and the ZDR/HIPAA limitations; Start a session and Session event stream cover the life cycle and events; Claude Platform on AWS covers the differences of that environment. Checked 10 October 2026.
• OpenAI, Sandbox security, on isolation, network boundaries and secrets; Observability and usage and Tracing, on accounting and tracing; Evaluate agent workflows, on control sets and scores. Checked 10 October 2026.
• OpenAI, openai-agents Python package manifest, lists version 0.23.1 and Python 3.10+; Anthropic, claude-agent-sdk Python package manifest, lists 0.2.165, Python 3.10+ and the Alpha classifier. This is metadata from the repositories' main branches, checked 10 October 2026, not a guarantee of the published version. For the Codex SDK, the official page was checked: TypeScript requires Node.js 18+, Python requires 3.10+, and the Python release is marked stable.
• Anthropic, issue #1749 in anthropic-sdk-python, contains a test reproduction of a tool being executed again after its result failed to be submitted. It is a report on one specific SDK scenario, not broad statistics or a claim about all agent products; viewed 10 October 2026.
• Anthropic Engineering, Effective harnesses for long-running agents, 26 November 2025, on loss of context between sessions and the role of initialisation, intermediate artefacts and verifiable progress; viewed 10 October 2026.
• Malcolm Featonby, AWS Builders' Library, Making retries safe with idempotent APIs, 15 January 2021, on idempotency keys and the atomic link between the key and the side effect; checked 10 October 2026.