agents

Documentation

Index

• Constants
• Variables
• func ExtractHitlPayload(s string) (json.RawMessage, bool)
• func StripHitlMarkers(s string) string
• func TryHitlMarker(assistantText string) (tools.TUIInputInput, bool)
• type Agent
  • func New(p ai.Provider, name string, model string, maxOutputTokens int64, system string, ...) *Agent
  • func NewFromFile(filename string, variables map[string]any) (*Agent, error)
  • func NewFromToml(tomlstr string, variables map[string]any) (*Agent, error)
  • func (a *Agent) AddTool(tool tools.Tool)
  • func (a *Agent) ExecTool(id string, name string, msg json.RawMessage, onData func(data string)) ai.ToolResultPart
  • func (a *Agent) GetPrompt() string
  • func (a *Agent) GetSkillDescriptions() string
  • func (a *Agent) GetSubAgentDescriptions() string
  • func (a *Agent) LoadSkills(dir string) error
  • func (a *Agent) Loop(maxTurns int, resetHistory bool)
  • func (a *Agent) Post(ctx context.Context, msgs *[]ai.ModelMessage) (*ai.GenOut, error)
  • func (a *Agent) PostStreaming(ctx context.Context, msgs *[]ai.ModelMessage, onTextDelta func(delta string)) (*ai.GenOut, error)
  • func (a *Agent) RunLoop(ctx context.Context, opts LoopOptions) (*LoopResult, error)
  • func (a *Agent) SetCompactor(c Compactor)
• type AgentConfig
• type AgentLoader
  • func NewAgentLoader(dir string, vars map[string]any) *AgentLoader
  • func (l *AgentLoader) Load() error
• type AutoCompactConfig
• type CompactConfig
• type Compactor
• type DefaultCompactor
  • func NewDefaultCompactor(cfg CompactConfig) *DefaultCompactor
  • func (c *DefaultCompactor) BeforeModelCall(ctx context.Context, a *Agent, history *[]ai.ModelMessage) error
  • func (c *DefaultCompactor) CompactToolResult(_ *Agent, tr ai.ToolResultPart) ai.ToolResultPart
• type LoopOptions
• type LoopResult
• type MicroCompactConfig

Constants

const (
	KeySubAgentDescriptions = "agent_descriptions"
	KeySkillDescriptions    = "skill_descriptions"
)

const HitlMarkerExample = `<hitl>{"type":"confirm","question":"是否继续？"}</hitl>`

HitlMarkerExample 写入系统提示时可引用，说明文本兜底格式。

Variables

var (
	Logger *slog.Logger = slog.Default()
)

Functions

func ExtractHitlPayload

func ExtractHitlPayload(s string) (json.RawMessage, bool)

ExtractHitlPayload 从助手文本中取出第一个 <hitl> 与 </hitl> 之间的 JSON（与 tui_input 载荷同形）。

func StripHitlMarkers

func StripHitlMarkers(s string) string

StripHitlMarkers 移除文本中所有 <hitl>...</hitl> 块（用于历史与界面展示）。

func TryHitlMarker

func TryHitlMarker(assistantText string) (tools.TUIInputInput, bool)

TryHitlMarker 解析首个 hitl JSON 并校验是否与 tui_input 载荷一致。

Types

type Agent

type Agent struct {
	Name   string
	Config AgentConfig

	Compactor         Compactor
	ModelContextSize  int64
	ContextUsage      int64
	ContextUsageRatio float64
	ContextRemaining  int64
	TotalInputTokens  int64
	TotalOutputTokens int64

	SkillLoader *skills.Loader
	SubAgents   map[string]*Agent
	// contains filtered or unexported fields
}

func New

func New(p ai.Provider, name string, model string, maxOutputTokens int64, system string, toolList []tools.Tool) *Agent

func NewFromFile

func NewFromFile(filename string, variables map[string]any) (*Agent, error)

NewFromFile 从 agx 风格 Markdown（YAML front matter + 可选正文作 prompt 模板）加载 Agent，语义与 NewFromToml 相同。

func NewFromToml

func NewFromToml(tomlstr string, variables map[string]any) (*Agent, error)

func (*Agent) AddTool

func (a *Agent) AddTool(tool tools.Tool)

func (*Agent) ExecTool

func (a *Agent) ExecTool(id string, name string, msg json.RawMessage, onData func(data string)) ai.ToolResultPart

func (*Agent) GetPrompt

func (a *Agent) GetPrompt() string

func (*Agent) GetSkillDescriptions

func (a *Agent) GetSkillDescriptions() string

func (*Agent) GetSubAgentDescriptions

func (a *Agent) GetSubAgentDescriptions() string

func (*Agent) LoadSkills

func (a *Agent) LoadSkills(dir string) error

func (*Agent) Loop

func (a *Agent) Loop(maxTurns int, resetHistory bool)

func (*Agent) Post

