agents-go docs

An Agent is the persona: instructions, tools, optional per-agent models, and lifecycle hooks. It holds no live connection — one agent can be used across sessions, and a session can swap between agents.

Construction

func NewAgent(opts AgentOptions) (*Agent, error)
func MustNewAgent(opts AgentOptions) *Agent

AgentOptions

Field	Type	Notes
`Instructions`	`Instructions`	System/developer instructions (a `string` or `*llm.Instructions`).
`Tools`	`any`	`tool.Entry`, `[]tool.Entry`, a `Toolset`, or a `*tool.Context`.
`STT` / `VAD` / `LLM` / `TTS`	model interfaces	Per-agent overrides; used while this agent is active, else the session default.
`ChatContext`	`*llm.ChatContext`	Seeds the agent's private history.
`ID`	`string`	Stable identifier. Defaults to `"default_agent"`.

Hooks

OnEnter             func(context.Context, *AgentContext) error
OnExit              func(context.Context, *AgentContext) error
OnUserTurnCompleted func(context.Context, *AgentContext, *llm.ChatContext, *llm.ChatMessage) error

OnEnter / OnExit fire as the agent becomes / stops being active — the hooks a handoff runs. OnEnter is where an agent greets or drives the first turn.
OnUserTurnCompleted runs after a user turn commits, before generation — use it to inspect or augment context (e.g. RAG).

Advanced node overrides

For custom pipelines, AgentOptions exposes node overrides — LLMNode, STTNode, TTSNode, AlignedTTSNode, TranscriptionNode — plus ToolFiller/ToolFillerDelay (interstitial speech during long tool calls) and TranscriptTransforms (ordered transforms on eager transcription). Most agents don't need these.

Methods

func (a *Agent) UpdateInstructions(ctx context.Context, instructions Instructions) error
func (a *Agent) UpdateTools(ctx context.Context, tools any) error

Both update the live agent config and emit a config-update event. Use them to change instructions or the tool set at runtime.

Example

agent := agents.MustNewAgent(agents.AgentOptions{
    Instructions: "You are a friendly booking assistant.",
    Tools:        []tool.Entry{bookTable},
    LLM:          model, // optional per-agent override
    OnEnter: func(ctx context.Context, ac *agents.AgentContext) error {
        return nil // e.g. greet the caller
    },
})

Agent