64 lines
2.9 KiB
Go
64 lines
2.9 KiB
Go
// Package agent is the public, embeddable SDK for driving a pigo agent from
|
|
// your own Go program. It wraps pigo's internal run-assembly, provider, and
|
|
// agent-loop packages behind a small surface whose every exported type is a Go
|
|
// primitive (string, []string, bool, func) — so importing this package never
|
|
// pulls an internal type into your code, and pigo can evolve its internals
|
|
// without breaking you.
|
|
//
|
|
// # Quick start
|
|
//
|
|
// sess, err := agent.New(
|
|
// agent.WithModel("claude-opus-4-8"),
|
|
// agent.WithAPIKey(os.Getenv("ANTHROPIC_API_KEY")),
|
|
// )
|
|
// if err != nil {
|
|
// log.Fatal(err)
|
|
// }
|
|
// defer sess.Close()
|
|
//
|
|
// reply, err := sess.Prompt(context.Background(), "Say hello in one word.")
|
|
// fmt.Println(reply)
|
|
//
|
|
// # Model, provider, credentials
|
|
//
|
|
// The model id selects the provider the same way the pigo CLI does:
|
|
// "claude-opus-4-8" resolves to Anthropic, "openrouter/free" to OpenRouter,
|
|
// and so on. Point at any OpenAI- or Anthropic-compatible endpoint with
|
|
// [WithBaseURL] + [WithProtocol], or a named provider from your config with
|
|
// [WithProvider]. The API key comes from [WithAPIKey] or, if unset, the
|
|
// provider's usual environment variable (e.g. ANTHROPIC_API_KEY). Keys are
|
|
// never logged.
|
|
//
|
|
// # Tools run automatically — read this
|
|
//
|
|
// By default a session is created with pigo's full built-in tool set (read,
|
|
// write, edit, bash, find, grep, and more) and those tools are executed WITHOUT
|
|
// any per-call confirmation prompt — equivalent to running the CLI with
|
|
// --approve. An agent can therefore read, modify, and delete files under its
|
|
// working directory and run shell commands on the host. This is the right
|
|
// default for an automated SDK, but it means you should only send prompts you
|
|
// trust, and run in a directory (and, ideally, a sandbox) you are willing to let
|
|
// the agent modify. To constrain or remove that capability use [WithTools] (an
|
|
// allowlist), [WithDisallowedTools] (a denylist, which always wins), or
|
|
// [WithoutTools] (a pure text completion with no tools at all).
|
|
//
|
|
// # Conversation state
|
|
//
|
|
// A [Session] keeps the running conversation: each [Session.Prompt] or
|
|
// [Session.Stream] call appends to the same history, so follow-up prompts see
|
|
// what came before. Call [Session.Reset] to start a fresh conversation on the
|
|
// same session, or [Session.Close] when you are done. A Session is NOT safe for
|
|
// concurrent use — drive it from one goroutine, or create one Session per
|
|
// goroutine.
|
|
//
|
|
// # Defaults
|
|
//
|
|
// - Tools: on (full built-in set, auto-executed; see the safety note above).
|
|
// - Skills: off — enable discovery of on-disk skills with [WithSkills].
|
|
// - Memory: off — enable the persistent memory store with [WithMemory].
|
|
// - Thinking: "medium" — override with [WithThinkingLevel].
|
|
//
|
|
// Skills and memory are off by default so an embedded session is hermetic: it
|
|
// does not read or write the machine's shared pigo state unless you ask it to.
|
|
package agent
|