Documentation
¶
Overview ¶
Package anthropic provides an implementation of the fantasy AI SDK for Anthropic's language models.
Package anthropic provides an implementation of the fantasy AI SDK for Anthropic's language models.
Index ¶
- Constants
- func IsComputerUseTool(tool fantasy.Tool) bool
- func New(opts ...Option) (fantasy.Provider, error)
- func NewComputerUseErrorResult(toolCallID string, err error) fantasy.ToolResultPart
- func NewComputerUseScreenshotResult(toolCallID string, screenshotPNG []byte) fantasy.ToolResultPart
- func NewComputerUseScreenshotResultWithMediaType(toolCallID string, base64Data string, mediaType string) fantasy.ToolResultPart
- func NewComputerUseTextResult(toolCallID string, text string) fantasy.ToolResultPart
- func NewComputerUseTool(opts ComputerUseToolOptions, ...) fantasy.ExecutableProviderTool
- func NewProviderCacheControlOptions(opts *ProviderCacheControlOptions) fantasy.ProviderOptions
- func NewProviderOptions(opts *ProviderOptions) fantasy.ProviderOptions
- func WebSearchTool(opts *WebSearchToolOptions) fantasy.ProviderDefinedTool
- type CacheControl
- type ComputerAction
- type ComputerUseInput
- type ComputerUseToolOptions
- type ComputerUseToolVersion
- type Effort
- type Option
- func WithAPIKey(apiKey string) Option
- func WithBaseURL(baseURL string) Option
- func WithBedrock() Option
- func WithBedrockRegion(region string) Option
- func WithHTTPClient(client option.HTTPClient) Option
- func WithHeaders(headers map[string]string) Option
- func WithName(name string) Option
- func WithObjectMode(om fantasy.ObjectMode) Option
- func WithSkipAuth(skip bool) Option
- func WithUserAgent(ua string) Option
- func WithVertex(project, location string) Option
- type ProviderCacheControlOptions
- type ProviderOptions
- type ReasoningOptionMetadata
- type ThinkingDisplay
- type ThinkingProviderOption
- type UserLocation
- type WebSearchResultItem
- type WebSearchResultMetadata
- type WebSearchToolOptions
Constants ¶
const ( // Name is the name of the Anthropic provider. Name = "anthropic" // DefaultURL is the default URL for the Anthropic API. DefaultURL = "https://api.anthropic.com" // VertexAuthScope is the auth scope required for vertex auth if using a Service Account JSON file (e.g. GOOGLE_APPLICATION_CREDENTIALS). VertexAuthScope = "https://www.googleapis.com/auth/cloud-platform" )
const ( TypeProviderOptions = Name + ".options" TypeReasoningOptionMetadata = Name + ".reasoning_metadata" TypeProviderCacheControl = Name + ".cache_control_options" TypeWebSearchResultMetadata = Name + ".web_search_result_metadata" )
Global type identifiers for Anthropic-specific provider data.
Variables ¶
This section is empty.
Functions ¶
func IsComputerUseTool ¶ added in v0.17.0
IsComputerUseTool reports whether tool is an Anthropic computer use tool. It checks for a ProviderDefinedTool whose ID matches the computer use tool identifier exactly.
func NewComputerUseErrorResult ¶ added in v0.17.0
func NewComputerUseErrorResult( toolCallID string, err error, ) fantasy.ToolResultPart
NewComputerUseErrorResult constructs a ToolResultPart indicating that the requested action failed. Claude will see this as an error and may retry or adjust its approach.
Use this when screenshot capture fails, coordinates are out of bounds, the application is unresponsive, or any other execution error occurs.
func NewComputerUseScreenshotResult ¶ added in v0.17.0
func NewComputerUseScreenshotResult( toolCallID string, screenshotPNG []byte, ) fantasy.ToolResultPart
NewComputerUseScreenshotResult constructs a ToolResultPart containing a screenshot image. This is the standard response for almost every computer use action — Claude expects to see what happened after executing the action.
Parameters:
- toolCallID: the ToolCallID from the ToolCallContent that requested this action.
- screenshotPNG: the raw PNG bytes of the screenshot. The caller is responsible for capturing and (optionally) resizing the screenshot before passing it here.
The function base64-encodes the image data and sets the media type to "image/png".
func NewComputerUseScreenshotResultWithMediaType ¶ added in v0.17.0
func NewComputerUseScreenshotResultWithMediaType( toolCallID string, base64Data string, mediaType string, ) fantasy.ToolResultPart
NewComputerUseScreenshotResultWithMediaType is like NewComputerUseScreenshotResult but allows specifying a custom media type (e.g. "image/jpeg") and pre-encoded base64 data.
func NewComputerUseTextResult ¶ added in v0.17.0
func NewComputerUseTextResult( toolCallID string, text string, ) fantasy.ToolResultPart
NewComputerUseTextResult constructs a ToolResultPart containing a plain text response. This is rarely needed for computer use — most actions should return a screenshot — but can be useful for returning metadata alongside the action or for testing.
func NewComputerUseTool ¶ added in v0.17.0
func NewComputerUseTool( opts ComputerUseToolOptions, run func(ctx context.Context, call fantasy.ToolCall) (fantasy.ToolResponse, error), ) fantasy.ExecutableProviderTool
NewComputerUseTool creates a new provider-defined tool configured for Anthropic computer use. The returned tool can be passed directly into a fantasy tool set via WithProviderDefinedTools.
func NewProviderCacheControlOptions ¶
func NewProviderCacheControlOptions(opts *ProviderCacheControlOptions) fantasy.ProviderOptions
NewProviderCacheControlOptions creates new cache control options for the Anthropic provider.
func NewProviderOptions ¶
func NewProviderOptions(opts *ProviderOptions) fantasy.ProviderOptions
NewProviderOptions creates new provider options for the Anthropic provider.
func WebSearchTool ¶ added in v0.13.0
func WebSearchTool(opts *WebSearchToolOptions) fantasy.ProviderDefinedTool
WebSearchTool creates a provider-defined web search tool for Anthropic models. Pass nil for default options.
Types ¶
type CacheControl ¶
type CacheControl struct {
Type string `json:"type"`
}
CacheControl represents cache control settings for the Anthropic provider.
func GetCacheControl ¶
func GetCacheControl(providerOptions fantasy.ProviderOptions) *CacheControl
GetCacheControl extracts cache control settings from provider options.
type ComputerAction ¶ added in v0.17.0
type ComputerAction string
ComputerAction identifies the action Claude wants to perform.
Unless noted otherwise on a specific action, respond by returning a screenshot using NewComputerUseScreenshotResult.
const ( // ActionScreenshot captures the current screen. // // No additional fields are populated. ActionScreenshot ComputerAction = "screenshot" // ActionLeftClick performs a left click. // // - Coordinate: [x, y] target. // - Text: optional modifier key (e.g. "shift", "ctrl"). ActionLeftClick ComputerAction = "left_click" // ActionRightClick performs a right click (v20250124+). // // - Coordinate: [x, y] target. // - Text: optional modifier key (e.g. "shift", "ctrl"). ActionRightClick ComputerAction = "right_click" // ActionDoubleClick performs a double click (v20250124+). // // - Coordinate: [x, y] target. // - Text: optional modifier key (e.g. "shift", "ctrl"). ActionDoubleClick ComputerAction = "double_click" // ActionTripleClick performs a triple click (v20250124+). // // - Coordinate: [x, y] target. // - Text: optional modifier key (e.g. "shift", "ctrl"). ActionTripleClick ComputerAction = "triple_click" // ActionMiddleClick performs a middle click (v20250124+). // // - Coordinate: [x, y] target. // - Text: optional modifier key (e.g. "shift", "ctrl"). ActionMiddleClick ComputerAction = "middle_click" // ActionMouseMove moves the cursor. // // - Coordinate: [x, y] destination. ActionMouseMove ComputerAction = "mouse_move" // ActionLeftClickDrag drags from one point to another // (v20250124+). // // - StartCoordinate: [x, y] drag origin. // - Coordinate: [x, y] drag destination. ActionLeftClickDrag ComputerAction = "left_click_drag" // ActionType types text. // // - Text: the string to type. ActionType ComputerAction = "type" // ActionKey presses a key combination. // // - Text: key combo string (e.g. "ctrl+c", "Return"). ActionKey ComputerAction = "key" // ActionScroll scrolls the screen (v20250124+). // // - Coordinate: [x, y] scroll origin. // - ScrollDirection: "up", "down", "left", or "right". // - ScrollAmount: scroll distance. // - Text: optional modifier key. ActionScroll ComputerAction = "scroll" // ActionLeftMouseDown presses and holds the left mouse button // (v20250124+). // // - Coordinate: [x, y] target. ActionLeftMouseDown ComputerAction = "left_mouse_down" // ActionLeftMouseUp releases the left mouse button // (v20250124+). // // - Coordinate: [x, y] target. ActionLeftMouseUp ComputerAction = "left_mouse_up" // ActionHoldKey holds down a key for a specified duration // (v20250124+). // // - Text: the key to hold. // - Duration: hold time in seconds. ActionHoldKey ComputerAction = "hold_key" // ActionWait pauses between actions (v20250124+). // // No additional fields are populated. ActionWait ComputerAction = "wait" // ActionZoom views a specific screen region at full // resolution (v20251124 only). Requires enable_zoom in the // tool definition. // // - Region: [x1, y1, x2, y2] top-left and bottom-right. // // Response: return a screenshot of the zoomed region at // full resolution. ActionZoom ComputerAction = "zoom" )
type ComputerUseInput ¶ added in v0.17.0
type ComputerUseInput struct {
Action ComputerAction `json:"action"`
// Coordinate is [x, y] for click, move, scroll, and
// drag-end actions.
Coordinate [2]int64 `json:"coordinate,omitempty"`
// StartCoordinate is [x, y] for left_click_drag start point.
StartCoordinate [2]int64 `json:"start_coordinate,omitempty"`
// Text is the string to type (ActionType), key combo
// (ActionKey), modifier key for click/scroll actions, or key
// to hold (ActionHoldKey).
Text string `json:"text,omitempty"`
// ScrollDirection is the scroll direction: "up", "down",
// "left", or "right".
ScrollDirection string `json:"scroll_direction,omitempty"`
// ScrollAmount is the number of scroll clicks.
ScrollAmount int64 `json:"scroll_amount,omitempty"`
// Duration is how long to hold the key in seconds
// (ActionHoldKey).
Duration int64 `json:"duration,omitempty"`
// Region is [x1, y1, x2, y2] defining the zoom area
// (ActionZoom, v20251124 only).
Region [4]int64 `json:"region,omitempty"`
}
ComputerUseInput is the parsed, typed representation of a computer use tool call's Input JSON. Not all fields are populated for every action — check Action first, then read the relevant fields.
func ParseComputerUseInput ¶ added in v0.17.0
func ParseComputerUseInput(input string) (ComputerUseInput, error)
ParseComputerUseInput parses a ToolCallContent's Input string into a typed ComputerUseInput. Returns an error if the JSON is invalid or if coordinate arrays have the wrong number of elements.
type ComputerUseToolOptions ¶ added in v0.17.0
type ComputerUseToolOptions struct {
// DisplayWidthPx is the width of the display in pixels.
DisplayWidthPx int64
// DisplayHeightPx is the height of the display in pixels.
DisplayHeightPx int64
// DisplayNumber is an optional X11 display number.
DisplayNumber *int64
// EnableZoom enables zoom support. Only used with the
// ComputerUse20251124 version.
EnableZoom *bool
// ToolVersion selects which computer use tool version to use.
ToolVersion ComputerUseToolVersion
// CacheControl sets optional cache control for the tool.
CacheControl *CacheControl
}
ComputerUseToolOptions holds the configuration for creating a computer use tool instance.
type ComputerUseToolVersion ¶ added in v0.17.0
type ComputerUseToolVersion string
ComputerUseToolVersion identifies which version of the Anthropic computer use tool to use.
const ( // ComputerUse20251124 selects the November 2025 version of the // computer use tool. ComputerUse20251124 ComputerUseToolVersion = "computer_20251124" // ComputerUse20250124 selects the January 2025 version of the // computer use tool. ComputerUse20250124 ComputerUseToolVersion = "computer_20250124" )
type Effort ¶ added in v0.11.0
type Effort string
Effort represents the output effort level for Anthropic models.
This maps to Messages API `output_config.effort`.
const ( // EffortLow represents low output effort. EffortLow Effort = "low" // EffortMedium represents medium output effort. EffortMedium Effort = "medium" // EffortHigh represents high output effort. EffortHigh Effort = "high" // EffortXHigh represents extra-high output effort. EffortXHigh Effort = "xhigh" // EffortMax represents maximum output effort. EffortMax Effort = "max" )
type Option ¶
type Option = func(*options)
Option defines a function that configures Anthropic provider options.
func WithAPIKey ¶
WithAPIKey sets the API key for the Anthropic provider.
func WithBaseURL ¶
WithBaseURL sets the base URL for the Anthropic provider.
func WithBedrock ¶
func WithBedrock() Option
WithBedrock configures the Anthropic provider to use AWS Bedrock.
func WithBedrockRegion ¶ added in v0.26.0
WithBedrockRegion sets the AWS region for the Bedrock provider.
func WithHTTPClient ¶
func WithHTTPClient(client option.HTTPClient) Option
WithHTTPClient sets the HTTP client for the Anthropic provider.
func WithHeaders ¶
WithHeaders sets the headers for the Anthropic provider.
func WithObjectMode ¶ added in v0.3.0
func WithObjectMode(om fantasy.ObjectMode) Option
WithObjectMode sets the object generation mode.
func WithSkipAuth ¶
WithSkipAuth configures whether to skip authentication for the Anthropic provider.
func WithUserAgent ¶ added in v0.12.0
WithUserAgent sets an explicit User-Agent header, overriding the default and any value set via WithHeaders.
func WithVertex ¶
WithVertex configures the Anthropic provider to use Vertex AI.
type ProviderCacheControlOptions ¶
type ProviderCacheControlOptions struct {
CacheControl CacheControl `json:"cache_control"`
}
ProviderCacheControlOptions represents cache control options for the Anthropic provider.
func (ProviderCacheControlOptions) MarshalJSON ¶ added in v0.3.0
func (o ProviderCacheControlOptions) MarshalJSON() ([]byte, error)
MarshalJSON implements custom JSON marshaling with type info for ProviderCacheControlOptions.
func (*ProviderCacheControlOptions) Options ¶
func (*ProviderCacheControlOptions) Options()
Options implements the ProviderOptions interface.
func (*ProviderCacheControlOptions) UnmarshalJSON ¶ added in v0.3.0
func (o *ProviderCacheControlOptions) UnmarshalJSON(data []byte) error
UnmarshalJSON implements custom JSON unmarshaling with type info for ProviderCacheControlOptions.
type ProviderOptions ¶
type ProviderOptions struct {
SendReasoning *bool `json:"send_reasoning"`
Thinking *ThinkingProviderOption `json:"thinking"`
Effort *Effort `json:"effort"`
ThinkingDisplay *ThinkingDisplay `json:"thinking_display"`
DisableParallelToolUse *bool `json:"disable_parallel_tool_use"`
ExtraBody map[string]any `json:"extra_body,omitempty"`
}
ProviderOptions represents additional options for the Anthropic provider.
func ParseOptions ¶
func ParseOptions(data map[string]any) (*ProviderOptions, error)
ParseOptions parses provider options from a map for the Anthropic provider.
func (ProviderOptions) MarshalJSON ¶ added in v0.3.0
func (o ProviderOptions) MarshalJSON() ([]byte, error)
MarshalJSON implements custom JSON marshaling with type info for ProviderOptions.
func (*ProviderOptions) Options ¶
func (o *ProviderOptions) Options()
Options implements the ProviderOptions interface.
func (*ProviderOptions) UnmarshalJSON ¶ added in v0.3.0
func (o *ProviderOptions) UnmarshalJSON(data []byte) error
UnmarshalJSON implements custom JSON unmarshaling with type info for ProviderOptions.
type ReasoningOptionMetadata ¶
type ReasoningOptionMetadata struct {
Signature string `json:"signature"`
RedactedData string `json:"redacted_data"`
}
ReasoningOptionMetadata represents reasoning metadata for the Anthropic provider.
func GetReasoningMetadata ¶
func GetReasoningMetadata(providerOptions fantasy.ProviderOptions) *ReasoningOptionMetadata
GetReasoningMetadata extracts reasoning metadata from provider options.
func (ReasoningOptionMetadata) MarshalJSON ¶ added in v0.3.0
func (m ReasoningOptionMetadata) MarshalJSON() ([]byte, error)
MarshalJSON implements custom JSON marshaling with type info for ReasoningOptionMetadata.
func (*ReasoningOptionMetadata) Options ¶
func (*ReasoningOptionMetadata) Options()
Options implements the ProviderOptions interface.
func (*ReasoningOptionMetadata) UnmarshalJSON ¶ added in v0.3.0
func (m *ReasoningOptionMetadata) UnmarshalJSON(data []byte) error
UnmarshalJSON implements custom JSON unmarshaling with type info for ReasoningOptionMetadata.
type ThinkingDisplay ¶ added in v0.30.0
type ThinkingDisplay string
ThinkingDisplay controls whether Anthropic returns visible thinking content.
const ( // ThinkingDisplaySummarized requests visible summarized thinking content. ThinkingDisplaySummarized ThinkingDisplay = "summarized" // ThinkingDisplayOmitted requests hidden thinking content. ThinkingDisplayOmitted ThinkingDisplay = "omitted" )
type ThinkingProviderOption ¶
type ThinkingProviderOption struct {
BudgetTokens int64 `json:"budget_tokens"`
}
ThinkingProviderOption represents thinking options for the Anthropic provider.
type UserLocation ¶ added in v0.13.0
type UserLocation struct {
City string `json:"city,omitempty"`
Region string `json:"region,omitempty"`
Country string `json:"country,omitempty"`
Timezone string `json:"timezone,omitempty"`
}
UserLocation provides geographic context for web search results.
type WebSearchResultItem ¶ added in v0.13.0
type WebSearchResultItem struct {
URL string `json:"url"`
Title string `json:"title"`
EncryptedContent string `json:"encrypted_content"`
// PageAge may be empty when the API does not return age info.
PageAge string `json:"page_age,omitempty"`
}
WebSearchResultItem represents a single web search result for round-tripping.
type WebSearchResultMetadata ¶ added in v0.13.0
type WebSearchResultMetadata struct {
Results []WebSearchResultItem `json:"results,omitempty"`
// ErrorCode is the Anthropic web_search_tool_result_error.error_code.
// At most one of Results or ErrorCode should be non-empty.
ErrorCode string `json:"error_code,omitempty"`
}
WebSearchResultMetadata stores web search results from Anthropic's server-executed web_search tool. The structured data, especially encrypted content and error codes, must be preserved for multi-turn conversations.
func (WebSearchResultMetadata) MarshalJSON ¶ added in v0.13.0
func (m WebSearchResultMetadata) MarshalJSON() ([]byte, error)
MarshalJSON implements custom JSON marshaling with type info for WebSearchResultMetadata.
func (*WebSearchResultMetadata) Options ¶ added in v0.13.0
func (*WebSearchResultMetadata) Options()
Options implements the ProviderOptions interface.
func (*WebSearchResultMetadata) UnmarshalJSON ¶ added in v0.13.0
func (m *WebSearchResultMetadata) UnmarshalJSON(data []byte) error
UnmarshalJSON implements custom JSON unmarshaling with type info for WebSearchResultMetadata.
type WebSearchToolOptions ¶ added in v0.13.0
type WebSearchToolOptions struct {
// MaxUses limits the number of web searches the model can
// perform within a single API request. Zero means no limit.
MaxUses int64
// AllowedDomains restricts results to these domains. Cannot
// be used together with BlockedDomains.
AllowedDomains []string
// BlockedDomains excludes these domains from results. Cannot
// be used together with AllowedDomains.
BlockedDomains []string
// UserLocation provides geographic context for more relevant
// search results.
UserLocation *UserLocation
}
WebSearchToolOptions configures the Anthropic web search tool.