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 NewChartTool ¶ added in v0.11.0

func NewChartTool() *ChartTool

NewChartTool creates a new chart tool.

func WithBootstrapProfile ¶ added in v0.9.0

func WithBootstrapProfile(profile *profiles.BootstrapProfile) Option

WithBootstrapProfile sets the bootstrap profile for agent initialization. Profiles customize system prompts, tools, and context limits per-agent.

Example:

agent, err := agent.New(config,
    agent.WithBootstrapProfile(profiles.CodeAssistantProfile),
)

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 WithLeanLevel ¶ added in v0.9.0

func WithLeanLevel(level profiles.LeanLevel) Option

WithLeanLevel enables lean mode at the specified level. This is a convenience function for common lean mode configurations.

Example:

agent, err := agent.New(config,
    agent.WithLeanLevel(profiles.LeanLevelLight),
)

func WithLeanMode ¶ added in v0.9.0

func WithLeanMode(mode *profiles.LeanMode) Option

WithLeanMode enables lean mode for resource optimization. This is especially useful for local models with limited resources.

Example:

agent, err := agent.New(config,
    agent.WithLeanMode(profiles.NewLeanMode(profiles.LeanLevelModerate)),
)

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 WithMemory ¶ added in v0.11.0

func WithMemory(client *core.Client) Option

WithMemory sets the omnimemory client for semantic memory operations. This enables memory_store, memory_search, memory_recall, and other tools.

Example:

client, _ := core.NewClient(core.ClientConfig{
    Providers: []core.ProviderConfig{
        {Name: core.ProviderNameMemory},
    },
})
agent, err := agent.New(config,
    agent.WithMemory(client),
)

func WithMemoryConfig ¶ added in v0.11.0

func WithMemoryConfig(cfg core.ClientConfig) Option

WithMemoryConfig creates an omnimemory client with the given configuration. This is a convenience option that creates the client from configuration.

Example:

agent, err := agent.New(config,
    agent.WithMemoryConfig(core.ClientConfig{
        Providers: []core.ProviderConfig{
            {Name: core.ProviderNamePostgres, DSN: os.Getenv("DATABASE_URL")},
        },
    }),
)

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 WithOpenAPISkill ¶ added in v0.8.0

func WithOpenAPISkill(cfg openapiskill.Config) Option

WithOpenAPISkill registers an OpenAPI spec as a compiled skill. This parses the OpenAPI specification and exposes operations as tools.

Example:

agent, err := agent.New(config,
    agent.WithOpenAPISkill(openapiskill.Config{
        Name:    "petstore",
        SpecURL: "https://petstore3.swagger.io/api/v3/openapi.json",
        Auth: openapiskill.AuthConfig{
            Type:   openapiskill.AuthAPIKey,
            APIKey: os.Getenv("PETSTORE_API_KEY"),
        },
    }),
)

func WithProfileRegistry ¶ added in v0.9.0

func WithProfileRegistry(registry *profiles.ProfileRegistry) Option

WithProfileRegistry sets a profile registry for dynamic profile selection. This allows switching profiles at runtime based on context.

Example:

registry := profiles.NewProfileRegistry()
registry.Register(profiles.CodeAssistantProfile)
registry.Register(profiles.RestrictedProfile)

agent, err := agent.New(config,
    agent.WithProfileRegistry(registry),
)

func WithProgressMode ¶ added in v0.9.0

func WithProgressMode(mode profiles.ProgressDetailMode, output io.Writer) Option

WithProgressMode sets the progress detail mode for tool execution. This is a convenience function that creates a progress reporter with the given mode.

Example:

agent, err := agent.New(config,
    agent.WithProgressMode(profiles.ProgressModeVerbose, os.Stderr),
)

func WithProgressReporter ¶ added in v0.9.0

func WithProgressReporter(reporter *profiles.ProgressReporter) Option

WithProgressReporter sets the progress reporter for tool execution. This controls how tool execution progress is displayed.

Example:

reporter := profiles.NewProgressReporter(profiles.ProgressModeVerbose, os.Stderr)

agent, err := agent.New(config,
    agent.WithProgressReporter(reporter),
)

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 WithSkillDirs ¶ added in v0.7.0

func WithSkillDirs(dirs ...string) Option

WithSkillDirs sets the directories to search for skills. Directory skills override embedded skills with the same name.

Example:

agent, err := agent.New(config,
    agent.WithSkillDirs("./skills", "~/.omniagent/skills"),
)

func WithSkillExcludes ¶ added in v0.7.0

func WithSkillExcludes(names ...string) Option

WithSkillExcludes prevents skills with matching names from being loaded. Applied after includes.

Example:

agent, err := agent.New(config,
    agent.WithSkillPack(skills.Default().FS()),
    agent.WithSkillExcludes("slack", "trello"),
)

func WithSkillIncludes ¶ added in v0.7.0

func WithSkillIncludes(names ...string) Option

WithSkillIncludes limits loaded skills to only those with matching names. If not set, all discovered skills are included.

Example:

agent, err := agent.New(config,
    agent.WithSkillPack(skills.Default().FS()),
    agent.WithSkillIncludes("github", "weather"),
)

func WithSkillManager ¶ added in v0.7.0

func WithSkillManager(mgr *skills.Manager) Option

WithSkillManager sets a custom skill manager for the agent. Use this for advanced skill loading scenarios.

Example:

mgr := skills.NewManager(skills.ManagerConfig{
    Packs:    []fs.FS{skills.Default().FS()},
    Dirs:     []string{"./custom-skills"},
    Includes: []string{"github"},
})
mgr.Load()

agent, err := agent.New(config,
    agent.WithSkillManager(mgr),
)

func WithSkillPack ¶ added in v0.7.0

func WithSkillPack(pack fs.FS) Option

WithSkillPack registers an embedded skill pack with the agent. Skills from packs are loaded after directory skills, so directory skills with the same name will override pack skills.

Example:

import skills "github.com/plexusone/omniagent-skills"

agent, err := agent.New(config,
    agent.WithSkillPack(skills.Default().FS()),
)

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.