127 lines
4.6 KiB
Go
127 lines
4.6 KiB
Go
// Package loop implements the default agent execution engine of the Cyrene v2
|
|
// runtime (DevDocs/design/04-运行时.md §1). It owns the loop that package agent
|
|
// deliberately leaves out: assemble context from memory, drive the model for up
|
|
// to MaxRounds steps, execute any requested tool calls under a per-invoke
|
|
// timeout, feed tool results back to the model, persist a checkpoint at every
|
|
// step, emit structured traces, deliver streamed deltas and run the
|
|
// memory-extraction hook.
|
|
//
|
|
// The loop is configured with injected dependencies rather than concrete wiring,
|
|
// so it stays leaf-testable with mocks (a mock adapter, mock guardrail and mock
|
|
// tool, plus real in-memory memory/persist stores and a buffered trace recorder).
|
|
package loop
|
|
|
|
import (
|
|
"errors"
|
|
"io"
|
|
"log/slog"
|
|
|
|
"git.yeij.top/AskaEth/Cyrene_v2/internal/logger"
|
|
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/agent"
|
|
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/guardrail"
|
|
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/memory"
|
|
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/persist"
|
|
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/tool"
|
|
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/trace"
|
|
)
|
|
|
|
// Constants that bound the loop. These are compile-time so no magic number
|
|
// appears in the run path.
|
|
const (
|
|
// DefaultMaxRounds is the tool-loop upper bound used when Options.MaxRounds
|
|
// is non-positive. It matches the agent package's own default.
|
|
DefaultMaxRounds = 8
|
|
|
|
// StopReasonMaxRounds reports that the loop exhausted its round budget
|
|
// before reaching a final answer.
|
|
StopReasonMaxRounds = "max_rounds"
|
|
)
|
|
|
|
// Sentinel errors returned by the Loop. Use errors.Is to test for them; they are
|
|
// returned directly or wrapped with %w so the underlying cause stays available.
|
|
var (
|
|
// ErrNilAgent is returned by Run when no *agent.Agent was configured.
|
|
ErrNilAgent = errors.New("loop: nil agent")
|
|
|
|
// ErrNoAdapter is returned by Run (streaming path) when the agent was built
|
|
// without a model Adapter.
|
|
ErrNoAdapter = errors.New("loop: no model adapter")
|
|
)
|
|
|
|
// Result is the outcome of a completed Run.
|
|
type Result struct {
|
|
// Text is the final assistant text, or empty when the loop exhausted its
|
|
// budget without a final answer.
|
|
Text string
|
|
// Steps is the number of model steps executed.
|
|
Steps int
|
|
// StopReason classifies how the loop ended: an agent StopReason* value or
|
|
// StopReasonMaxRounds.
|
|
StopReason string
|
|
// ToolCallsExecuted is the number of tool calls the loop invoked, including
|
|
// those that failed.
|
|
ToolCallsExecuted int
|
|
}
|
|
|
|
// Loop is the default agent execution engine. It is configured once via New and
|
|
// safe for concurrent Run calls as long as the injected dependencies (agent,
|
|
// dispatcher, stores, recorder, tracer) are themselves concurrency-safe, which
|
|
// they are by contract. Run keeps all loop state on the stack.
|
|
type Loop struct {
|
|
agent *agent.Agent
|
|
tools *tool.Dispatcher
|
|
memory *memory.Store
|
|
retriever *memory.Retriever
|
|
working *memory.WorkingMemory
|
|
extractor memory.Extractor
|
|
checkpoint *persist.Store
|
|
tracer *trace.Tracer
|
|
guards *guardrail.Pipeline
|
|
personaID string
|
|
maxRounds int
|
|
onStream func(delta string)
|
|
log *slog.Logger
|
|
}
|
|
|
|
// New builds a Loop from opts, applying defaults. A non-positive MaxRounds
|
|
// selects DefaultMaxRounds; a nil Log is replaced by a discard logger tagged with
|
|
// source "runtime/loop". Every dependency may be nil and is tolerated until the
|
|
// step that needs it (mirroring the run-time nil-tolerance of the underlying
|
|
// packages); Run returns ErrNilAgent when no agent is configured.
|
|
func New(opts Options) *Loop {
|
|
maxRounds := opts.MaxRounds
|
|
if maxRounds <= 0 {
|
|
maxRounds = DefaultMaxRounds
|
|
}
|
|
return &Loop{
|
|
agent: opts.Agent,
|
|
tools: opts.Tools,
|
|
memory: opts.Memory,
|
|
retriever: opts.Retriever,
|
|
working: opts.WorkingMemory,
|
|
extractor: opts.Extractor,
|
|
checkpoint: opts.Checkpoint,
|
|
tracer: opts.Tracer,
|
|
guards: opts.Guards,
|
|
personaID: opts.PersonaID,
|
|
maxRounds: maxRounds,
|
|
onStream: opts.OnStream,
|
|
log: sourcedLog(opts.Log),
|
|
}
|
|
}
|
|
|
|
// MaxRounds returns the tool-loop upper bound configured for the loop.
|
|
func (l *Loop) MaxRounds() int { return l.maxRounds }
|
|
|
|
// Agent returns the injected agent.
|
|
func (l *Loop) Agent() *agent.Agent { return l.agent }
|
|
|
|
// sourcedLog returns a logger tagged with the module source "runtime/loop",
|
|
// replacing a nil logger with a discard one so the loop can always log safely.
|
|
func sourcedLog(l *slog.Logger) *slog.Logger {
|
|
if l == nil {
|
|
l = slog.New(slog.NewTextHandler(io.Discard, nil))
|
|
}
|
|
return logger.WithSource(l, "runtime/loop")
|
|
}
|