agent

Documentation

Index

• type Agent
  • func CreateAgent(ctx context.Context, opts *AgentCreationOptions) (*Agent, error)
  • func NewAgent(ctx context.Context, agentConfig *AgentConfig) (*Agent, error)
  • func (a *Agent) Close() error
  • func (a *Agent) GenerateWithLoop(ctx context.Context, messages []fantasy.Message, onToolCall ToolCallHandler, ...) (*GenerateWithLoopResult, error)
  • func (a *Agent) GenerateWithLoopAndStreaming(ctx context.Context, messages []fantasy.Message, onToolCall ToolCallHandler, ...) (*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) GetMCPToolCount() int
  • func (a *Agent) GetModel() fantasy.LanguageModel
  • func (a *Agent) GetTools() []fantasy.AgentTool
  • func (a *Agent) SetModel(ctx context.Context, config *models.ProviderConfig) error
• type AgentConfig
• type AgentCreationOptions
• type GenerateWithLoopResult
• type ReasoningDeltaHandler
• type ResponseHandler
• type SpinnerFunc
• type StreamingResponseHandler
• type ToolCallContentHandler
• type ToolCallHandler
• type ToolExecutionHandler
• type ToolResultHandler

Types

type Agent

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

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

func CreateAgent

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

CreateAgent creates an agent with optional spinner for Ollama models. It shows a loading spinner for Ollama models if ShowSpinner is true and not in quiet mode. Returns the created agent or an error if creation fails.

func NewAgent

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

NewAgent creates a new Agent with core tools and optional MCP tool integration. Core tools (bash, read, write, edit, grep, find, ls) are always registered. External MCP tools are loaded from the config if any MCP servers are configured.

func (*Agent) Close

func (a *Agent) Close() error

Close closes the agent and cleans up resources.

func (*Agent) GenerateWithLoop

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

GenerateWithLoop processes messages with a custom loop that displays tool calls in real-time.

func (*Agent) GenerateWithLoopAndStreaming

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

GenerateWithLoopAndStreaming processes messages using the fantasy agent with streaming and callbacks. Fantasy handles the tool call loop internally. We map fantasy's rich callback system to kit's existing callback interface for UI integration.

func (*Agent) GetCoreToolCount

func (a *Agent) GetCoreToolCount() int

GetCoreToolCount returns the number of core tools.

func (*Agent) GetExtensionToolCount

func (a *Agent) GetExtensionToolCount() int

GetExtensionToolCount returns the number of tools registered by extensions.

func (*Agent) GetLoadedServerNames

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

GetLoadedServerNames returns the names of successfully loaded MCP servers.

func (*Agent) GetLoadingMessage

func (a *Agent) GetLoadingMessage() string

GetLoadingMessage returns the loading message from provider creation.

func (*Agent) GetMCPToolCount

func (a *Agent) GetMCPToolCount() int

GetMCPToolCount returns the number of tools loaded from external MCP servers.

func (*Agent) GetModel

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

GetModel returns the underlying fantasy LanguageModel.

func (*Agent) GetTools

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

GetTools returns the list of available tools loaded in the agent, including core tools, MCP tools, and extension-registered tools.

func (*Agent) SetModel

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

SetModel swaps the agent's LLM provider to a new model. The existing tools, system prompt, and configuration are preserved. The old provider is closed if it has a closer. Returns the previous model string for notification.

type AgentConfig

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

	// 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

	// ToolWrapper is an optional function that wraps the combined tool list
	// before it is passed to the Fantasy 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
}

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
	// CoreTools overrides the default core tool set. If empty, core.AllTools()
	// is used.
	CoreTools []fantasy.AgentTool
	// ToolWrapper wraps the combined tool list before Fantasy agent creation.
	ToolWrapper func([]fantasy.AgentTool) []fantasy.AgentTool
	// ExtraTools are additional tools to include (e.g. from extensions).
	ExtraTools []fantasy.AgentTool
}

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

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 (crush-style)
	Messages []message.Message
	// TotalUsage contains aggregate token usage across all steps
	TotalUsage fantasy.Usage
}

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

type ReasoningDeltaHandler

type ReasoningDeltaHandler func(delta string)

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

type ResponseHandler

type ResponseHandler func(content string)

ResponseHandler is a function type for handling LLM responses.

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 StreamingResponseHandler

type StreamingResponseHandler func(content string)

StreamingResponseHandler is a function type for handling streaming LLM responses.

type ToolCallContentHandler

type ToolCallContentHandler func(content string)

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

type ToolCallHandler

type ToolCallHandler func(toolName, toolArgs string)

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

type ToolExecutionHandler

type ToolExecutionHandler func(toolName string, isStarting bool)

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

type ToolResultHandler

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

ToolResultHandler is a function type for handling tool results.