agent

type Agent ¶

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

Agent represents an AI agent with core tool integration using the LLM library. Core tools (bash, read, write, edit, grep, find, ls) are registered as direct AgentTool implementations — no MCP layer, no serialization overhead. Additional tools from external MCP servers can be loaded alongside core tools.

When MCP servers are configured, tool loading happens in the background so the agent (and UI) can start immediately. The first LLM call automatically waits for MCP tools to finish loading before proceeding.

func CreateAgent(ctx context.Context, opts *AgentCreationOptions) (*Agent, error)

func NewAgent(ctx context.Context, agentConfig *AgentConfig) (*Agent, error)

func (a *Agent) AddMCPServer(ctx context.Context, name string, cfg config.MCPServerConfig) (int, error)

func (a *Agent) Close() error

func (a *Agent) GenerateWithCallbacks(ctx context.Context, messages []fantasy.Message,
	cb GenerateCallbacks,
) (*GenerateWithLoopResult, error)

func (a *Agent) GenerateWithLoop(ctx context.Context, messages []fantasy.Message,
	onToolCall ToolCallHandler, onToolExecution ToolExecutionHandler, onToolResult ToolResultHandler,
	onResponse ResponseHandler, onToolCallContent ToolCallContentHandler,
) (*GenerateWithLoopResult, error)

func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fantasy.Message,
	onToolCall ToolCallHandler, onToolExecution ToolExecutionHandler, onToolResult ToolResultHandler,
	onResponse ResponseHandler, onToolCallContent ToolCallContentHandler,
	onStreamingResponse StreamingResponseHandler,
	onReasoningDelta ReasoningDeltaHandler,
	onReasoningComplete ReasoningCompleteHandler,
	onToolOutput ToolOutputHandler,
	onStepMessages StepMessagesHandler,
	onStepUsage StepUsageHandler,
	onPasswordPrompt PasswordPromptHandler,
	onToolCallStart ToolCallStartHandler,
	onToolCallDelta ToolCallDeltaHandler,
	onToolCallEnd ToolCallEndHandler,
) (*GenerateWithLoopResult, error)

func (a *Agent) GetCoreToolCount() int

func (a *Agent) GetExtensionToolCount() int

func (a *Agent) GetLoadedServerNames() []string

func (a *Agent) GetLoadingMessage() string

func (a *Agent) GetMCPPrompt(ctx context.Context, serverName, promptName string, args map[string]string) (*tools.MCPPromptResult, error)

func (a *Agent) GetMCPPrompts() []tools.MCPPrompt

func (a *Agent) GetMCPResources() []tools.MCPResource

func (a *Agent) GetMCPToolCount() int

func (a *Agent) GetMCPToolManager() *tools.MCPToolManager

func (a *Agent) GetMaxTokens() int

func (a *Agent) GetModel() fantasy.LanguageModel

func (a *Agent) GetTools() []fantasy.AgentTool

func (a *Agent) MCPToolsReady() bool

func (a *Agent) ReadMCPResource(ctx context.Context, serverName, uri string) (*tools.MCPResourceContent, error)

func (a *Agent) RemoveMCPServer(name string) error

func (a *Agent) SetExtraTools(extraTools []fantasy.AgentTool)

func (a *Agent) SetModel(ctx context.Context, config *models.ProviderConfig) error

func (a *Agent) SubscribeMCPResource(ctx context.Context, serverName, uri string) error

func (a *Agent) UnsubscribeMCPResource(ctx context.Context, serverName, uri string) error

func (a *Agent) WaitForMCPTools() error

type AgentConfig ¶

