anthropic

package
v0.38.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 16, 2026 License: Apache-2.0 Imports: 26 Imported by: 14

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

View Source
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"
)
View Source
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

func IsComputerUseTool(tool fantasy.Tool) bool

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 New

func New(opts ...Option) (fantasy.Provider, error)

New creates a new Anthropic provider with the given options.

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

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

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

func WithAPIKey(apiKey string) Option

WithAPIKey sets the API key for the Anthropic provider.

func WithBaseURL

func WithBaseURL(baseURL string) Option

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

func WithBedrockRegion(region string) Option

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

func WithHeaders(headers map[string]string) Option

WithHeaders sets the headers for the Anthropic provider.

func WithName

func WithName(name string) Option

WithName sets the name 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

func WithSkipAuth(skip bool) Option

WithSkipAuth configures whether to skip authentication for the Anthropic provider.

func WithUserAgent added in v0.12.0

func WithUserAgent(ua string) Option

WithUserAgent sets an explicit User-Agent header, overriding the default and any value set via WithHeaders.

func WithVertex

func WithVertex(project, location string) Option

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL