Library Embedding

---
name: library-embedding
description: Walk a Go developer through embedding core-agent in their own binary. Use when the user asks "how do I embed core-agent", "use core-agent as a library", "build my own agent on core-agent", "agent.New", "custom prompter", "custom tools", "custom provider", "HTTP-served agent", "integrate core-agent into [Go project]", or asks any question implying they want to use the Go API rather than the bundled CLI.
---

When invoked:

1. **Confirm the use case.** Embedding fits when:
   - You're building a domain-specific agent (web service, custom UI, IDE plugin)
   - You need extension points the CLI doesn't expose (custom prompter, custom tools, custom provider)
   - You're wrapping `core-agent` in a larger system (orchestrator, agent platform)

   If the user just wants to customize `core-agent`'s behavior for their project, the CLI + skills covers it without embedding. Walk them to the `cli-setup` skill instead.

2. **Start with the minimal embed.** Show the 20-line "hello world" — `agent.New` + `Run` + iterate events. Most embedding work builds on this base. Use `references/minimal-embed.md`.

3. **Identify the extension point they need.** Most embedding use cases come down to one of:
   - Custom **Prompter** — different approval UX (web modal, Slack button, IDE dialog)
   - Custom **tool** — domain operations the built-in nine don't cover
   - Custom **Provider** — LLM backend not in the box (local Ollama, internal model server)
   - Custom **session.Service** — persistence beyond eventlog (Redis, custom DB)
   - **`RemoteAgentSpawner`** — delegate background subagents to K8s Jobs, Cloud Run, etc.

   Fetch `references/extension-points.md` to walk them through the relevant one.

4. **Show a full worked example.** For non-trivial embeddings (web service, HTTP-served agent), build out a complete program. Use `references/http-served-agent.md` for the canonical example.

5. **Discuss long-term maintenance.** `core-agent` is pre-1.0; breaking changes can land at any minor version. If the user is shipping production code on top of it:
   - Pin the dep version in `go.mod`
   - Subscribe to releases / `CHANGELOG.md`
   - Use the documented `agent.Option` interface — not internal/private symbols

## Triggers in detail

Beyond the description, also match on:

- "How do I add a custom tool to core-agent"
- "Build an HTTP-served agent"
- "Background workers with core-agent"
- "Integrate core-agent into my existing Go service"
- "Customize the approval UX for a web app"
- "Bring my own LLM backend"
- "Programmatic control of an agent run"

## References

Fetch based on what the user is building:

- **`references/minimal-embed.md`** — the smallest working `agent.New` + `Run` loop. Read first for any embedding question; it's the foundation.
- **`references/extension-points.md`** — the seven main customization surfaces (`WithTools`, `WithPrompter`, `WithProvider`, `WithSessionService`, `WithCompactor`, `WithCheckpointer`, `RemoteAgentSpawner`) with one paragraph per. Read when narrowing in on the user's specific extension need.
- **`references/http-served-agent.md`** — full worked HTTP-served agent example. Read when the user is building a web-facing service; covers session-per-request vs persistent-session shapes, prompter integration, streaming responses.

## Procedure: minimal embed

Walk the user through this skeleton first. Everything else is variations on it:

```go
package main

import (
    "context"
    "fmt"
    "log"
    "os"

    "github.com/go-steer/core-agent/v2/pkg/agent"
    "github.com/go-steer/core-agent/v2/pkg/models"
    _ "github.com/go-steer/core-agent/v2/pkg/models/gemini"
)

func main() {
    ctx := context.Background()
    provider, err := models.Resolve(nil) // reads .agents/config.json
    if err != nil { log.Fatal(err) }
    model, err := provider.Model(ctx, "gemini-3.7-flash")
    if err != nil { log.Fatal(err) }

    a, err := agent.New(model)
    if err != nil { log.Fatal(err) }

    prompt := os.Args[1]
    for ev, err := range a.Run(ctx, prompt) {
        if err != nil { log.Fatal(err) }
        if ev.Content != nil {
            for _, p := range ev.Content.Parts {
                if p.Text != "" {
                    fmt.Print(p.Text)
                }
            }
        }
    }
    fmt.Println()
}
```

