agent

func New ¶

func New(cfg Config, opts ...Option) (Agent, error)

New is the one-call constructor: it absorbs the whole bootstrap a host used to hand-wire — persona resolution (with an evva fallback), EVVA.md / USER_PROFILE.md memory + skill auto-load, the permission store + mode, and the approval / question brokers — driven entirely by Config plus Options.

With no Options it builds a headless agent (the default brokers auto-deny any approval the model requests, so a request never parks a goroutine). Pass WithSink to surface approval + question events to an interactive UI (resolve them via Agent.RespondPermission / RespondQuestion) and WithRootContext so Ctrl-C reaches every background worker — that combination is all a ~40-line host needs for a full TUI with personas, permissions, /resume, and /compact.

Options are applied after the Config-derived wiring, so a host Option always wins on conflict (e.g. WithName, WithMaxIterations).

func NewWithProfile ¶

func NewWithProfile(profile Profile, opts ...Option) (Agent, error)

NewWithProfile is the flexible public constructor a downstream app uses to build an agent against its own profile and option set. Unlike New (which loads the bundled "evva" persona, memdir, and skill catalog) this constructor wires only what the caller supplies — no skill catalog, no memory snapshot, no agent registry by default.

Approval / question handling follows the agent's defaults. Pass agent.WithSink to surface approval + question events to an interactive UI (resolve them via Agent.RespondPermission / RespondQuestion), or agent.WithPermissionBroker to plug in a custom allow/deny policy. With neither, the agent auto-denies so an async request never parks the caller forever.

Example:

prof, _ := agent.NewProfile("custom", "you are helpful",
    []tools.ToolName{tools.READ_FILE, tools.BASH},
    "anthropic", constant.CLAUDE_SONNET_4_6,
    agent.ProfileOptions{})

ag, _ := agent.NewWithProfile(prof,
    agent.WithConfig(cfg),
    agent.WithSink(mySink),
    agent.WithMaxIterations(20),
)
resp, _ := ag.Run(ctx, "...")

package main

import (
	"context"
	"encoding/json"
	"fmt"
	"log/slog"
	"os"
	"path/filepath"

	"github.com/johnny1110/evva/pkg/agent"
	"github.com/johnny1110/evva/pkg/config"
	"github.com/johnny1110/evva/pkg/constant"
	"github.com/johnny1110/evva/pkg/event"
	"github.com/johnny1110/evva/pkg/llm"
	"github.com/johnny1110/evva/pkg/tools"
)

// exampleConfig loads a throwaway Config under /tmp so the example
// works without touching the user's real ~/.evva home.
func exampleConfig() *config.Config {
	tmp := filepath.Join(os.TempDir(), "evva-example-agent")
	cfg, _ := config.Load(config.LoadOptions{
		AppName: "example",
		AppHome: tmp,
		WorkDir: tmp,
	})
	return cfg
}

// echoLLM is a minimal stand-in for examples. Production callers
// import `_ "github.com/johnny1110/evva/pkg/llm/builtins"` to get
// Anthropic / DeepSeek / Ollama pre-registered instead.
type echoLLM struct{ model string }

func (e *echoLLM) Name() string             { return "echo" }
func (e *echoLLM) Model() string            { return e.model }
func (*echoLLM) SupportsDeferLoading() bool { return false }
func (e *echoLLM) Complete(_ context.Context, msgs []llm.Message, _ []tools.Tool) (llm.Response, error) {
	return llm.Response{Content: "echo: ok"}, nil
}
func (e *echoLLM) Stream(ctx context.Context, m []llm.Message, t []tools.Tool, _ llm.ChunkSink) (llm.Response, error) {
	return e.Complete(ctx, m, t)
}
func (*echoLLM) Apply(...llm.Option) {}

// examplePingTool answers any input with "pong". Demonstrates the public
// pkg/tools.Tool interface a downstream consumer satisfies.
type examplePingTool struct{}

func (examplePingTool) Name() string            { return "ping" }
func (examplePingTool) Description() string     { return "respond with pong" }
func (examplePingTool) Schema() json.RawMessage { return json.RawMessage(`{"type":"object"}`) }
func (examplePingTool) Execute(_ context.Context, _ *slog.Logger, _ json.RawMessage) (tools.Result, error) {
	return tools.Result{Content: "pong"}, nil
}

