cursor

package
v0.0.3 Latest Latest
Warning

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

 Go to latest Published: Jun 15, 2026 License: MIT Imports: 19 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var Cursor = cursorNamespace{}

Cursor provides account-level SDK operations.

View Source 
var Models = modelsNamespace{}

Models exposes model listing.

View Source 
var Repositories = repositoriesNamespace{}

Repositories exposes connected repository listing.

Functions

func ArchiveAgent 

func ArchiveAgent(ctx context.Context, agentID string, opts AgentOperationOptions, clientOpts ...ClientOption) error

ArchiveAgent archives a cloud agent by ID.

func AssistantText 

func AssistantText(msg SDKMessage) string

AssistantText extracts text from an assistant SDKMessage.

func CancelRun 

func CancelRun(ctx context.Context, runID, agentID string, clientOpts ...ClientOption) error

CancelRun cancels a run by ID.

func CloseDefaultClient 

func CloseDefaultClient() error

CloseDefaultClient closes the process-wide default client and bridge.

func Configure 

func Configure(opts ConfigureOptions)

Configure sets process-wide SDK defaults matching Cursor.configure() in TypeScript.

func DeleteAgent 

func DeleteAgent(ctx context.Context, agentID string, opts AgentOperationOptions, clientOpts ...ClientOption) error

DeleteAgent permanently deletes a cloud agent.

func EnsureBridgeInstalled 

func EnsureBridgeInstalled(ctx context.Context) error

EnsureBridgeInstalled reports whether cursor-sdk-bridge is installed (npm global/link or env).

func IsAgentBusy 

func IsAgentBusy(err error) bool

IsAgentBusy reports agent busy errors.

func IsAuthentication 

func IsAuthentication(err error) bool

IsAuthentication reports authentication/permission errors.

func IsConfiguration 

func IsConfiguration(err error) bool

IsConfiguration reports configuration errors.

func IsIntegrationNotConnected 

func IsIntegrationNotConnected(err error) bool

IsIntegrationNotConnected reports integration connection errors.

func IsNotFound 

func IsNotFound(err error) bool

IsNotFound reports not-found errors.

func IsRateLimit 

func IsRateLimit(err error) bool

IsRateLimit reports rate limit errors.

func IsUnsupportedRunOperation 

func IsUnsupportedRunOperation(err error) bool

IsUnsupportedRunOperation reports unsupported run operation errors.

func McpServerFromMap 

func McpServerFromMap(m map[string]any) map[string]any

McpServerFromMap normalizes a flat MCP server config map to wire format. Accepts both nested ({http: ...}, {stdio: ...}) and flat ({type, url, command}) shapes.

func Setup 

func Setup(ctx context.Context, opts SetupOptions) error

Setup installs runtime prerequisites (cursor-sdk-bridge via npm). If ResolvePath succeeds (bridge on PATH at the required version), Setup is a no-op.

func UnarchiveAgent 

func UnarchiveAgent(ctx context.Context, agentID string, opts AgentOperationOptions, clientOpts ...ClientOption) error

UnarchiveAgent restores an archived cloud agent.

Types

type APITimeoutError 

type APITimeoutError struct{ *AgentError }

type Agent 

type Agent struct {
	AgentID string
	Model   *ModelSelection
	// contains filtered or unexported fields
}

Agent is a durable handle for multi-turn agent conversations.

func CreateAgent 

func CreateAgent(ctx context.Context, opts AgentOptions, clientOpts ...ClientOption) (*Agent, error)

CreateAgent creates a new agent with the given options.

func ResumeAgent 

func ResumeAgent(ctx context.Context, agentID string, opts AgentOptions, clientOpts ...ClientOption) (*Agent, error)

ResumeAgent resumes an existing agent by ID.

func (*Agent) Archive 

func (a *Agent) Archive(ctx context.Context, opts AgentOperationOptions) error

Archive archives the agent.

func (*Agent) Close 

func (a *Agent) Close(ctx context.Context) error

Close closes the agent on the bridge.

func (*Agent) Delete 

func (a *Agent) Delete(ctx context.Context, opts AgentOperationOptions) error

Delete permanently deletes the agent.

func (*Agent) DownloadArtifact 

func (a *Agent) DownloadArtifact(ctx context.Context, path string) ([]byte, error)

DownloadArtifact downloads an artifact by path.

func (*Agent) ListArtifacts 