type AgentConfig struct {
	ModelConfig      *models.ProviderConfig
	MCPConfig        *config.Config
	SystemPrompt     string
	MaxSteps         int
	StreamingEnabled bool
	DebugLogger      tools.DebugLogger

	// AuthHandler handles OAuth authorization for remote MCP servers.
	// When set, remote transports are configured with OAuth support.
	// If nil, remote MCP servers that require OAuth will fail to connect.
	AuthHandler tools.MCPAuthHandler

	// TokenStoreFactory, if non-nil, creates a custom token store for each
	// remote MCP server's OAuth tokens. When nil, the default file-based
	// token store is used.
	TokenStoreFactory tools.TokenStoreFactory

	// CoreTools overrides the default core tool set. If empty, core.AllTools()
	// is used. This allows SDK users to provide a custom tool set (e.g.
	// CodingTools or tools with a custom WorkDir).
	CoreTools []fantasy.AgentTool

	// DisableCoreTools, when true, prevents loading any core tools.
	// If both DisableCoreTools is true and CoreTools is empty, the agent
	// will have no tools (useful for simple chat completions).
	DisableCoreTools bool

	// ToolWrapper is an optional function that wraps the combined tool list
	// before it is passed to the LLM agent. Used by the extensions system
	// to intercept tool calls/results.
	ToolWrapper func([]fantasy.AgentTool) []fantasy.AgentTool

	// ExtraTools are additional tools to include alongside core and MCP tools.
	// Used by extensions to register custom tools.
	ExtraTools []fantasy.AgentTool

	// OnMCPServerLoaded, if non-nil, is called when each MCP server finishes
	// loading (successfully or with error). The callback receives the server
	// name, tool count, and any error. Called from the background goroutine.
	OnMCPServerLoaded func(serverName string, toolCount int, err error)
}

AgentConfig holds configuration options for creating a new Agent.

type AgentCreationOptions ¶

type AgentCreationOptions struct {
	// ModelConfig specifies the LLM provider and model to use
	ModelConfig *models.ProviderConfig
	// MCPConfig contains MCP server configurations
	MCPConfig *config.Config
	// SystemPrompt is the initial system message for the agent
	SystemPrompt string
	// MaxSteps limits the number of tool calls (0 for unlimited)
	MaxSteps int
	// StreamingEnabled controls whether responses are streamed
	StreamingEnabled bool
	// ShowSpinner indicates whether to show a spinner for Ollama models during loading
	ShowSpinner bool // For Ollama models
	// Quiet suppresses the spinner even if ShowSpinner is true
	Quiet bool // Skip spinner if quiet
	// SpinnerFunc is the function to show spinner, provided by the caller
	SpinnerFunc SpinnerFunc // Function to show spinner (provided by caller)
	// DebugLogger is an optional logger for debugging MCP communications
	DebugLogger tools.DebugLogger // Optional debug logger
	// AuthHandler handles OAuth authorization for remote MCP servers
	AuthHandler tools.MCPAuthHandler
	// TokenStoreFactory, if non-nil, creates a custom token store for each
	// remote MCP server's OAuth tokens. When nil, the default file-based
	// token store is used.
	TokenStoreFactory tools.TokenStoreFactory
	// CoreTools overrides the default core tool set. If empty, core.AllTools()
	// is used.
	CoreTools []fantasy.AgentTool
	// DisableCoreTools, when true, prevents loading any core tools.
	// If both DisableCoreTools is true and CoreTools is empty, the agent
	// will have no tools (useful for simple chat completions).
	DisableCoreTools bool
	// ToolWrapper wraps the combined tool list before agent creation.
	ToolWrapper func([]fantasy.AgentTool) []fantasy.AgentTool
	// ExtraTools are additional tools to include (e.g. from extensions).
	ExtraTools []fantasy.AgentTool
	// OnMCPServerLoaded, if non-nil, is called when each MCP server finishes
	// loading (successfully or with error). Called from the background goroutine.
	OnMCPServerLoaded func(serverName string, toolCount int, err error)
}

AgentCreationOptions contains options for creating an agent. It extends AgentConfig with UI-related options for showing progress during creation.

type ErrorHandler ¶ added in v0.60.0

type ErrorHandler func(err error)

ErrorHandler is called when an agent-level error occurs.

type GenerateCallbacks ¶ added in v0.60.0

