agent

func New ¶

func New(cfg Config) (Agent, error)

New constructs an Agent ready to call Run. When cfg.AppConfig is nil it loads the process-wide default (config.Get(), which initializes via LoadDefault on first use); pass an explicit *config.Config to target a custom AppHome.

Set API keys via the <app>-config.yml file under cfg.AppHome (or env vars consumed by your own loader for downstream apps).

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 Main persona, memdir, and a non-interactive permission stub) this constructor wires only what the caller supplies — no skill catalog, no memory snapshot, no agent registry by default.

A non-interactive permission broker + question broker are installed internally so async approval / question requests don't park the caller forever; pass agent_impl.WithPermissionBroker / WithQuestionBroker via the variadic opts list to override.

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 (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 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 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 WithName ¶

func WithName(name string) Option

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

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