Documentation
¶
Overview ¶
Package anthropic implements models.Provider for Anthropic / Claude, on the first-party API and on Vertex AI.
The adapter itself lives in core-models (dialect/anthropic, docs/model-support-design.md): request conversion, streaming, rolling and 1-hour prompt caching, thinking, the usage record. This package is core-agent's facade over it — it maps config.Config onto core-models' built-in anthropic and anthropic-vertex profiles, keeps core-agent's defaults (DefaultModel, the small-model tier, caching on, built-ins off) and exported API, and adapts each model to ADK v2 through models.Adapt, which also writes the cache-write sidecar pkg/usage reads.
Index ¶
- Constants
- type BuiltinTools
- type CacheOptions
- type Option
- type Provider
- func (p *Provider) BuiltinToolNames() []string
- func (p *Provider) DefaultSmallModel() string
- func (p *Provider) Model(ctx context.Context, modelID string) (adkmodel.LLM, error)
- func (p *Provider) Name() string
- func (p *Provider) PromptCache() CacheOptions
- func (p *Provider) SetPromptCache(o CacheOptions)
Constants ¶
const ( EnvVertexProject = "ANTHROPIC_VERTEX_PROJECT_ID" EnvVertexRegion = "CLOUD_ML_REGION" )
Env vars consulted by the Vertex constructor when project / region are not supplied explicitly via config. Names match Anthropic SDK conventions; the GCP-standard fallbacks let the same env that drives Vertex Gemini also drive Vertex Anthropic.
const DefaultMaxTokens = cmanthropic.DefaultMaxTokens
DefaultMaxTokens caps a single response when the caller hasn't set one. It is core-models' value, re-exported for callers that sized against this package's constant.
const DefaultModel = "claude-opus-5-5"
DefaultModel is used when LLMRequest.Model is empty. We follow the claude-api skill's guidance and default to the most capable Opus — the LATEST one, per the policy documented on taskclass.ModelForTier. Not the Mythos-class tier above it (claude-fable-5 / claude-mythos-5), which costs 2x and isn't a general-purpose default.
Pinned to taskclass.ModelForTier("anthropic", "frontier") by TestDefaultModel_MatchesFrontierTier: an operator who sets --task=implement and one who sets nothing should land on the same model, or the task-class flag reads as a silent downgrade.
const DefaultSmallModelID = "claude-haiku-5-5"
DefaultSmallModelID is the Anthropic cheap-tier model used by default for agentic subtasks when the operator hasn't pinned one with --agentic-small-model. Same value for the first-party and Vertex backends; the Vertex publication name resolves at call time.
const DefaultVertexRegion = "us-east5"
Default Vertex region for Claude. Most current Anthropic Vertex deployments live in us-east5; override per call site as needed.
const EnvAPIKey = "ANTHROPIC_API_KEY" // #nosec G101 -- env var name, not a credential
EnvAPIKey is the environment variable consulted when no key is supplied via config.
const EnvBaseURL = "ANTHROPIC_BASE_URL"
EnvBaseURL overrides the first-party API root, for a proxy in front of api.anthropic.com. It does not apply to Vertex AI, whose URL is built from the project and region.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
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 core-agent. 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:
provider, _ := anthropic.New(key, anthropic.WithWebSearch(true))
To replace the whole set:
provider, _ := anthropic.New(key, anthropic.WithBuiltinTools(anthropic.BuiltinTools{
WebSearch: true,
}))
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 DefaultBuiltinTools ¶
func DefaultBuiltinTools() BuiltinTools
DefaultBuiltinTools returns the on-by-default baseline applied to every Provider unless overridden via WithBuiltinTools or one of the per-tool helpers. Currently empty — see BuiltinTools doc for why.
func (BuiltinTools) Names ¶
func (b BuiltinTools) Names() []string
Names reports the enabled built-ins under the provider-neutral names the config block uses (see config.BuiltinToolsConfig), so the startup summary reads the same whichever provider is resolved and an operator can match the line against the keys they typed.
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 (#714).
History bool
// TTL is the breakpoint lifetime: config.PromptCacheTTL5m (the
// zero value's meaning) or config.PromptCacheTTL1h. The 1-hour
// TTL bills writes at 2x base input against the 5-minute TTL's
// 1.25x, so it only pays when turns are further than five minutes
// apart — see config.PromptCacheConfig.TTL. Both are priced, and
// the response reports which one each write used, so the ledger is
// right either way (#770).
//
// Any other value is treated as 5m.
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 is what every constructor starts from: cache the stable prefix and the conversation tail. On by default because the break-even is two requests against a 5-minute TTL and core-agent's agentic loop issues its second request seconds after the first — the shape that loses (a single request whose prefix is never seen again) is the rare one, and it is the one an operator can turn off.
func (CacheOptions) Enabled ¶
func (o CacheOptions) Enabled() bool
Enabled reports whether any breakpoint would be placed.
type Option ¶
type Option func(*Provider)
Option configures a Provider at construction.
func WithBuiltinTools ¶
func WithBuiltinTools(b BuiltinTools) Option
WithBuiltinTools replaces the Provider's whole BuiltinTools set.
func WithCacheSystem
deprecated
WithCacheSystem caches the last system block and nothing else.
Deprecated: use WithPromptCache. This option predates the history breakpoints and keeps its original all-or-nothing meaning — it REPLACES the policy rather than editing one field, so WithCacheSystem(false) still means "no caching at all", the way it did when system blocks were the only thing that could be marked. A caller who wrote it to avoid the write premium keeps that outcome instead of silently acquiring rolling history breakpoints.
func WithPromptCache ¶
func WithPromptCache(o CacheOptions) Option
WithPromptCache sets the whole prompt-caching policy, replacing DefaultCacheOptions. Pass a zero CacheOptions to turn caching off — worth doing for a request shape whose prefix varies every call, where the write premium buys reads that never come.
func WithWebSearch ¶
WithWebSearch toggles Anthropic's server-side web_search tool. Off by default — opt in when you've decided the per-search cost and external-call posture are acceptable.
type Provider ¶
type Provider struct {
// contains filtered or unexported fields
}
Provider is the Anthropic implementation of models.Provider. The same struct serves both the first-party API and Vertex AI backends — only the core-models profile it opens differs. name carries which one this is so telemetry and Resolve() see the right identity.
func New ¶
New constructs a Provider with the given API key (first-party api.anthropic.com). Pass options to tune behavior. Empty key falls back to the ANTHROPIC_API_KEY env var.
func NewVertex ¶
NewVertex constructs a Provider that talks to Claude via Google Vertex AI. project and region are required. Authentication uses Application Default Credentials (run `gcloud auth application-default login`, or set GOOGLE_APPLICATION_CREDENTIALS, or rely on workload identity in production); missing credentials fail here, at startup.
func (*Provider) BuiltinToolNames ¶
BuiltinToolNames satisfies models.BuiltinToolsReporter — the effective server-side built-in set this Provider will send, after config and options. Reported from what the Provider actually carries rather than re-derived from config, so the startup line cannot drift from the requests.
func (*Provider) DefaultSmallModel ¶
DefaultSmallModel satisfies models.SmallModelDefaulter so core-agent can route subtask digesting to a cheap-tier Claude model without requiring the operator to set --agentic-small-model.
func (*Provider) Model ¶
Model returns a model.LLM for the given model ID. modelID may be empty, in which case DefaultModel is used.
Note: Vertex AI sometimes serves Claude under date-suffixed model IDs (e.g. "claude-opus-4-5@20251101"). When using "anthropic-vertex", pass the exact ID Vertex expects via cfg.Model.Name; it goes into the Vertex URL path verbatim.
func (*Provider) PromptCache ¶
func (p *Provider) PromptCache() CacheOptions
PromptCache reports the currently installed policy. Lets a host log what it wired without keeping its own copy.
func (*Provider) SetPromptCache ¶
func (p *Provider) SetPromptCache(o CacheOptions)
SetPromptCache installs the caching policy after construction. Exists for the daemon's wiring order: the provider comes out of the registry (models.Resolve, which sees only config) before the CLI kill switch can be applied, and Model() reads the policy when it builds an LLM. Call it before the first Model() call — like the Gemini provider's cache hooks, it is startup wiring, not a live control.