type GenerateCallbacks struct {
	OnToolCall          ToolCallHandler
	OnToolExecution     ToolExecutionHandler
	OnToolResult        ToolResultHandler
	OnResponse          ResponseHandler
	OnToolCallContent   ToolCallContentHandler
	OnStreamingResponse StreamingResponseHandler
	OnReasoningDelta    ReasoningDeltaHandler
	OnReasoningComplete ReasoningCompleteHandler
	OnToolOutput        ToolOutputHandler
	OnStepMessages      StepMessagesHandler
	OnStepUsage         StepUsageHandler
	OnPasswordPrompt    PasswordPromptHandler
	OnToolCallStart     ToolCallStartHandler
	OnToolCallDelta     ToolCallDeltaHandler
	OnToolCallEnd       ToolCallEndHandler

	// New callbacks for previously unwired Fantasy lifecycle events.
	OnStepStart      StepStartHandler
	OnStepFinish     StepFinishHandler
	OnTextStart      TextStartHandler
	OnTextEnd        TextEndHandler
	OnReasoningStart ReasoningStartHandler
	OnWarnings       WarningsHandler
	OnSource         SourceHandler
	OnStreamFinish   StreamFinishHandler
	OnError          ErrorHandler
	OnRetry          RetryHandler
	OnPrepareStep    PrepareStepHandler
}

GenerateCallbacks consolidates all callback functions for GenerateWithLoopAndStreaming into a single struct. This replaces the previous 16+ positional callback parameters, making it easier to add new callbacks without breaking existing callers (new fields default to nil).

type GenerateWithLoopResult ¶

type GenerateWithLoopResult struct {
	// FinalResponse is the last message generated by the model
	FinalResponse *fantasy.Response
	// ConversationMessages contains all messages in the conversation including tool calls and results
	ConversationMessages []fantasy.Message
	// Messages contains the conversation as custom content blocks
	Messages []message.Message
	// TotalUsage contains aggregate token usage across all steps
	TotalUsage fantasy.Usage
	// StopReason is the LLM provider's finish reason for the final response.
	StopReason string
	// PersistedMessageCount is the number of new messages (beyond the original
	// input) that were already persisted incrementally via OnStepMessages during
	// generation. The caller should skip these when doing post-generation
	// persistence to avoid duplicates.
	PersistedMessageCount int
}

GenerateWithLoopResult contains the result and conversation history from an agent interaction.

type PasswordPromptHandler ¶ added in v0.53.0

type PasswordPromptHandler = core.PasswordPromptCallback

PasswordPromptHandler is a function type for password prompts. Used by the bash tool when sudo requires a password. The handler receives a prompt message and returns the password and whether it was cancelled. Note: This is an alias for core.PasswordPromptCallback.

type PrepareStepHandler ¶ added in v0.60.0

type PrepareStepHandler func(stepNumber int, messages []fantasy.Message) []fantasy.Message

PrepareStepHandler is called between steps to allow message modification. It receives the step number and current messages, and returns replacement messages (or nil to keep unchanged).

type ReasoningCompleteHandler ¶ added in v0.35.0

type ReasoningCompleteHandler func()

ReasoningCompleteHandler is a function type for handling reasoning/thinking completion. Called when the last reasoning token has been processed, before text streaming starts.

type ReasoningDeltaHandler ¶ added in v0.7.0

type ReasoningDeltaHandler func(delta string)

ReasoningDeltaHandler is a function type for handling streaming reasoning/thinking deltas.

type ReasoningStartHandler ¶ added in v0.60.0

type ReasoningStartHandler func(id string)

ReasoningStartHandler is called when the LLM begins reasoning/thinking.

type ResponseHandler ¶

type ResponseHandler func(content string)

ResponseHandler is a function type for handling LLM responses.

type RetryHandler ¶ added in v0.60.0

type RetryHandler func(attempt int, err error)

RetryHandler is called when the LLM request is retried.

type SourceHandler ¶ added in v0.60.0

type SourceHandler func(sourceType, id, url, title string)

SourceHandler is called when the LLM references a source.

type SpinnerFunc ¶

type SpinnerFunc func(fn func() error) error

SpinnerFunc is a function type for showing spinners during agent creation. It executes the provided function while displaying an animated spinner.