func (a *Agent) ListArtifacts(ctx context.Context) ([]SdkArtifact, error)

ListArtifacts lists files produced by the agent.

func (*Agent) ListMessages 

func (a *Agent) ListMessages(ctx context.Context) ([]AgentMessage, error)

ListMessages returns persisted agent messages.

func (*Agent) Reload 

func (a *Agent) Reload(ctx context.Context) error

Reload reloads agent configuration from disk/settings.

func (*Agent) Send 

func (a *Agent) Send(ctx context.Context, message any, opts SendOptions) (*Run, error)

Send starts a new run for this agent.

func (*Agent) Unarchive 

func (a *Agent) Unarchive(ctx context.Context, opts AgentOperationOptions) error

Unarchive restores an archived agent.

type AgentBusyError 

type AgentBusyError struct{ *AgentError }

type AgentDefinition 

type AgentDefinition struct {
	Description string
	Prompt      string
	Model       any   // string, ModelSelection, or "inherit"
	McpServers  []any // string names or inline configs
}

AgentDefinition describes a sub-agent available to the main agent.

func (AgentDefinition) ToWire 

func (d AgentDefinition) ToWire() map[string]any

type AgentError 

type AgentError struct {
	Message        string
	Code           string
	Status         int
	Details        []map[string]any
	IsRetryable    bool
	ProtoErrorCode string
	RequestID      string
	Headers        map[string]string
	RetryAfter     string
}

AgentError is the base error type for Cursor SDK failures.

func AsAgentError 

func AsAgentError(err error) (*AgentError, bool)

AsAgentError reports whether err is an *AgentError (including typed wrappers).

func (*AgentError) Error 

func (e *AgentError) Error() string

type AgentMessage 

type AgentMessage struct {
	Type    string `json:"type"`
	UUID    string `json:"uuid"`
	AgentID string `json:"agentId"`
	Message any    `json:"message"`
}

AgentMessage is a persisted agent message.

type AgentMode 

type AgentMode string

AgentMode selects agent or plan mode. 

const (
	AgentModeAgent AgentMode = "agent"
	AgentModePlan  AgentMode = "plan"
)

type AgentNotFoundError 

type AgentNotFoundError struct{ *AgentError }

type AgentOperationOptions 

type AgentOperationOptions struct {
	CWD    string
	APIKey string
}

AgentOperationOptions configures archive/unarchive/delete operations.

func (AgentOperationOptions) ToWire 

func (o AgentOperationOptions) ToWire() map[string]any

type AgentOptions 

type AgentOptions struct {
	Model          any // string or ModelSelection
	APIKey         string
	Name           string
	Local          *LocalAgentOptions
	Cloud          *CloudAgentOptions
	McpServers     map[string]McpServer
	Agents         map[string]AgentDefinition
	AgentID        string
	IdempotencyKey string
	Mode           AgentMode
}

AgentOptions configures agent creation or resume.

func (AgentOptions) ToWire 

func (o AgentOptions) ToWire() map[string]any

type AgentsResource 

type AgentsResource struct {
	// contains filtered or unexported fields
}

AgentsResource groups agent operations on a client.

func (*AgentsResource) Archive 

func (r *AgentsResource) Archive(ctx context.Context, agentID string, opts AgentOperationOptions) error

func (*AgentsResource) CancelRun 

func (r *AgentsResource) CancelRun(ctx context.Context, runID, agentID string) error

func (*AgentsResource) Create 

func (r *AgentsResource) Create(ctx context.Context, opts AgentOptions) (*Agent, error)

func (*AgentsResource) Delete 

func (r *AgentsResource) Delete(ctx context.Context, agentID string, opts AgentOperationOptions) error

func (*AgentsResource) Get 

func (r *AgentsResource) Get(ctx context.Context, agentID string, opts GetAgentOptions) (SDKAgentInfo, error)

func (*AgentsResource) GetRun 

func (r *AgentsResource) GetRun(ctx context.Context, runID string, opts GetRunOptions) (*Run, error)

func (*AgentsResource) List 

func (r *AgentsResource) List(ctx context.Context, opts ListAgentsOptions) (ListResult[SDKAgentInfo], error)

func (*AgentsResource) ListRuns 

func (r *AgentsResource) ListRuns(ctx context.Context, agentID string, opts ListRunsOptions) (ListResult[*Run], error)

func (*AgentsResource) Resume 