func main() {
	// 1. Register an echo provider for the example.
	if !llm.DefaultRegistry().Has("echo-example") {
		_ = llm.DefaultRegistry().Register("echo-example",
			func(_ llm.APIConfig, model string, _ ...llm.Option) (llm.Client, error) {
				return &echoLLM{model: model}, nil
			})
	}

	// 2. Build a config with credentials. Real apps use config.Load
	//    with their own AppName / AppHome; this example uses an inline
	//    Config so the example doesn't pollute the filesystem.
	cfg := exampleConfig()
	_ = cfg.SetProviderCredentials("echo-example", "http://example", "n/a")

	// 3. Build the Profile + Agent.
	prof, _ := agent.NewProfile("example", "you echo",
		nil, "echo-example", constant.Model("v0"), agent.ProfileOptions{})

	collected := []string{}
	sink := event.SinkFunc(func(e event.Event) {
		if e.Kind == event.KindText && e.Text != nil {
			collected = append(collected, e.Text.Text)
		}
	})

	ag, err := agent.NewWithProfile(prof,
		agent.WithConfig(cfg),
		agent.WithSink(sink),
		agent.WithMaxIterations(3),
		agent.WithHeadlessBypass(),
		agent.WithCustomTool("ping", func(tools.State) (tools.Tool, error) { return examplePingTool{}, nil }),
	)
	if err != nil {
		fmt.Println("construct error:", err)
		return
	}

	resp, _ := ag.Run(context.Background(), "hi")
	fmt.Println("final:", resp)
}

Output:
final: echo: ok

func LoadDiskAgents ¶

func LoadDiskAgents(evvaHome string) ([]AgentDefinition, []string)

LoadDiskAgents reads the on-disk personas under <evvaHome>/agents/ (no built-ins), returning each as a public AgentDefinition plus any load warnings. Useful for inspecting an agents directory before building a full registry.

func BuildAgentRegistry ¶

func BuildAgentRegistry(evvaHome string) (*AgentRegistry, []string)

BuildAgentRegistry assembles the runtime catalog: built-ins first, then on-disk personas under <evvaHome>/agents/. A disk persona that collides with a built-in name is skipped (built-ins win); the returned warnings describe any that failed to load. Never returns an error — a missing or malformed catalog degrades gracefully.

func NewAgentRegistry ¶

func NewAgentRegistry() *AgentRegistry

NewAgentRegistry returns an empty registry. Most callers want BuildAgentRegistry, which pre-populates the built-ins + on-disk personas.

func WithConfig ¶

func WithConfig(cfg *config.Config) Option

WithConfig installs the runtime configuration the agent reads from. Subagents inherit the parent's config; downstream apps that run multiple agents with different AppHome dirs pass distinct *config.Config pointers per agent.

Omitting WithConfig boots the agent against config.Get() — the historical singleton — so cmd/evva and existing callers don't need to change.

func WithCustomTool ¶

func WithCustomTool(name tools.ToolName, factory pubtoolset.ToolFactory) Option

WithCustomTool registers a downstream-authored tool on the pkg/toolset.DefaultRegistry and adds it to the agent's active list. The factory receives the agent's pkg/tools.State at build time so the tool can read Config() and Workdir().

Registration is idempotent across agents — calling WithCustomTool with the same name in two New calls registers the factory once and reuses it.

func WithHeadlessBypass ¶

func WithHeadlessBypass() Option

WithHeadlessBypass is the convenience option for downstream apps that run an agent without an interactive approval surface (no TUI overlay, no CLI prompt). It bundles WithPermissionMode(PermissionBypass) behind a more discoverable name + a strong docstring.

SECURITY: with bypass mode every tool call auto-succeeds. The agent will run any bash command the model emits, edit any file under its workdir, and fetch any URL it decides to. Use only in trusted environments (CI runners, sandboxed containers, ephemeral VMs).

For an interactive host that wants real prompts, omit this option — the default permission mode asks before each mutating call. Wire your UI's approval flow through agent.RespondPermission.

package main

import (
	"fmt"

	"github.com/johnny1110/evva/pkg/agent"
)

func main() {
	_ = agent.WithHeadlessBypass()
	fmt.Println("see godoc for security notes")
}

