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