func (r *AgentsResource) Resume(ctx context.Context, agentID string, opts AgentOptions) (*Agent, error)

func (*AgentsResource) Unarchive 

func (r *AgentsResource) Unarchive(ctx context.Context, agentID string, opts AgentOperationOptions) error

type AuthenticationError 

type AuthenticationError struct{ *AgentError }

type BadRequestError 

type BadRequestError struct{ *AgentError }

type Client 

type Client struct {
	Agents       *AgentsResource
	Models       *ModelsResource
	Repositories *RepositoriesResource
	// contains filtered or unexported fields
}

Client talks to the Cursor SDK bridge.

func Connect 

func Connect(baseURL, authToken string, opts ...ClientOption) (*Client, error)

Connect returns a client attached to an existing bridge.

func DefaultClient 

func DefaultClient(ctx context.Context) (*Client, error)

DefaultClient returns the process-wide default client, launching a bridge if needed.

func LaunchBridge 

func LaunchBridge(ctx context.Context, opts ...ClientOption) (*Client, error)

LaunchBridge starts a local bridge and returns a client.

func (*Client) Close 

func (c *Client) Close() error

Close releases bridge and transport resources.

func (*Client) GetVersion 

func (c *Client) GetVersion(ctx context.Context) (map[string]any, error)

GetVersion returns bridge version metadata.

func (*Client) Ping 

func (c *Client) Ping(ctx context.Context) (string, error)

Ping checks bridge connectivity.

func (*Client) Shutdown 

func (c *Client) Shutdown(ctx context.Context, graceSeconds int) error

Shutdown requests graceful bridge shutdown.

func (*Client) WithOptions 

func (c *Client) WithOptions(opts ...ClientOption) (*Client, error)

WithOptions returns a client sharing the transport with overridden timeouts.

type ClientOption 

type ClientOption func(*clientConfig)

ClientOption configures a Client.

func WithAllowAPIKeyEnvFallback 

func WithAllowAPIKeyEnvFallback(allow bool) ClientOption

WithAllowAPIKeyEnvFallback allows reading CURSOR_API_KEY from the environment.

func WithMaxRetries 

func WithMaxRetries(n int) ClientOption

WithMaxRetries sets retry count for idempotent unary RPCs.

func WithStreamTimeout 

func WithStreamTimeout(d time.Duration) ClientOption

WithStreamTimeout sets streaming RPC timeout.

func WithUnaryTimeout 

func WithUnaryTimeout(d time.Duration) ClientOption

WithUnaryTimeout sets unary RPC timeout.

func WithWorkspace 

func WithWorkspace(path string) ClientOption

WithWorkspace sets the bridge workspace directory.

type CloudAgentOptions 

type CloudAgentOptions struct {
	Env                 *CloudEnvironment
	Repos               []CloudRepository
	WorkOnCurrentBranch *bool
	AutoCreatePR        *bool
	SkipReviewerRequest *bool
	EnvVars             map[string]string
}

CloudAgentOptions configures a cloud agent runtime.

func (CloudAgentOptions) ToWire 

func (o CloudAgentOptions) ToWire() map[string]any

type CloudEnvironment 

type CloudEnvironment struct {
	Type string `json:"type"`
	Name string `json:"name,omitempty"`
}

CloudEnvironment selects cloud vs self-hosted pool.

func (CloudEnvironment) ToWire 

func (e CloudEnvironment) ToWire() map[string]any

type CloudRepository 

type CloudRepository struct {
	URL         string `json:"url"`
	StartingRef string `json:"startingRef,omitempty"`
	PRURL       string `json:"prUrl,omitempty"`
}

CloudRepository identifies a repo for cloud agents.

func (CloudRepository) ToWire 

func (r CloudRepository) ToWire() map[string]any

type ConfigurationError 

type ConfigurationError struct{ *AgentError }

type ConfigureLocalOptions 

type ConfigureLocalOptions struct {
	Store *LocalAgentStoreConfig
}

ConfigureLocalOptions configures local agent defaults.

type ConfigureOptions 

type ConfigureOptions struct {
	Local *ConfigureLocalOptions
}

ConfigureOptions sets process-wide SDK defaults for later Agent calls. Per-call options override these values.

type ConversationStep 

type ConversationStep struct {
	Type    string
	Text    string
	Message map[string]any
	Raw     map[string]any
}

ConversationStep is one step in a run conversation.