func (a *Agent) Post(ctx context.Context, msgs *[]ai.ModelMessage) (*ai.GenOut, error)

Post 非流式调用底层 ai.Provider.Generate。

func (*Agent) PostStreaming

func (a *Agent) PostStreaming(
	ctx context.Context,
	msgs *[]ai.ModelMessage,
	onTextDelta func(delta string),
) (*ai.GenOut, error)

PostStreaming 使用 ai.Provider.Stream；在收到文本增量时回调 onTextDelta，返回聚合后的 ai.GenOut（与非流式语义一致，便于处理 tool_calls）。

func (*Agent) RunLoop

func (a *Agent) RunLoop(ctx context.Context, opts LoopOptions) (*LoopResult, error)

func (*Agent) SetCompactor

func (a *Agent) SetCompactor(c Compactor)

type AgentConfig

type AgentConfig struct {
	Model           string
	MaxOutputTokens int64
	Prompt          string
	SkillDir        string
}

type AgentLoader

type AgentLoader struct {
	Dir    string
	Vars   map[string]any
	Agents map[string]*Agent
}

func NewAgentLoader

func NewAgentLoader(dir string, vars map[string]any) *AgentLoader

func (*AgentLoader) Load

func (l *AgentLoader) Load() error

Load 扫描 Dir 下每个 *.md，用 NewFromFile 加载；注册键为文件名去掉扩展名（如 main.md -> main）。

type AutoCompactConfig

type AutoCompactConfig struct {
	Enabled             bool
	TriggerUsageRatio   float64
	TriggerRemainTokens int64
	MinHistoryMessages  int
	KeepRecentMessages  int
	CooldownTurns       int
	SummaryMaxTokens    int64
	DumpDir             string
	DumpFilename        string
}

type CompactConfig

type CompactConfig struct {
	Micro MicroCompactConfig
	Auto  AutoCompactConfig
}

type Compactor

type Compactor interface {
	BeforeModelCall(ctx context.Context, a *Agent, history *[]ai.ModelMessage) error
	CompactToolResult(a *Agent, tr ai.ToolResultPart) ai.ToolResultPart
}

type DefaultCompactor

type DefaultCompactor struct {
	Config CompactConfig
	// contains filtered or unexported fields
}

func NewDefaultCompactor

func NewDefaultCompactor(cfg CompactConfig) *DefaultCompactor

func (*DefaultCompactor) BeforeModelCall

func (c *DefaultCompactor) BeforeModelCall(ctx context.Context, a *Agent, history *[]ai.ModelMessage) error

func (*DefaultCompactor) CompactToolResult

func (c *DefaultCompactor) CompactToolResult(_ *Agent, tr ai.ToolResultPart) ai.ToolResultPart

type LoopOptions

type LoopOptions struct {
	// ResetHistory 清空会话历史后再执行本轮 loop。
	ResetHistory bool
	// MaxTurns 最大模型往返轮次（assistant 生成一次计一轮）；<=0 时使用默认值。
	MaxTurns int
	// MaxToolCalls 最大工具调用次数；<=0 表示不限制。
	MaxToolCalls int
	// MaxToolResultChars 对每个工具结果做截断，避免上下文膨胀；<=0 表示不截断。
	MaxToolResultChars int
	// Input 可选的起始输入消息，会在执行前 append 到 history。
	Input *ai.ModelMessage
	// History 可选的外部会话历史；为空时使用 Agent 内部 history。
	History *[]ai.ModelMessage
	// OnTextDelta 流式文本增量回调（来自模型）。
	OnTextDelta func(delta string)
	// OnToolCall 每次解析到工具调用时回调（含 JSON 参数）。
	OnToolCall func(toolName string, arguments json.RawMessage)
	// OnToolData 工具流式数据回调。
	OnToolData func(toolName string, data string)
	// OnToolError 工具执行出错时回调（含 IsError=true 的 content）。
	// 若不设置，则错误只会写入历史消息。
	OnToolError func(toolName string, content string)
	// OnToolDone 单次工具执行结束（已得到结果）后回调。
	OnToolDone func(toolName string)
	// OnHitlMarker 当本轮模型未发起工具调用（FinishReason != tool_calls），且助手文本中含合法
	// `<hitl>...</hitl>` 块（JSON 与 tui_input 同形）时调用；返回的用户回复将作为 user 消息追加并进入下一轮。
	// 与 tui_input 工具优先：若本轮走 tool_calls 路径则不会触发此回调。
	OnHitlMarker func(tools.TUIInputInput) (reply string, err error)
}

type LoopResult

type LoopResult struct {
	Text         string
	FinishReason ai.FinishReason
	Turns        int
	ToolCalls    int
	LastMessage  *ai.ModelMessage
	HitTurnLimit bool
	HitToolLimit bool
}

type MicroCompactConfig

type MicroCompactConfig struct {
	Enabled          bool
	ThresholdChars   int
	KeepHeadChars    int
	KeepTailChars    int
	ReplacementLabel string
}