Documentation
¶
Overview ¶
Package anthropic is the anthropic dialect: Claude through the Messages API, first-party and on Vertex AI (docs/design.md §7.3, phase L4).
It adapts the official SDK (github.com/anthropics/anthropic-sdk-go): a genai-shaped llm.Request becomes a MessageNewParams, and the SSE stream is accumulated back into genai-shaped Responses. The shape is mast's — option structs, no registry, usage in usage.Detail — and the behavior core-agent built after the two copies split is ported onto it: rolling and one-hour prompt caching (cache.go), per-call opt-outs through callctx, and the positional schema normalizer. The thinking-request shape is mast's, chosen per model generation.
Retries ¶
The SDK's own retries are off. Package retry's Transport does it in the HTTP client instead, as for every other dialect, so a 429 is handled the same way whichever model a workload names and each attempt carries a fresh credential.
Vertex AI ¶
Claude on Vertex is the same Messages body sent to a different URL: the model moves from the body into the path, and the body carries an anthropic_version. Options.Vertex turns that rewrite on; see vertex.go. It is done here rather than through the SDK's vertex package so that the credential is core-models' own (package auth) and the core module takes no golang.org/x/oauth2 or google.golang.org/api dependency.
Index ¶
Constants ¶
const ( // TTL5m is the five-minute breakpoint, Anthropic's default. Writes // bill at 1.25x base input. TTL5m = "5m" // TTL1h is the one-hour breakpoint. Writes bill at 2x base input, // so it only pays when consecutive requests are routinely more than // five minutes apart. TTL1h = "1h" )
Prompt-cache breakpoint lifetimes, for CacheOptions.TTL.
const DefaultBaseURL = "https://api.anthropic.com"
DefaultBaseURL is the first-party API root.
const DefaultMaxTokens = 16_384
DefaultMaxTokens caps a single response when the request sets no MaxOutputTokens. 16K is plenty for most turns and well under the streaming HTTP timeouts.
const VertexVersion = "vertex-2023-10-16"
VertexVersion is the anthropic_version Vertex AI requires in the body of every Claude request, in place of the first-party anthropic-version header.
const WebSearch = "web_search"
WebSearch is the provider-neutral name for Claude's web_search, the one built-in this adapter surfaces.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type APIError ¶
type APIError struct {
// contains filtered or unexported fields
}
APIError is an error the Anthropic API answered with. It wraps the SDK's *anthropic.Error, which errors.As still finds, and adds the HTTPStatus method products classify retryable failures by — the same method openaichat.APIError has, so one check covers every dialect.
An error can arrive two ways. Before the stream starts it is an ordinary non-2xx response, which package retry has already retried if the status allowed. After it starts, the server sends an SSE error event on a response that answered 200 — an overloaded_error midway through generation, say. The transport cannot retry that: tokens may already have reached the caller, and replaying the request would deliver them twice. HTTPStatus then reports the status the error's type stands for (overloaded_error is 529), not the stream's 200, so a product's own retry policy can still tell a transient failure from a permanent one; MidStream says which case it was.
func (*APIError) Error ¶
Error is the SDK's message with the URL corrected. The SDK names the request as it built it; on Vertex AI the middleware then rewrote it (…/v1/messages → …/models/<id>:rawPredict), and a message naming the path that was never called sends anyone reading logs to the wrong endpoint (#35). The response carries the request actually sent.
func (*APIError) HTTPStatus ¶
HTTPStatus is the response's status, or for a mid-stream error the status its type stands for.
type BuiltinTools ¶
type BuiltinTools struct {
WebSearch bool // Server-side web search; per-search billing on top of tokens.
}
BuiltinTools toggles Anthropic's server-side built-in tools surfaced by this provider. Each enabled flag becomes one entry on the request's Tools slice alongside any user-defined function declarations.
Defaults: everything OFF. Anthropic's server-side tools are billed per use on top of token cost (web_search is per-search), so we apply the same "active surface = opt in" rule that keeps Gemini's CodeExecution off by default. The library caller decides explicitly whether the cost and external-action posture are acceptable.
To turn one on:
c, _ := anthropic.New(anthropic.Options{
…,
BuiltinTools: anthropic.BuiltinTools{WebSearch: true},
})
callctx.WithoutBuiltins drops them for one call.
Other Anthropic server-side tools (web_fetch, code_execution, text_editor, bash, memory) aren't surfaced today. Add them under the same struct when a concrete consumer needs one.
func BuiltinToolsFromNames ¶
func BuiltinToolsFromNames(names []string) (BuiltinTools, error)
BuiltinToolsFromNames maps provider-neutral names onto the toggles. A name Claude has no tool for — url_context and code_execution are Gemini's — is an error, not a silently absent tool, as for the gemini dialect.
func (BuiltinTools) Names ¶
func (b BuiltinTools) Names() []string
Names reports the enabled built-ins under the provider-neutral names mast's and core-agent's builtin_tools blocks use, so a report reads the same whichever provider is resolved and an operator can match it against the keys they typed.
The block's url_context and code_execution are Gemini-side and have no Anthropic equivalent, so they can never appear here. That is the direction that fails safe: a tool this provider cannot send is one it cannot leave on.
type CacheOptions ¶
type CacheOptions struct {
// System marks the last system block. Since the render order is
// tools → system → messages, that one marker caches the tool
// schemas and the system prompt together.
System bool
// History places rolling breakpoints over the tail of the
// conversation so a growing transcript is re-read at the cache
// rate instead of re-billed in full every turn (core-agent #714).
History bool
// TTL is the breakpoint lifetime: TTL5m (the zero value's meaning)
// or TTL1h. Both are priced, and the response reports which one
// each write used (usage.Detail.CacheWrite1hTokens), so the ledger
// is right either way (core-agent #770). Any other value is treated
// as TTL5m.
TTL string
}
CacheOptions selects which parts of a request carry Anthropic cache_control breakpoints. Both halves are prefix-cached by the same mechanism; they're separable because they fail differently — System is worthless if the instruction carries a per-turn timestamp, History is worthless for one-shot calls that never replay a prefix.
The zero value disables caching entirely.
func DefaultCacheOptions ¶
func DefaultCacheOptions() CacheOptions
DefaultCacheOptions caches the stable prefix and the conversation tail at the five-minute TTL. coremodels.Open applies it unless told otherwise: the break-even is two requests against a 5-minute TTL, and an agent loop issues its second request seconds after the first. The shape that loses — a single request whose prefix is never seen again — is a side call, and callctx.WithoutPromptCache turns caching off for exactly that call.
func (CacheOptions) Enabled ¶
func (o CacheOptions) Enabled() bool
Enabled reports whether any breakpoint would be placed.
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client holds one configured SDK client. It is safe for concurrent use, and every model it returns shares its connection pool.
type Options ¶
type Options struct {
// BaseURL is the API root. Empty means DefaultBaseURL. With Vertex
// set it is the publisher prefix
// .../projects/{p}/locations/{r}/publishers/anthropic/models, and a
// request goes to BaseURL/{model}:streamRawPredict.
BaseURL string
// Credential authenticates every request: an api_key credential as
// x-api-key, as the first-party API expects, and any other kind as
// a bearer token (Google ADC on Vertex, or a gateway's token). Nil
// sends none.
Credential *auth.Credential
// Vertex routes requests the way Vertex AI serves Claude.
Vertex bool
// HTTPClient supplies the base transport and timeout. Nil means a
// client with http.DefaultTransport. coremodels.Open puts a profile's
// headers in it (profile.Resolved.HeaderTransport); a host building
// this client itself does the same.
HTTPClient *http.Client
// Retry is the HTTP-layer retry policy. Nil means retry.Default().
Retry *retry.Policy
// Backend and Region are stamped into every usage.Detail.
Backend string
Region string
// Cache is the prompt-caching policy. The zero value places no
// breakpoints; coremodels.Open passes DefaultCacheOptions unless
// told otherwise.
Cache CacheOptions
// BuiltinTools are Anthropic's server-side tools, all off unless
// set (mast #340).
BuiltinTools BuiltinTools
}
Options configures a Client. A coremodels.Open caller never builds one by hand; it comes from a resolved profile.