func ParseConversationStep 

func ParseConversationStep(m map[string]any) ConversationStep

ParseConversationStep parses a conversation step envelope.

type ConversationTurn 

type ConversationTurn struct {
	Type string
	Turn any
}

ConversationTurn is a turn in run conversation history.

func ConversationFromJSON 

func ConversationFromJSON(raw string) ([]ConversationTurn, error)

ConversationFromJSON parses conversation JSON returned by GetRunConversation.

func ParseConversationTurn 

func ParseConversationTurn(m map[string]any) ConversationTurn

ParseConversationTurn parses a conversation turn from JSON bytes.

type CursorAgentError 

type CursorAgentError = AgentError

CursorAgentError is a backward-compatible alias matching TypeScript.

type CursorClient 

type CursorClient = Client

CursorClient is an alias for Client matching the Python SDK name.

type CursorRequestOptions 

type CursorRequestOptions struct {
	APIKey string
}

CursorRequestOptions carries optional apiKey for Cursor namespace reads.

type CustomTool 

type CustomTool struct {
	Description string
	InputSchema map[string]any
	Execute     func(args map[string]any, ctx CustomToolContext) (any, error)
}

CustomTool defines a host-executed tool for local agents.

type CustomToolContext 

type CustomToolContext struct {
	ToolCallID string
}

CustomToolContext carries per-invocation metadata.

type DeltaCallback 

type DeltaCallback func(InteractionUpdate)

DeltaCallback receives raw interaction updates during streaming.

type FlatMcpServer 

type FlatMcpServer map[string]any

FlatMcpServer implements McpServer for map-based configs.

func (FlatMcpServer) ToWire 

func (f FlatMcpServer) ToWire() map[string]any

type GetAgentOptions 

type GetAgentOptions struct {
	CWD    string
	APIKey string
}

GetAgentOptions configures Agent.get lookups.

func (GetAgentOptions) ToWire 

func (o GetAgentOptions) ToWire() map[string]any

type GetRunOptions 

type GetRunOptions struct {
	Runtime string
	CWD     string
	AgentID string
	APIKey  string
}

GetRunOptions configures Agent.getRun lookups.

func (GetRunOptions) ToWire 

func (o GetRunOptions) ToWire() map[string]any

type HttpMcpServerConfig 

type HttpMcpServerConfig struct {
	URL     string
	Type    string // "http" or "sse"
	Headers map[string]string
	Auth    *McpAuth
}

HttpMcpServerConfig configures an HTTP or SSE MCP server.

func (HttpMcpServerConfig) ToWire 

func (c HttpMcpServerConfig) ToWire() map[string]any

type IntegrationNotConnectedError 

type IntegrationNotConnectedError struct {
	*AgentError
	Provider string
	HelpURL  string
}

type InteractionUpdate 

type InteractionUpdate struct {
	Type               string
	Text               string
	ThinkingDurationMS int
	CallID             string
	ToolCall           map[string]any
	ModelCallID        string
	Tokens             int
	StepID             int
	StepDurationMS     int
	Usage              map[string]any
	UserMessage        map[string]any
	Summary            string
	Event              map[string]any
	Raw                map[string]any
}

InteractionUpdate is a delta event during streaming.

func ParseInteractionUpdate 

func ParseInteractionUpdate(m map[string]any) InteractionUpdate

ParseInteractionUpdate parses a wire interaction update.

type InternalServerError 

type InternalServerError struct{ *AgentError }

type ListAgentsOptions 

type ListAgentsOptions struct {
	Runtime         string
	CWD             string
	IncludeArchived *bool
	PRURL           string
	Limit           int
	APIKey          string
	Cursor          string
}

ListAgentsOptions configures agent listing.

func (ListAgentsOptions) ToWire 

func (o ListAgentsOptions) ToWire() map[string]any

type ListResult 

type ListResult[T any] struct {
	Items      []T
	NextCursor string
	// contains filtered or unexported fields
}

ListResult is a paginated list response.

func ListAgents 

func ListAgents(ctx context.Context, opts ListAgentsOptions, clientOpts ...ClientOption) (ListResult[SDKAgentInfo], error)

ListAgents lists agents with optional filters.

func ListRuns 

func ListRuns(ctx context.Context, agentID string, opts ListRunsOptions, clientOpts ...ClientOption) (ListResult[*Run], error)

