embeddedchat

Documentation

Overview

Package embeddedchat provides a small headless chat wrapper around the docker-agent runtime for embedders that want to drive an agent from their own UI instead of running docker-agent's Bubble Tea application.

Index

• Variables
• type Config
• type Event
  • func TranslateRuntimeEvent(event dagentruntime.Event) (Event, bool)
• type Session
  • func New(ctx context.Context, cfg Config) (*Session, error)
  • func (s *Session) Close() error
  • func (s *Session) Confirm(ctx context.Context, req dagentruntime.ResumeRequest) error
  • func (s *Session) Conversation() *session.Session
  • func (s *Session) Restart() error
  • func (s *Session) Runtime() dagentruntime.Runtime
  • func (s *Session) Send(ctx context.Context, prompt string) (<-chan Event, error)
  • func (s *Session) WelcomeMessage() string
• type ToolActivity

Variables

var (
	// ErrAgentSourceRequired is returned when New is called without an agent
	// source or a pre-built team.
	ErrAgentSourceRequired = errors.New("embeddedchat: an agent source or a team is required")
	// ErrRegistriesRequired is returned when an AgentSource is loaded without
	// load options: the loader needs toolset and provider registries. Pass
	// embeddedchat/defaults.Opts() for docker-agent's full registries, or
	// your own via LoadOpts.
	ErrRegistriesRequired = errors.New("embeddedchat: LoadOpts is required with AgentSource (e.g. embeddedchat/defaults.Opts())")
	// ErrNotInitialized is returned when a Session has no runtime or conversation.
	ErrNotInitialized = errors.New("embeddedchat: session is not initialized")
	// ErrRunActive is returned when Send is called while a previous run is still active.
	ErrRunActive = errors.New("embeddedchat: a run is already active")
	// ErrClosed is returned when an operation is attempted after Close.
	ErrClosed = errors.New("embeddedchat: session is closed")
)

Types

type Config

type Config struct {
	// Team is a pre-built team. Embedders that assemble their agents in code
	// use it instead of AgentSource: no YAML loading happens, and — the point
	// — docker-agent's full toolset and provider registries are never linked
	// into their binary. Takes precedence over AgentSource.
	Team *team.Team
	// AgentSource is the agent/team definition to load. Bytes sources are a
	// good fit for embedders that ship a pinned agent in their binary.
	// Requires LoadOpts (see ErrRegistriesRequired).
	AgentSource dagentcfg.Source
	// RuntimeConfig is passed to the team loader. When nil, a zero runtime
	// config is used.
	RuntimeConfig *dagentcfg.RuntimeConfig
	// LoadOpts configures the team loader for the AgentSource path, most
	// importantly the toolset and provider registries.
	// embeddedchat/defaults.Opts() provides docker-agent's full registries.
	LoadOpts []teamloader.Opt
	// ToolsetRegistry resolves toolsets declared by AgentSource; appended to
	// LoadOpts as a convenience.
	ToolsetRegistry teamloader.ToolsetRegistry
	// RuntimeOptions are appended when constructing the runtime.
	RuntimeOptions []dagentruntime.Opt
	// SessionOptions are appended when constructing each conversation session.
	SessionOptions []session.Opt
	// InitialSession, when set, is used as the first conversation instead of
	// a fresh one — e.g. a conversation restored from a session store.
	// Restart still replaces it with a fresh session.
	InitialSession *session.Session
	// EventBuffer controls the size of the channel returned by Send. When zero,
	// a small default buffer is used.
	EventBuffer int
}

Config describes an embedded agent session.

type Event

type Event struct {
	// Text is an assistant text delta.
	Text string
	// Tool describes a tool call starting, awaiting confirmation, or finishing.
	Tool *ToolActivity
	// Err is a user-facing runtime error.
	Err error
	// Done marks a clean end of the reply stream.
	Done bool
	// RuntimeEvent is the original docker-agent runtime event for projected
	// events. Not every runtime event is forwarded by this compact API; callers
	// that need the full raw stream can use Runtime().RunStream directly.
	RuntimeEvent dagentruntime.Event
}

Event is the UI-friendly form of one runtime stream event.

func TranslateRuntimeEvent

func TranslateRuntimeEvent(event dagentruntime.Event) (Event, bool)

TranslateRuntimeEvent translates content-bearing runtime events into the compact Event shape used by embedded chat UIs.

type Session

type Session struct {
	// contains filtered or unexported fields
}

Session owns one embedded runtime and one mutable conversation session.

func New

func New(ctx context.Context, cfg Config) (*Session, error)

New builds the runtime for the configured team (or loads AgentSource) and creates the first conversation session.

func (*Session) Close

func (s *Session) Close() error

Close cancels any active run and releases runtime resources.

func (*Session) Confirm

func (s *Session) Confirm(ctx context.Context, req dagentruntime.ResumeRequest) error

Confirm answers the pending tool confirmation, if any.

func (*Session) Conversation

func (s *Session) Conversation() *session.Session

Conversation returns the underlying docker-agent session.

The returned pointer is mutable and may be replaced by Restart. Callers that mutate it directly are responsible for coordinating with Send/Restart.

func (*Session) Restart

func (s *Session) Restart() error

Restart cancels any active run and replaces the conversation with a fresh session, preserving the runtime and loaded agent.

func (*Session) Runtime

func (s *Session) Runtime() dagentruntime.Runtime

Runtime returns the underlying docker-agent runtime for advanced embedders. It returns nil only for sessions not created by New.

func (*Session) Send

func (s *Session) Send(ctx context.Context, prompt string) (<-chan Event, error)

Send appends prompt to the conversation and streams the assistant reply. The returned channel closes when the runtime stream stops. A clean stream emits a final Done event first; a stream that reports an ErrorEvent emits one Err event, suppresses later projected events, then keeps draining until the runtime stops. If ctx is cancelled, Send drains the runtime stream until it stops, but no further events are delivered to the caller.

func (*Session) WelcomeMessage

func (s *Session) WelcomeMessage() string

WelcomeMessage returns the loaded agent's welcome message.

type ToolActivity

type ToolActivity struct {
	Call tools.ToolCall
	Def  tools.Tool
	// Output is an incremental output line streamed by the running call
	// (empty for lifecycle events).
	Output   string
	Finished bool
	IsError  bool
	// Response is the finished call's textual result.
	Response string
	// Result is the finished call's structured result (nil when unavailable).
	Result *tools.ToolCallResult
	// NeedsConfirmation is true when the runtime is blocked until Confirm is
	// called with the user's decision.
	NeedsConfirmation bool
}

ToolActivity describes one tool call surfaced by the runtime.