type SteerMessage ¶ added in v0.36.0

type SteerMessage struct {
	Text  string
	Files []fantasy.FilePart
}

SteerMessage carries a steering prompt and optional file attachments (e.g. clipboard images) through the steer channel.

type StepFinishHandler ¶ added in v0.60.0

type StepFinishHandler func(stepNumber int, hasToolCalls bool, finishReason string, usage fantasy.Usage)

StepFinishHandler is called when a step completes with full context.

type StepMessagesHandler ¶ added in v0.44.0

type StepMessagesHandler func(stepMessages []fantasy.Message)

StepMessagesHandler is a function type for persisting messages after each complete step in a multi-step agent turn. The handler receives the messages produced by the step (typically an assistant message with tool calls followed by a tool-role message with results, or a final assistant message with text). This enables incremental session persistence so that progress is saved as it happens rather than only at the end of the turn.

type StepStartHandler ¶ added in v0.60.0

type StepStartHandler func(stepNumber int)

StepStartHandler is called when a new LLM step begins within a turn.

type StepUsageHandler ¶ added in v0.23.0

type StepUsageHandler func(inputTokens, outputTokens, cacheReadTokens, cacheCreationTokens int64)

StepUsageHandler is a function type for handling token usage after each complete step in a multi-step agent turn. This enables real-time cost tracking during long-running tool-calling conversations.

type StreamFinishHandler ¶ added in v0.60.0

type StreamFinishHandler func(usage fantasy.Usage, finishReason string)

StreamFinishHandler is called when a per-step LLM stream completes.

type StreamingResponseHandler ¶

type StreamingResponseHandler func(content string)

StreamingResponseHandler is a function type for handling streaming LLM responses.

type TextEndHandler ¶ added in v0.60.0

type TextEndHandler func(id string)

TextEndHandler is called when the LLM finishes generating text content.

type TextStartHandler ¶ added in v0.60.0

type TextStartHandler func(id string)

TextStartHandler is called when the LLM begins generating text content.

type ToolCallContentHandler ¶

type ToolCallContentHandler func(content string)

ToolCallContentHandler is a function type for handling content that accompanies tool calls.

type ToolCallDeltaHandler ¶ added in v0.58.0

type ToolCallDeltaHandler func(toolCallID, delta string)

ToolCallDeltaHandler is a function type for handling streamed fragments of tool call arguments as they arrive from the LLM.

type ToolCallEndHandler ¶ added in v0.58.0

type ToolCallEndHandler func(toolCallID string)

ToolCallEndHandler is a function type for handling the end of tool argument streaming, before the tool call is parsed and execution begins.

type ToolCallHandler ¶

type ToolCallHandler func(toolCallID, toolName, toolArgs string)

ToolCallHandler is a function type for handling tool calls as they happen.

type ToolCallStartHandler ¶ added in v0.58.0

type ToolCallStartHandler func(toolCallID, toolName string)

ToolCallStartHandler is a function type for handling the moment when the LLM begins generating tool call arguments. The tool name is known but the full argument JSON is still streaming.

type ToolExecutionHandler ¶

type ToolExecutionHandler func(toolCallID, toolName, toolArgs string, isStarting bool)

ToolExecutionHandler is a function type for handling tool execution start/end events.

type ToolOutputHandler ¶ added in v0.20.0

type ToolOutputHandler = core.ToolOutputCallback

ToolOutputHandler is a function type for handling streaming tool output chunks. Used by tools like bash to stream output as it arrives rather than waiting for the command to complete. The isStderr flag indicates if the chunk contains stderr output. Note: This is an alias for core.ToolOutputCallback to avoid import cycles.

type ToolResultHandler ¶

type ToolResultHandler func(toolCallID, toolName, toolArgs, result, metadata string, isError bool)

ToolResultHandler is a function type for handling tool results. The metadata parameter carries optional structured data (e.g. file diff info) from the tool execution, JSON-encoded. It may be empty.

type WarningsHandler ¶ added in v0.60.0

type WarningsHandler func(warnings []string)

WarningsHandler is called when the LLM provider returns warnings.