ListRuns lists runs for an agent.

func (ListResult[T]) AllPages 

func (l ListResult[T]) AllPages() ([]T, error)

AllPages iterates all items across pages.

func (ListResult[T]) HasNextPage 

func (l ListResult[T]) HasNextPage() bool

func (ListResult[T]) NextPage 

func (l ListResult[T]) NextPage() (ListResult[T], error)

func (ListResult[T]) NextPageInfo 

func (l ListResult[T]) NextPageInfo() map[string]string

NextPageInfo returns pagination metadata for the next page.

type ListRunsOptions 

type ListRunsOptions struct {
	Runtime string
	CWD     string
	Limit   int
	APIKey  string
	Cursor  string
}

ListRunsOptions configures run listing.

func (ListRunsOptions) ToWire 

func (o ListRunsOptions) ToWire() map[string]any

type LocalAgentOptions 

type LocalAgentOptions struct {
	CWD            []string
	SettingSources []SettingSource
	SandboxOptions *SandboxOptions
	Store          *LocalAgentStoreConfig
	AutoReview     *bool
	CustomTools    map[string]CustomTool
}

LocalAgentOptions configures a local agent runtime.

func LocalOptions 

func LocalOptions(cwd ...string) *LocalAgentOptions

LocalOptions builds LocalAgentOptions from one or more workspace paths.

func (LocalAgentOptions) ToWire 

func (o LocalAgentOptions) ToWire() map[string]any

type LocalAgentStoreConfig 

type LocalAgentStoreConfig struct {
	Type    string `json:"type"`
	RootDir string `json:"rootDir,omitempty"`
}

LocalAgentStoreConfig configures a custom local store.

func (LocalAgentStoreConfig) ToWire 

func (c LocalAgentStoreConfig) ToWire() map[string]any

type LocalSendOptions 

type LocalSendOptions struct {
	Force       *bool
	CustomTools map[string]CustomTool
}

LocalSendOptions configures local-only send overrides.

func (LocalSendOptions) ToWire 

func (o LocalSendOptions) ToWire() map[string]any

type McpAuth 

type McpAuth struct {
	ClientID     string   `json:"clientId"`
	ClientSecret string   `json:"clientSecret,omitempty"`
	Scopes       []string `json:"scopes,omitempty"`
}

McpAuth holds OAuth2 client credentials for HTTP MCP servers.

func (McpAuth) ToWire 

func (a McpAuth) ToWire() map[string]any

type McpServer 

type McpServer interface {
	ToWire() map[string]any
}

McpServer is implemented by MCP server config types.

type ModelParameterDefinition 

type ModelParameterDefinition struct {
	ID          string
	DisplayName string
	Values      []ModelParameterDefinitionValue
}

ModelParameterDefinition describes a configurable model parameter.

type ModelParameterDefinitionValue 

type ModelParameterDefinitionValue struct {
	Value       string
	DisplayName string
}

ModelParameterDefinitionValue is one allowed value for a model parameter.

type ModelParameterValue 

type ModelParameterValue struct {
	ID    string `json:"id"`
	Value string `json:"value"`
}

ModelParameterValue is a per-model option such as reasoning effort.

func (ModelParameterValue) ToWire 

func (p ModelParameterValue) ToWire() map[string]any

type ModelSelection 

type ModelSelection struct {
	ID     string                `json:"id"`
	Params []ModelParameterValue `json:"params,omitempty"`
}

ModelSelection identifies a model and optional parameters.

func ModelFromString 

func ModelFromString(id string) ModelSelection

func (ModelSelection) ToWire 

func (m ModelSelection) ToWire() map[string]any

type ModelVariant 

type ModelVariant struct {
	Params      []ModelParameterValue
	DisplayName string
	Description string
	IsDefault   bool
}

ModelVariant is a preset parameter combination for a model.

type ModelsResource 

type ModelsResource struct {
	// contains filtered or unexported fields
}

ModelsResource lists models through a client.

func (*ModelsResource) List 

func (r *ModelsResource) List(ctx context.Context, opts CursorRequestOptions) ([]SDKModel, error)

type NetworkError 

type NetworkError struct{ *AgentError }

type NotFoundError 

type NotFoundError struct{ *AgentError }

type PermissionDeniedError 

type PermissionDeniedError struct{ *AgentError }

type RateLimitError 

type RateLimitError struct{ *AgentError }

type RepositoriesResource 

