agent

Documentation

Overview

Package agent defines Agent, Mode, and HandoffTool for the fino Agent SDK. An Agent is a model-agnostic behavior configuration; Mode defines a runnable persona with instructions, tools, and model options.

Example

package main

import (
	"context"
	"fmt"
	"iter"

	"github.com/nethinwei/fino/agent"
	"github.com/nethinwei/fino/message"
	"github.com/nethinwei/fino/model"
	"github.com/nethinwei/fino/runner"
	"github.com/nethinwei/fino/tool"
)

type staticModel struct{}

func (staticModel) Generate(ctx context.Context, messages []message.Message, tools []tool.Info, opts ...model.Option) (*message.Message, error) {
	msg := message.Assistant(message.NewText("hello"))
	return &msg, nil
}

func (staticModel) Stream(ctx context.Context, messages []message.Message, tools []tool.Info, opts ...model.Option) iter.Seq2[model.Event, error] {
	return func(yield func(model.Event, error) bool) {}
}

func main() {
	mode, _ := agent.NewMode("default", "Be helpful.")
	a, _ := agent.New("assistant", agent.WithMode(mode), agent.WithDefaultMode("default"))
	r, _ := runner.New(staticModel{})
	result, _ := r.Run(context.Background(), a, runner.Text("hi"))
	fmt.Println(result.Text())
}

Output:
hello

Index

• func NewHandoffTool(target *Agent) (tool.Tool, error)
• type Agent
  • func New(name string, opts ...AgentOption) (*Agent, error)
  • func (a *Agent) DefaultMode() string
  • func (a *Agent) Mode(name string) (Mode, bool)
  • func (a *Agent) Name() string
• type AgentOption
  • func WithDefaultMode(name string) AgentOption
  • func WithMode(mode Mode) AgentOption
• type HandoffTool
• type Mode
  • func NewMode(name, instructions string, opts ...ModeOption) (Mode, error)
• type ModeOption
  • func WithMetadata(key string, value any) ModeOption
  • func WithModelOptions(opts ...model.Option) ModeOption
  • func WithTools(tools ...tool.Tool) ModeOption

Examples

• Package

Functions

func NewHandoffTool

func NewHandoffTool(target *Agent) (tool.Tool, error)

NewHandoffTool creates a tool that signals a transfer to the target Agent. The returned Tool also satisfies the HandoffTool interface, which Runner uses to detect and execute the handoff.

Types

type Agent

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

Agent is a model-agnostic behavior configuration. It groups one or more Modes and delegates execution to the Runner.

func New

func New(name string, opts ...AgentOption) (*Agent, error)

New creates an Agent with the given name and options. It validates that the name is non-empty, at least one mode is provided, mode names are unique, and the default mode exists.

func (*Agent) DefaultMode

func (a *Agent) DefaultMode() string

DefaultMode returns the name of the Agent's default mode.

func (*Agent) Mode

func (a *Agent) Mode(name string) (Mode, bool)

Mode returns the Mode with the given name. The second return value reports whether the mode exists.

func (*Agent) Name

func (a *Agent) Name() string

Name returns the Agent's name.

type AgentOption

type AgentOption func(*Agent)

AgentOption configures an Agent.

func WithDefaultMode

func WithDefaultMode(name string) AgentOption

WithDefaultMode sets the default mode name for the Agent.

func WithMode

func WithMode(mode Mode) AgentOption

WithMode adds a Mode to the Agent.

type HandoffTool

type HandoffTool interface {
	tool.Tool
	// TargetAgent returns the Agent to transfer control to.
	TargetAgent() *Agent
}

HandoffTool is a Tool that signals an Agent transfer. Runner detects handoffs by type-asserting tools to this interface.

type Mode

type Mode struct {
	Name         string
	Instructions string
	Tools        []tool.Tool
	ModelOptions []model.Option
	Metadata     map[string]any
}

Mode is a runnable persona: a set of instructions, tools, and optional model options. Modes are selected at run time rather than by modifying Agent state.

func NewMode

func NewMode(name, instructions string, opts ...ModeOption) (Mode, error)

NewMode creates a Mode with the given name and instructions. It validates that the name is non-empty, no tool is nil, and tool names are unique within the mode.

type ModeOption

type ModeOption func(*Mode)

ModeOption configures a Mode.

func WithMetadata

func WithMetadata(key string, value any) ModeOption

WithMetadata attaches a key-value pair to the mode's metadata.

func WithModelOptions

func WithModelOptions(opts ...model.Option) ModeOption

WithModelOptions sets default model options for the mode. These are applied before any per-run overrides.

func WithTools

func WithTools(tools ...tool.Tool) ModeOption

WithTools adds tools to the mode.