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 WithRole ¶ added in v0.13.0

func WithRole(r role.Role, skills ...compiled.Skill) Option

WithRole registers a role with the agent. A role is a high-level agent persona that combines skills, workflows, and system prompts into a cohesive behavior.

The role's required skills must be provided as compiled skills. The role's system prompt will be prepended to the agent's system prompt.

Example:

pmRole := meetingpm.New(meetingpm.Config{
    DefaultConfluenceSpace: "TEAM",
})
meetingSkill := meeting.NewSkill(...)
googleSkill := google.NewSkill(...)

agent, err := agent.New(config,
    agent.WithRole(pmRole, meetingSkill, googleSkill),
)

func WithRoleManager ¶ added in v0.13.0

func WithRoleManager(mgr *roles.Manager) Option

WithRoleManager sets a pre-configured role manager. Use this for advanced role configuration scenarios.

Example:

mgr, _ := roles.NewManager(pmRole, meetingSkill, googleSkill)
mgr.Init(ctx)

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

func WithSecretEnv ¶ added in v0.16.0

func WithSecretEnv(env map[string]string) Option

WithSecretEnv injects secrets (keyed by environment-variable name) into the agent's secrets-aware compiled skills — notably MCP servers, whose subprocess environment receives them. Injection is order-independent: skills registered before or after this option all receive the secrets before Init().

Per-agent runtime instances (RMI-OMNIAGENT-310) use this to bind agent-scoped secrets, so two agents' MCP subprocesses run with disjoint environments.

Example:

agent, err := agent.New(config,
    agent.WithMCPSkill(mcpskill.Config{Name: "github", Command: cmd}),
    agent.WithSecretEnv(map[string]string{"GITHUB_TOKEN": token}),
)

func WithSessionRollover ¶ added in v0.16.0

func WithSessionRollover(policy sessions.RolloverPolicy) Option

WithSessionRollover enables automatic session rollover. When a session exceeds the policy's idle timeout or crosses a calendar-day boundary, its conversation ends: a session.rollover event carrying the ended transcript fires (the built-in session-memory hook persists it to semantic memory when memory is configured), and the turn continues on a fresh conversation under the same session ID. Manual session clears are unaffected and emit no rollover.

The day boundary resolves in policy.Location when set, otherwise the agent's configured Timezone (default UTC).

Example:

agent, err := agent.New(config,
    agent.WithSessionRollover(sessions.RolloverPolicy{
        IdleTimeout: 4 * time.Hour,
        Daily:       true,
    }),
)

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 WithToolsAllowHook ¶ added in v0.16.0

func WithToolsAllowHook(fn hooks.ToolsAllowFunc) Option

WithToolsAllowHook registers a synchronous pre-turn hook that can narrow the tools submitted to the model for a single turn. The hook runs before every model call: returning nil leaves the tool set unchanged, an empty slice removes all optional tools for that turn, and a list of names narrows the set to its intersection with the available tools. The tool registry itself is never mutated.

Example:

agent, err := agent.New(config,
    agent.WithToolsAllowHook(func(ctx context.Context, turn hooks.PromptTurn) []string {
        if turn.Iteration > 2 {
            return []string{} // stop offering tools after 3 iterations
        }
        return nil
    }),
)

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.