agent

func New ¶

func New(config Config, opts ...Option) (*Agent, error)

New creates a new agent with optional configuration.

Example:

agent, err := agent.New(config,
    agent.WithStorage(sqliteStorage),
    agent.WithCompiledSkill(investSkill),
)

func NewBaseTool ¶

func NewBaseTool(name, description string, parameters map[string]interface{}, handler func(ctx context.Context, args json.RawMessage) (string, error)) *BaseTool

NewBaseTool creates a new base tool.

func WithCompiledHook ¶ added in v0.6.0

func WithCompiledHook(hook hooks.Hook) Option

WithCompiledHook registers a compiled hook for handling events. Compiled hooks implement the hooks.Hook interface and support initialization, cleanup, and multi-event handling.

Example:

type AuditHook struct {
    logger *slog.Logger
}

func (h *AuditHook) Name() string { return "audit" }
func (h *AuditHook) Events() []hooks.EventType {
    return []hooks.EventType{hooks.EventMessageReceived, hooks.EventMessageSent}
}
func (h *AuditHook) Handle(ctx context.Context, event hooks.Event) error {
    h.logger.Info("event", "type", event.Type, "data", event.Data)
    return nil
}
func (h *AuditHook) Init(ctx context.Context) error { return nil }
func (h *AuditHook) Close() error { return nil }

agent, err := agent.New(config,
    agent.WithCompiledHook(&AuditHook{logger: slog.Default()}),
)

func WithCompiledSkill ¶ added in v0.5.0

func WithCompiledSkill(skill compiled.Skill) Option

WithCompiledSkill registers a compiled skill with the agent. Multiple skills can be registered by calling this option multiple times.

Example:

agent, err := agent.New(config,
    agent.WithCompiledSkill(investSkill),
    agent.WithCompiledSkill(weatherSkill),
)

func WithContextConfig ¶ added in v0.6.0

func WithContextConfig(cfg agentctx.Config) Option

WithContextConfig creates a context engine with the given configuration. This is a convenience option for simple context configuration.

Example:

agent, err := agent.New(config,
    agent.WithContextConfig(context.Config{
        MaxMessages: 50,
        MaxTokens:   8000,
    }),
)

func WithContextEngine ¶ added in v0.6.0

func WithContextEngine(engine *agentctx.Engine) Option

WithContextEngine sets the context engine for conversation management. This enables automatic windowing and token limit enforcement.

Example:

engine := context.New(context.Config{
    MaxMessages: 50,
    MaxTokens:   8000,
})
agent, err := agent.New(config,
    agent.WithContextEngine(engine),
)

func WithCronScheduler ¶ added in v0.6.0

func WithCronScheduler() Option

WithCronScheduler registers the cron skill for scheduled job execution. This requires storage to be configured (use WithStorage or WithSessionsFromStorage).

Example:

sqliteStore, _ := sqlite.New(sqlite.Config{Path: "data.db"})
agent, err := agent.New(config,
    agent.WithSessionsFromStorage(sqliteStore),
    agent.WithCronScheduler(),
)

func WithHook ¶ added in v0.6.0

func WithHook(event hooks.EventType, handler hooks.HandlerFunc) Option

WithHook registers a quick handler for an event type. This is the simplest way to handle events.

Example:

agent, err := agent.New(config,
    agent.WithHook(hooks.EventMessageReceived, func(ctx context.Context, e hooks.Event) error {
        msg := e.Data.(hooks.MessageEvent)
        log.Printf("Received: %s", msg.Content)
        return nil
    }),
)

func WithMCPSkill ¶ added in v0.6.0

func WithMCPSkill(cfg mcpskill.Config) Option

WithMCPSkill registers an MCP server as a compiled skill. This spawns the MCP server as a subprocess and exposes its tools to the agent.

Example:

agent, err := agent.New(config,
    agent.WithMCPSkill(mcpskill.Config{
        Name:    "github",
        Command: []string{"npx", "-y", "@modelcontextprotocol/server-github"},
        Env: map[string]string{
            "GITHUB_TOKEN": os.Getenv("GITHUB_TOKEN"),
        },
    }),
)

func WithMaxMessages ¶ added in v0.6.0

func WithMaxMessages(max int) Option

WithMaxMessages sets a simple message limit for context. This creates a context engine with only a message limit.

Example:

agent, err := agent.New(config,
    agent.WithMaxMessages(50),
)

func WithNamedHook ¶ added in v0.6.0

func WithNamedHook(event hooks.EventType, name string, handler hooks.HandlerFunc) Option

WithNamedHook registers a named handler for an event type. The name is used in logging to identify the handler.

Example:

agent, err := agent.New(config,
    agent.WithNamedHook(hooks.EventMessageReceived, "audit-log", func(ctx context.Context, e hooks.Event) error {
        msg := e.Data.(hooks.MessageEvent)
        log.Printf("[AUDIT] Received: %s", msg.Content)
        return nil
    }),
)

func WithSessionStore ¶ added in v0.6.0

func WithSessionStore(store *sessions.Store) Option

WithSessionStore sets the session store for conversation persistence. This enables ProcessWithSession to maintain conversation history.

Example:

sqliteStore, _ := sqlite.New(sqlite.Config{Path: "data.db"})
sessionStore := sessions.NewStore(sessions.StoreConfig{Backend: sqliteStore})
agent, err := agent.New(config,
    agent.WithSessionStore(sessionStore),
)

func WithSessionsFromStorage ¶ added in v0.6.0

func WithSessionsFromStorage(backend kvs.Store) Option

WithSessionsFromStorage creates a session store from the given KVS backend. This is a convenience option that combines WithStorage and WithSessionStore.

Example:

sqliteStore, _ := sqlite.New(sqlite.Config{Path: "data.db"})
agent, err := agent.New(config,
    agent.WithSessionsFromStorage(sqliteStore),
)

func WithStorage ¶ added in v0.5.0

func WithStorage(s kvs.Store) Option

WithStorage sets the storage backend for the agent. Storage is automatically injected into any storage-aware compiled skills.

Example:

sqliteStore, _ := sqlite.New(sqlite.Config{Path: "data.db"})
agent, err := agent.New(config,
    agent.WithStorage(sqliteStore),
    agent.WithCompiledSkill(investSkill),
)

func WithTool ¶ added in v0.5.0

func WithTool(tool Tool) Option

WithTool registers a single tool with the agent.

Example:

agent, err := agent.New(config,
    agent.WithTool(myTool),
)

func WithWebhookHook ¶ added in v0.6.0

func WithWebhookHook(webhook *hooks.WebhookHook) Option

WithWebhookHook registers a webhook-based hook that sends events to an HTTP endpoint.

Example:

agent, err := agent.New(config,
    agent.WithWebhookHook(&hooks.WebhookHook{
        HookName:   "slack-notify",
        HookEvents: []hooks.EventType{hooks.EventMessageSent},
        URL:        "https://hooks.slack.com/services/xxx",
        Method:     "POST",
        Timeout:    5 * time.Second,
    }),
)

func NewSearchTool ¶

func NewSearchTool() (*SearchTool, error)

NewSearchTool creates a new search tool.

func NewToolRegistry ¶

func NewToolRegistry() *ToolRegistry

NewToolRegistry creates a new tool registry.