Output:
see godoc for security notes

func WithHookRegistry ¶

func WithHookRegistry(r *hooks.Registry) Option

WithHookRegistry installs the lifecycle-hook registry. Populate it with hooks.Load(workdir, appHome) to read from .evva/settings.json (project) and <appHome>/settings.json (user). nil is safe — the dispatcher noops when no registry is present. Shared across the root agent and every subagent so one settings.json load drives the whole agent tree.

func WithMaxIterations ¶

func WithMaxIterations(n int) Option

WithMaxIterations overrides the agent's loop cap. Pass 0 to keep the cfg-derived default. Values in (0, 2) are clamped to 2.

func WithMcpManager ¶

func WithMcpManager(m *mcp.Manager) Option

WithMcpManager installs a pre-built MCP connection manager, suppressing the one-call agent.New's auto-load. Build it with mcp.Load + mcp.Open and call mgr.RegisterFactories(toolset.DefaultRegistry()) before passing it here when you want a custom logger, OAuth prompt, or a manager shared across agents. Omit it to let New load + open the manager from settings.json (and wire the bundled ask_user_question OAuth flow) automatically. nil is safe — MCP tools and resources just have nothing to surface. Subagents inherit the parent's manager.

func WithName ¶

func WithName(name string) Option

WithName sets a human-readable label on the agent. Surfaced in logs and in subagent panels.

func WithPermissionBroker ¶

func WithPermissionBroker(b permission.Broker) Option

WithPermissionBroker installs a custom approval back-channel — the seam for a downstream allow/deny policy. Build one with permission.NewBroker() and register a callback via permission.SetOnRequest that inspects each permission.ApprovalRequest and calls Broker.Respond with a Decision.

Omit it and the agent installs a default broker: when a sink is present (WithSink) it emits an approval event for an interactive UI to resolve via Agent.RespondPermission; with no sink it auto-denies. One Broker is shared by the root agent and every subagent.

func WithPermissionMode ¶

func WithPermissionMode(m PermissionMode) Option

WithPermissionMode sets the agent's initial permission stance. Pass one of the typed PermissionMode constants — passing an unknown PermissionMode (e.g. PermissionMode("by-pass") with a typo) results in a no-op option, but that path is hard to reach: the constants are the only typed values exposed.

agent.WithPermissionMode(agent.PermissionBypass)

If your config layer hands you a string (YAML / CLI flag), convert at the boundary with PermissionMode(s).

func WithPermissionStore ¶

func WithPermissionStore(s *permission.Store) Option

WithPermissionStore installs the rule store the permission gate consults. Build one with permission.NewStore() (empty) or permission.Load(workdir, home) to read project + user rules from disk. One Store is shared by the root agent and every subagent it spawns.

Omit it to run with no pre-seeded rules — the active permission mode's safelist still governs which calls auto-allow, ask, or deny.

func WithPersona ¶

func WithPersona(name string) Option

WithPersona records the active persona's wire name (e.g. "nono") so Agent.ProfileName and the UI render the right label. Pair it with an initial Profile from ResolveMainProfile for that same name.

func WithPersonaRegistry ¶

func WithPersonaRegistry(r *AgentRegistry) Option

WithPersonaRegistry installs the persona catalog the agent resolves through: the /profile picker (Agent.ListMainProfiles / SwitchProfile) and the Agent tool's subagent kinds. Build one with BuildAgentRegistry (built-ins + disk) and Register your own personas before passing it here. A nil registry leaves the agent with only the built-in "evva".

func WithRootContext ¶

func WithRootContext(ctx context.Context) Option

WithRootContext installs the agent-lifetime context. The signal pump goroutine, background bash tasks, and Monitor goroutines all bind to this ctx, so cancelling it (or calling Agent.Shutdown) cleans up every detached worker the agent ever spawned.

Pass the host's session-level cancellable ctx (e.g. signal.NotifyContext) so Ctrl-C reaches every long-lived goroutine.

func WithSink ¶

func WithSink(s event.Sink) Option

WithSink installs the event consumer the agent emits into. nil sinks become event.Discard at emit time; pass event.Multi{...} to fan out to several consumers (e.g. a TUI plus a JSON-over-stdout bridge).