type RepositoriesResource struct {
	// contains filtered or unexported fields
}

RepositoriesResource lists repositories through a client.

func (*RepositoriesResource) List 

func (r *RepositoriesResource) List(ctx context.Context, opts CursorRequestOptions) ([]SDKRepository, error)

type Run 

type Run struct {
	ID         string
	RequestID  string
	AgentID    string
	Status     RunStatus
	Result     string
	Model      *ModelSelection
	DurationMS int
	Git        *RunGitInfo
	CreatedAt  string
	// contains filtered or unexported fields
}

Run is a handle for one prompt submission and its stream.

func GetRun 

func GetRun(ctx context.Context, runID string, opts GetRunOptions, clientOpts ...ClientOption) (*Run, error)

GetRun fetches a run by ID.

func (*Run) Cancel 

func (r *Run) Cancel(ctx context.Context) error

Cancel requests cancellation of an in-flight run.

func (*Run) Conversation 

func (r *Run) Conversation(ctx context.Context) ([]ConversationTurn, error)

Conversation returns parsed conversation turns.

func (*Run) ConversationJSON 

func (r *Run) ConversationJSON(ctx context.Context) (string, error)

ConversationJSON returns the raw conversation JSON from the bridge.

func (*Run) Events 

func (r *Run) Events(ctx context.Context) iter.Seq2[RunStreamEvent, error]

Events returns low-level stream envelopes.

func (*Run) IterText 

func (r *Run) IterText(ctx context.Context) iter.Seq2[string, error]

IterText yields assistant text chunks as they arrive.

func (*Run) Messages 

func (r *Run) Messages(ctx context.Context) iter.Seq2[SDKMessage, error]

Messages returns typed SDK messages from the stream.

func (*Run) Observe 

func (r *Run) Observe(ctx context.Context, afterOffset string) iter.Seq2[RunStreamEvent, error]

Observe replays or continues observing a run from an offset.

func (*Run) OnDidChangeStatus 

func (r *Run) OnDidChangeStatus(fn func(RunStatus)) func()

OnDidChangeStatus registers a listener for status transitions (TypeScript alias).

func (*Run) OnStatusChange 

func (r *Run) OnStatusChange(fn func(RunStatus)) func()

OnStatusChange registers a listener for status transitions.

func (*Run) Stream 

func (r *Run) Stream(ctx context.Context) iter.Seq2[SDKMessage, error]

Stream is an alias for Messages.

func (*Run) Supports 

func (r *Run) Supports(op RunOperation) bool

Supports reports whether an operation is available on this run handle.

func (*Run) SupportsString 

func (r *Run) SupportsString(op string) bool

SupportsString reports whether a named operation is available.

func (*Run) Text 

func (r *Run) Text(ctx context.Context) (string, error)

Text blocks until the run completes and returns the final assistant text.

func (*Run) UnsupportedReason 

func (r *Run) UnsupportedReason(op RunOperation) string

UnsupportedReason explains why an operation is unavailable.

func (*Run) UnsupportedReasonString 

func (r *Run) UnsupportedReasonString(op string) string

UnsupportedReasonString explains why a named operation is unavailable.

func (*Run) Wait 

func (r *Run) Wait(ctx context.Context) (RunResult, error)

Wait blocks until the run reaches a terminal state.

type RunGitBranchInfo 

type RunGitBranchInfo struct {
	RepoURL string `json:"repoUrl"`
	Branch  string `json:"branch"`
	PRURL   string `json:"prUrl"`
}

RunGitBranchInfo describes a branch touched by a run.

type RunGitInfo 

type RunGitInfo struct {
	Branches []RunGitBranchInfo `json:"branches"`
}

RunGitInfo aggregates git metadata from a run.

type RunOperation 

type RunOperation string

RunOperation names a run capability. 

const (
	RunOpStream       RunOperation = "stream"
	RunOpWait         RunOperation = "wait"
	RunOpCancel       RunOperation = "cancel"
	RunOpConversation RunOperation = "conversation"
)

type RunResult 

type RunResult struct {
	ID         string          `json:"runId"`
	RequestID  string          `json:"requestId,omitempty"`
	AgentID    string          `json:"agentId"`
	Status     RunStatus       `json:"status"`
	Result     string          `json:"result"`
	Model      *ModelSelection `json:"model,omitempty"`
	DurationMS int             `json:"durationMs"`
	Git        *RunGitInfo     `json:"git,omitempty"`
	CreatedAt  string          `json:"createdAt,omitempty"`
}

