Documentation
¶
Overview ¶
Package run gives an agent run an identity, a registry and a cancel switch.
Agent.Run is synchronous and anonymous: it returns a string and there is no handle on the work while it is in flight. Nothing can ask what is running, attach to it, or stop one specific run. The only per-run object in the SDK is an unexported usage tracker living in a context value, which dies with the stack frame.
This package adds the missing layer, and deliberately nothing more:
- a RunID minted per run;
- a Handle to await the result, observe status, or cancel;
- a Manager that can list live runs and cancel one by ID.
Relationship to pkg/task ¶
pkg/task is a task *lifecycle* service: create a task, plan it, have a human approve the plan, log against it. It concerns work a person tracks. This package concerns a single agent invocation that is in flight right now. They are not alternatives, and neither is built on the other.
Index ¶
- Variables
- func FromContext(ctx context.Context) (string, bool)
- func WithRunID(ctx context.Context, id string) context.Context
- type Agent
- type Handle
- type Info
- type Manager
- func (m *Manager) Active() []Info
- func (m *Manager) Cancel(id string) error
- func (m *Manager) CancelAll() int
- func (m *Manager) Get(id string) (*Handle, error)
- func (m *Manager) List() []Info
- func (m *Manager) Start(ctx context.Context, agent Agent, input string, options ...StartOption) *Handle
- func (m *Manager) Stream(ctx context.Context, agent Agent, input string, options ...StartOption) *Handle
- type ManagerOption
- type StartOption
- type Status
- type StreamingAgent
Constants ¶
This section is empty.
Variables ¶
var ErrNotFound = errors.New("run not found")
ErrNotFound is returned when no run matches an ID.
Functions ¶
func FromContext ¶
FromContext returns the run ID on the context, if any.
It returns the ID rather than the Handle deliberately: a Handle is mutable and reachable from arbitrary tool code, including MCP tools backed by remote processes, which could then mark a run succeeded or forge its result.
Types ¶
type Agent ¶
Agent is the subset of an agent this package needs.
Declared here rather than imported so pkg/run does not depend on pkg/agent, which keeps the dependency pointing one way and lets callers wrap or fake an agent freely.
type Handle ¶
type Handle struct {
// contains filtered or unexported fields
}
Handle is a live reference to one run.
func (*Handle) Cancel ¶
func (h *Handle) Cancel()
Cancel stops the run. It is safe to call more than once, and on a run that has already finished.
func (*Handle) Done ¶
func (h *Handle) Done() <-chan struct{}
Done returns a channel closed when the run reaches a terminal state.
func (*Handle) Events ¶
func (h *Handle) Events() <-chan interfaces.AgentStreamEvent
Events returns the run's stream, or nil if it was not started with Stream.
The channel is closed when the run finishes.
type Info ¶
type Info struct {
ID string
AgentName string
Input string
Status Status
StartedAt time.Time
EndedAt time.Time
Err error
}
Info is a point-in-time snapshot of a run.
type Manager ¶
type Manager struct {
// contains filtered or unexported fields
}
Manager starts runs and keeps track of the ones in flight.
The zero value is not usable; call NewManager.
func NewManager ¶
func NewManager(options ...ManagerOption) *Manager
NewManager creates a run manager.
func (*Manager) CancelAll ¶
CancelAll stops every run still in flight and returns how many it signalled.
type ManagerOption ¶
type ManagerOption func(*Manager)
ManagerOption configures a Manager.
func WithRetainedRuns ¶
func WithRetainedRuns(n int) ManagerOption
WithRetainedRuns sets how many finished runs remain listable. Defaults to 100.
A bound matters: a registry that keeps every run forever is a memory leak in any service that stays up.
type StartOption ¶
type StartOption func(*startConfig)
StartOption configures a single run.
func WithDetached ¶
func WithDetached() StartOption
WithDetached runs independently of the caller's context, so the run survives the request that started it.
Without this a background run started inside an HTTP handler dies when the client disconnects, which is rarely what "background" is meant to mean. With it, the only ways to stop the run are Cancel or a timeout -- so a timeout is strongly advised alongside it.
func WithTimeout ¶
func WithTimeout(d time.Duration) StartOption
WithTimeout bounds the run's duration.
type Status ¶
type Status string
Status is the lifecycle state of a run.
const ( // StatusRunning means the run is in flight. StatusRunning Status = "running" // StatusSucceeded means the run produced a result. StatusSucceeded Status = "succeeded" // StatusFailed means the run returned an error. StatusFailed Status = "failed" // StatusCanceled means the run was cancelled before completing. StatusCanceled Status = "canceled" )
type StreamingAgent ¶
type StreamingAgent interface {
Agent
RunStream(ctx context.Context, input string) (<-chan interfaces.AgentStreamEvent, error)
}
StreamingAgent is implemented by agents that can stream.
Source Files