func WithSkillRegistry ¶

func WithSkillRegistry(r *skill.Registry) Option

WithSkillRegistry installs a pre-built skill catalog on the agent's ToolState. The SKILL tool reads through it at Execute time, and the agent's system prompt advertises every registered skill on the available-skills list.

When omitted, agent.New auto-loads from cfg.AppHomeSkillsDir and cfg.WorkDirSkillsDir — the same disk path cmd/evva uses. Pass an override for either of:

1. Programmatic-only catalogs: build with skill.NewRegistry() + Add(...) to ship skills inside the binary via go:embed, fetch them at boot, or generate them on the fly.
2. Mixed catalogs: start from skill.LoadRegistry(home, workdir) and Add programmatic extras alongside.
3. Suppression: pass skill.NewRegistry() to disable disk auto-load when the host wants the SKILL tool to surface no skills at all.

func WithStream ¶

func WithStream(stream bool) Option

WithStream toggles streaming completions. Overrides the Profile.Stream field; useful for tests and downstream apps that want to force the buffered or chunked path without rebuilding the profile.

func NewProfile ¶

func NewProfile(name, systemPrompt string, activeTools []tools.ToolName, providerName string, model constant.Model, opts ProfileOptions) (Profile, error)

NewProfile builds a Profile a downstream app can pass into NewWithProfile. The system prompt is wrapped into an llm.WithSystem option automatically.

providerName must match a name registered on pkg/llm.DefaultRegistry ("anthropic", "deepseek", "ollama", or a downstream-registered name). model is the typed constant.Model id sent to the provider; for downstream-registered providers whose model strings aren't in pkg/constant, write `constant.Model("custom-model-name")`. Empty is allowed but downstream factories typically expect a concrete id.

The profile is classified as GENERAL_PURPOSE — evva's internal type system reserves MAIN/EXPLORE/PLAN for the bundled personas. Downstream apps that want richer behavior (memory injection, skills, plan-mode) should ship an on-disk agent definition under <AppHome>/agents/ instead of constructing a Profile in code.

providerName does not need to be in pkg/constant.GetAllProviders() — downstream apps register their own provider via pkg/llm.DefaultRegistry().Register and pass the same name here. When the name isn't in the bundled constants, an LLMProvider stub is synthesised on the fly so the rest of the agent loop has a value to log + introspect.

package main

import (
	"fmt"

	"github.com/johnny1110/evva/pkg/agent"
	"github.com/johnny1110/evva/pkg/constant"
	"github.com/johnny1110/evva/pkg/tools"
)

func main() {
	prof, _ := agent.NewProfile(
		"my-agent",
		"You are a brisk assistant.",
		[]tools.ToolName{tools.READ_FILE, tools.BASH},
		"deepseek",
		constant.DEEPSEEK_V4_PRO,
		agent.ProfileOptions{},
	)
	fmt.Println("prompt:", prof.SystemPrompt)
	fmt.Println("provider:", prof.LLMProvider.Name)
	fmt.Println("model:", string(prof.LLMModel))
}

Output:
prompt: You are a brisk assistant.
provider: deepseek
model: deepseek-v4-pro

func ResolveMainProfile ¶

func ResolveMainProfile(cfg *config.Config, reg *AgentRegistry, name string, opts ...llm.Option) (Profile, []string, error)

ResolveMainProfile builds the initial Profile for a main-tier persona by name, ready to pass to NewWithProfile. It auto-loads the skill catalog and the EVVA.md / USER_PROFILE.md memory snapshot from cfg, so a host never touches the internal memory or skills packages.

reg is the persona catalog (from BuildAgentRegistry, with any Register'd personas); a nil registry resolves only the built-in "evva". An empty name defaults to "evva". The returned warnings are non-fatal memory-load notes (oversize / unreadable files); an unknown or non-main persona name returns an error.

Typical use:

reg, _ := agent.BuildAgentRegistry(cfg.AppHome)
reg.Register(myPersona)
prof, _, err := agent.ResolveMainProfile(cfg, reg, "nono")
ag, _ := agent.NewWithProfile(prof,
    agent.WithConfig(cfg),
    agent.WithPersonaRegistry(reg),
    agent.WithPersona("nono"),
    agent.WithSink(myUI),
)