RunResult is the terminal outcome of a run.

func Prompt 

func Prompt(ctx context.Context, message any, opts AgentOptions, clientOpts ...ClientOption) (RunResult, error)

Prompt is a one-shot helper: create agent, send, wait, and close.

type RunResultStatus 

type RunResultStatus = RunStatus

RunResultStatus is the terminal status returned by Wait.

type RunSnapshot 

type RunSnapshot = RunResult

RunSnapshot is a point-in-time view of a run.

type RunStatus 

type RunStatus string

RunStatus is the lifecycle state of a run. 

const (
	RunStatusRunning   RunStatus = "running"
	RunStatusFinished  RunStatus = "finished"
	RunStatusError     RunStatus = "error"
	RunStatusCancelled RunStatus = "cancelled"
	RunStatusExpired   RunStatus = "expired"
)

type RunStreamEvent 

type RunStreamEvent struct {
	Kind              string
	Offset            string
	SDKMessage        SDKMessage
	InteractionUpdate InteractionUpdate
	Step              ConversationStep
	Result            map[string]any
	Done              map[string]any
	ResultIsFull      bool
}

RunStreamEvent is a low-level stream envelope.

func ParseRunStreamEvent 

func ParseRunStreamEvent(m map[string]any) RunStreamEvent

ParseRunStreamEvent parses a stream envelope.

type SDKAgentInfo 

type SDKAgentInfo struct {
	AgentID      string            `json:"agentId"`
	Name         string            `json:"name"`
	Summary      string            `json:"summary"`
	LastModified string            `json:"lastModified,omitempty"`
	Status       string            `json:"status,omitempty"`
	CreatedAt    string            `json:"createdAt,omitempty"`
	Archived     bool              `json:"archived"`
	Runtime      string            `json:"runtime,omitempty"`
	CWD          string            `json:"cwd,omitempty"`
	Env          *CloudEnvironment `json:"env,omitempty"`
	Repos        []string          `json:"repos,omitempty"`
}

SDKAgentInfo describes a known agent.

func GetAgent 

func GetAgent(ctx context.Context, agentID string, opts GetAgentOptions, clientOpts ...ClientOption) (SDKAgentInfo, error)

GetAgent fetches agent metadata by ID.

type SDKArtifact 

type SDKArtifact = SdkArtifact

SDKArtifact is an alias matching the TypeScript export name.

type SDKError 

type SDKError = AgentError

SDKError is a backward-compatible alias.

type SDKImage 

type SDKImage struct {
	URL       string
	Data      string
	MimeType  string
	Dimension *SDKImageDimension
}

SDKImage is an image attachment for user messages.

func ImageFromFile 

func ImageFromFile(path string, mimeType string, dim *SDKImageDimension) (SDKImage, error)

func ImageFromURL 

func ImageFromURL(url string, dim *SDKImageDimension) SDKImage

func (SDKImage) ToWire 

func (i SDKImage) ToWire() map[string]any

type SDKImageDimension 

type SDKImageDimension struct {
	Width  int `json:"width"`
	Height int `json:"height"`
}

SDKImageDimension describes image size metadata.

type SDKMessage 

type SDKMessage struct {
	Type               string
	AgentID            string
	RunID              string
	Subtype            string
	Model              *ModelSelection
	Tools              []string
	UserContent        []TextBlock
	AssistantContent   []any
	ThinkingText       string
	ThinkingDurationMS *int
	ToolCallID         string
	ToolName           string
	ToolStatus         string
	ToolArgs           any
	ToolResult         any
	Status             string
	StatusMessage      string
	TaskStatus         string
	TaskText           string
	RequestID          string
	Raw                map[string]any
}

SDKMessage is a typed stream message during a run.

func SDKMessageFromJSON 

func SDKMessageFromJSON(m map[string]any) SDKMessage

SDKMessageFromJSON parses a wire SDK message.

type SDKModel 

type SDKModel struct {
	ID          string                     `json:"id"`
	DisplayName string                     `json:"displayName"`
	Description string                     `json:"description"`
	Parameters  []ModelParameterDefinition `json:"parameters,omitempty"`
	Variants    []ModelVariant             `json:"variants,omitempty"`
}

SDKModel describes an available model.

type SDKRepository 

