CH 01 · Anatomy of an AI Agent · 10/12
Read as one pageReal code: in pi, the model call is one line of a long file
pi's packages/ai is a library that talks to many LLM providers behind one interface. This is its Anthropic adapter, a file of about 1,700 lines. The line that actually calls the model is marked [5]. Everything around it is the system this section describes: building the request, retrying, cancelling, and recovering when the provider rejects a request.
const requestOptions = {
...(options?.signal ? { signal: options.signal } : {}),
...(options?.timeoutMs !== undefined ? { timeout: options.timeoutMs } : {}),
maxRetries: 0, // [1]
};
let disablePreferredStrictTools = false;
let response: Response;
for (;;) {
options?.signal?.throwIfAborted();
const built = buildParams(model, normalizedContext, isOAuth, options, disablePreferredStrictTools); // [2]
if (built.providerThinkingLevel) output.providerThinkingLevel = built.providerThinkingLevel;
let params = built.params;
const nextParams = await options?.onPayload?.(params, model); // [3]
if (nextParams !== undefined) {
params = { ...(nextParams as MessageCreateParamsStreaming), stream: true };
}
try {
response = await retryProviderRequest( // [4]
() => client.beta.messages.create(params, requestOptions).asResponse(), // [5]
{
maxRetries: options?.maxRetries,
maxRetryDelayMs: options?.maxRetryDelayMs,
signal: options?.signal,
},
);
break;
} catch (error) {
// Only downgrade a rejected request, never an already-started stream.
// ... (15 lines: rethrow unless it is a 400 saying the strict tool schemas are too large)
disablePreferredStrictTools = true; // [6]
// ... (6 lines: record a diagnostic on the reply)
}
}
Source: earendil-works/pi, packages/ai/src/api/anthropic-messages.ts (MIT)
What to notice
- [1] The Anthropic SDK (the official client library) retries failed requests by default.
maxRetries: 0turns that off so retries happen in exactly one place, [4], instead of stacking. - [2]
buildParamsconverts pi's provider-neutral conversation,normalizedContext, into Anthropic's request shape: messages, tool definitions, system prompt, cache markers, thinking settings. - [3]
onPayloadis a hook that lets the caller inspect or replace the exact request body before it is sent, which is handy for logging or a last-minute override. - [4]
retryProviderRequestretries only errors it classifies as retryable, waits between attempts, and stops at once if the user cancelled.signalis anAbortSignal, JavaScript's standard way to cancel async work. Unless the caller asks for retries, it makes one attempt. - [5] The model call itself.
MessageCreateParamsStreamingis the Anthropic SDK's type for a streaming request. - [6] Strict tool schemas ask the provider to force tool arguments to match their schema exactly, and Anthropic rejects a request whose strict schemas are too many or too complex. If Anthropic returns that 400 and the request still has preferred-strict tools, pi sets the flag and loops, rebuilding so tools marked
strict: "prefer"are no longer strict. Other strict tools stay strict. Every other error is rethrown.
A rethrown error does not escape as a crash. The function's outer catch pushes an error event. stopReason is "aborted" if the caller cancelled, and "error" otherwise. pi's agent loop ends the turn on that message instead of throwing. A bare await client.messages.create(params) works in a demo and, in production, stacks a second retry policy, cannot be cancelled, and lets one provider quirk take the turn down.
Read it yourself: open packages/ai/src/api/openai-completions.ts and compare: is the same maxRetries: 0 plus retryProviderRequest wrapper there? Then read the StreamFunction type in packages/ai/src/types.ts. Chat adapters share that one signature, which is what makes the model a component you can swap. Image and classifier adapters in this folder use other types.
Finished this idea?
Your learning progress stays in this browser.