That's it. Multi-turn conversation: call `a.Run(ctx, prompt)` again with a new prompt — session history is preserved automatically. Run-to-completion (no streaming): use `runner.Headless` instead.

## Procedure: pick extension points

Walk the user through what they're customizing:

| Want | Extension | Reference |
|---|---|---|
| Different approval UX | `WithPrompter(impl)` | `references/extension-points.md` § Prompter |
| Domain-specific tool | `WithTools([]tool.Tool{...})` | `references/extension-points.md` § Tools |
| LLM backend not in box | Implement `models.Provider`, register with `models.Register` | `references/extension-points.md` § Provider |
| Custom persistence | `WithSessionService(impl)` | `references/extension-points.md` § Session |
| Long-session survival | `WithCompactor(...)` + `WithCheckpointer(...)` | (built-in defaults usually fine) |
| Distributed subagent execution | Implement `background.RemoteAgentSpawner` | `references/extension-points.md` § Remote subagents |
| HTTP-served agent | All of the above + handler shape | `references/http-served-agent.md` |

For each one, fetch the relevant section and walk through the implementation contract + a minimal example.

## Procedure: structured persistence

If the user is building anything beyond a one-shot CLI, push them toward durable sessions early:

```go
import "github.com/go-steer/core-agent/v2/pkg/eventlog"
import "github.com/glebarez/sqlite"

handle, err := eventlog.Open(ctx, sqlite.Open("./sessions.db"))
if err != nil { log.Fatal(err) }
defer handle.Close()

a, err := agent.New(model,
    agent.WithSessionService(handle.Service),
    agent.WithEventLog(handle),
)
```

Now every turn, every tool call, every model response lands in `sessions.db`. Crash-resume, audit log, replay, live tail — all unlocked.

## Procedure: composition with autonomous + subagents

If the embedded agent is itself autonomous OR spawns subagents, use `RunAutonomous` + `background.Manager`:

```go
import "github.com/go-steer/core-agent/v2/pkg/agent"

bgMgr, err := agent.NewBackgroundAgentManager(
    agent.WithBackgroundProvider(provider, "gemini-2.5-flash"),
    agent.WithBackgroundGate(gate),
    agent.WithBackgroundCatalog(builtinTools),
)
if err != nil { log.Fatal(err) }
defer bgMgr.Close()

a, err := agent.New(model,
    agent.WithBackgroundManager(bgMgr),
    agent.WithTools(append(builtinTools, agent.NewBackgroundSpawnTools(bgMgr)...)),
)
```

The parent now has `spawn_agent` and `stop_agent` (subagent results are pushed back via the `[Background reports]` block; `spawn_agent { wait: true }` blocks inline). The user's `AGENTS.md` (or in-prompt instruction) governs when to use them.

## When NOT to use this skill

- The user is using the **bundled CLI** (`core-agent` binary) and asking about configuration. Use `cli-setup` skill.
- The user is configuring **autonomous / unattended runs** of the bundled CLI. Use `autonomous-setup` skill.
- The user is asking a reference question (function signature, type definition). Answer directly from [library/api]({{< relref "library/api.md" >}}) docs; no need to walk the whole embedding procedure.
- The user wants to **modify `core-agent` itself** (contribute upstream changes). That's a different conversation; point them at `CONTRIBUTING.md`.

## Output style

Code-heavy but with clear narrative. Embedding work is mostly Go — show the code, explain what each block does. Don't generate a wall of code without explanation; the user is going to maintain it.

For non-trivial embeddings, propose a project layout (`cmd/`, `internal/`, etc.) before writing code. Give the user a sense of where things go so the snippets fit into context.

When showing extension points, ALWAYS include the interface contract being satisfied. E.g., "you need to implement `permissions.Prompter` which is `interface { AskApproval(ctx, req) (Decision, error) }`" — not just "implement a prompter."