type SDKRepository struct {
	URL string `json:"url"`
}

SDKRepository is a connected repository.

type SDKUser 

type SDKUser struct {
	APIKeyName    string `json:"apiKeyName"`
	CreatedAt     string `json:"createdAt"`
	UserID        *int   `json:"userId,omitempty"`
	UserEmail     string `json:"userEmail"`
	UserFirstName string `json:"userFirstName"`
	UserLastName  string `json:"userLastName"`
}

SDKUser is the authenticated API key owner.

type SDKUserMessage 

type SDKUserMessage = UserMessage

SDKUserMessage is the structured send message type (alias for UserMessage).

type SandboxOptions 

type SandboxOptions struct {
	Enabled *bool `json:"enabled,omitempty"`
}

SandboxOptions configures local sandbox behavior.

func (SandboxOptions) ToWire 

func (s SandboxOptions) ToWire() map[string]any

type SdkArtifact 

type SdkArtifact struct {
	Path      string `json:"path"`
	SizeBytes int    `json:"sizeBytes"`
	UpdatedAt string `json:"updatedAt"`
}

SdkArtifact is a file produced by an agent run.

type SendOptions 

type SendOptions struct {
	Model          any
	McpServers     map[string]McpServer
	Local          *LocalSendOptions
	IdempotencyKey string
	Mode           AgentMode
	OnDelta        DeltaCallback
	OnStep         StepCallback
}

SendOptions configures a single prompt submission.

func (SendOptions) ToWire 

func (o SendOptions) ToWire() map[string]any

type SettingSource 

type SettingSource string

SettingSource controls which ambient settings are loaded for local agents. 

const (
	SettingSourceProject SettingSource = "project"
	SettingSourceUser    SettingSource = "user"
	SettingSourceTeam    SettingSource = "team"
	SettingSourceMDM     SettingSource = "mdm"
	SettingSourcePlugins SettingSource = "plugins"
	SettingSourceAll     SettingSource = "all"
)

type SetupOptions 

type SetupOptions struct {
	Local     bool
	BridgeDir string
	Version   string
}

SetupOptions configures prerequisite installation for the Go SDK.

type StdioMcpServerConfig 

type StdioMcpServerConfig struct {
	Command string
	Args    []string
	Env     map[string]string
	CWD     string
}

StdioMcpServerConfig configures a stdio MCP server.

func (StdioMcpServerConfig) ToWire 

func (c StdioMcpServerConfig) ToWire() map[string]any

type StepCallback 

type StepCallback func(ConversationStep)

StepCallback receives completed conversation steps during streaming.

type TextBlock 

type TextBlock struct {
	Type string `json:"type"`
	Text string `json:"text"`
}

TextBlock is assistant/user text content.

type ToolCallbackServer 

type ToolCallbackServer struct {
	URL   string
	Token string
	// contains filtered or unexported fields
}

ToolCallbackServer hosts custom tool execute handlers for the bridge.

func NewToolCallbackServer 

func NewToolCallbackServer() *ToolCallbackServer

NewToolCallbackServer starts a loopback Connect/JSON server for custom tools.

func (*ToolCallbackServer) Close 

func (s *ToolCallbackServer) Close()

Close stops the callback server.

func (*ToolCallbackServer) RegisterAgent 

func (s *ToolCallbackServer) RegisterAgent(agentID string, tools map[string]CustomTool)

RegisterAgent registers custom tools for an agent ID.

func (*ToolCallbackServer) UnregisterAgent 

func (s *ToolCallbackServer) UnregisterAgent(agentID string)

UnregisterAgent removes custom tools for an agent ID.

type ToolUseBlock 

type ToolUseBlock struct {
	Type  string `json:"type"`
	ID    string `json:"id"`
	Name  string `json:"name"`
	Input any    `json:"input,omitempty"`
}

ToolUseBlock is a tool invocation in assistant content.

type UnknownAgentError 

type UnknownAgentError struct{ *AgentError }

type UnsupportedRunOperationError 

type UnsupportedRunOperationError struct {
	*AgentError
	Operation string
}

type UserMessage 

type UserMessage struct {
	Text   string
	Images []SDKImage
}

UserMessage is a prompt with optional images.

func UserMessageFromText 

func UserMessageFromText(text string) UserMessage

func (UserMessage) ToWire 

func (m UserMessage) ToWire() map[string]any

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.