Documentation
¶
Overview ¶
Package agent provides the agent bundle primitive. An Agent is a configured, self-sufficient unit of inference: it owns the provider, model spec, transforms, handlers, cognitive pattern, tracer, and (optionally) a state binding. Callers configure the agent at construction and then use Run to perform inference.
The agent is reusable: many Run calls share the same internal step. The agent is composable: any agent can be wrapped as a tool.Tool by a parent agent (see x/subagent).
Differences between agent kinds (ReAct, SingleShot, Verified) live in the configured pattern, not in the agent type. All agents are agent.Agent.
When WithState is bound, Run auto-appends the produced turn to the bound ledger. Callers that want a fresh state per Run should not bind state or should call LoadTurns before each Run.
Lifecycle: an agent constructed by New owns an internal *loop.Step. Close stops the step and closes any subscriber channels. Close is safe to call multiple times.
Index ¶
- type Agent
- func (a *Agent) Close() error
- func (a *Agent) Name() string
- func (a *Agent) Pattern() cognitive.Pattern
- func (a *Agent) Provider() provider.Provider
- func (a *Agent) Run(ctx context.Context, st ledger.State) (ledger.State, error)
- func (a *Agent) Spec() models.Spec
- func (a *Agent) Step() *loop.Step
- func (a *Agent) Subscribe(kinds ...string) <-chan loop.OutputEvent
- type Option
- func WithHandlers(h ...loop.Handler) Option
- func WithInvokeOptions(opts ...provider.InvokeOption) Option
- func WithPattern(p cognitive.Pattern) Option
- func WithProvider(p provider.Provider) Option
- func WithSpec(spec models.Spec) Option
- func WithState(st ledger.State) Option
- func WithTracer(tracer trace.Tracer) Option
- func WithTransforms(t ...loop.Transform) Option
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Agent ¶
type Agent struct {
// contains filtered or unexported fields
}
Agent is a configured bundle of everything an inference call needs: provider, model spec, transforms, handlers, cognitive pattern, tracer, and (optionally) a state binding. The same Agent is reused across many Run calls; differences between "kinds" of agent (ReAct, SingleShot, Verified) live in the configured pattern, not in the agent type.
func New ¶
New constructs an Agent with the given name and options. The pattern must be configured via WithPattern; if not, New panics.
New builds an internal *loop.Step from the configured options. The step is reused across Run calls.
func (*Agent) Close ¶ added in v0.12.3
Close stops the agent's internal step and closes all subscriber channels. Safe to call multiple times.
func (*Agent) Name ¶ added in v0.12.3
Name returns the agent's identifier (the value passed to New).
func (*Agent) Run ¶
Run executes the configured pattern against the given ledger. The caller may invoke Run any number of times; the same internal step is reused.
When WithState was used at construction, Run auto-appends the produced turn to the bound state (via the underlying step's Emit/TurnCompleteEvent path).
When a tracer is configured, Run records an "agent.run" span (Internal) with agent.name and agent.pattern attributes. The span is the parent of any loop.turn span emitted by Step.Turn.
func (*Agent) Step ¶ added in v0.12.3
Step returns the agent's internal loop.Step. Exposed for advanced wiring (sub-agents, custom handlers that need direct access to the underlying emitter). Most callers should use Run/Subscribe/Close.
func (*Agent) Subscribe ¶ added in v0.12.3
func (a *Agent) Subscribe(kinds ...string) <-chan loop.OutputEvent
Subscribe returns a filtered output event channel from the agent's internal step. It is a thin pass-through to step.Subscribe; the event surface is owned by the loop.
The returned channel is closed when the agent is Closed (or when the step's underlying EventBus closes for any other reason).
type Option ¶ added in v0.12.3
type Option func(*Agent)
Option configures an Agent. Options are applied in order at New; later options can append to slice-valued options (WithTransforms, WithHandlers, WithInvokeOptions).
func WithHandlers ¶ added in v0.12.3
WithHandlers registers loop.Handler values that run on the complete response after each turn. They apply to every inference the agent performs.
func WithInvokeOptions ¶ added in v0.12.3
func WithInvokeOptions(opts ...provider.InvokeOption) Option
WithInvokeOptions configures per-call provider options forwarded to every provider call made by the agent's underlying step.
func WithPattern ¶ added in v0.12.3
WithPattern sets the cognitive pattern that drives Run. Required: New panics if WithPattern is not provided.
func WithProvider ¶ added in v0.12.3
WithProvider sets the provider used for inference. The provider is invoked by the agent's internal step.
func WithSpec ¶ added in v0.12.3
WithSpec sets the agent's model spec. It becomes the loop's default spec; per-call specs (set by the pattern) override it when non-empty.
func WithState ¶ added in v0.12.3
WithState binds a mutable state to the agent so that TurnCompleteEvents from Run auto-append to the ledger. If not set, Run does not auto-append; callers manage state themselves. Use LoadTurns to reset the bound state between Run calls.
func WithTracer ¶ added in v0.12.3
WithTracer configures an OpenTelemetry tracer. When set, Run records an "agent.run" span (Internal) with agent.name and agent.pattern attributes, parent of any loop.turn span emitted by the underlying step.
func WithTransforms ¶ added in v0.12.3
WithTransforms registers loop.Transform values that run before each provider call. They apply to every inference the agent performs.
Source Files