Files
samandCopilot 64dfad6d53 feat(runs): add typed results and model aliases (#2043)
Also fix repository-free message.send validation (#2046) and add a single-binary development smoke path (#1977).

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
2026-11-18 23:47:35 +11:00

130 lines
4.2 KiB
Go

package runs
import (
"context"
"encoding/json/jsontext"
"errors"
"github.com/samcharles93/ai-sdk/agentloop"
"github.com/samcharles93/ai-sdk/chat"
"github.com/samcharles93/ai-sdk/core"
"github.com/samcharles93/ai-sdk/middleware"
)
// AgentRequest is one agent loop inside a workflow.
type AgentRequest struct {
// Name keys the loop's journal and its idempotency keys; it must be
// unique within the workflow.
Name string
Provider chat.Provider
Model string
ModelInfo chat.ModelInfo
System string
Prompt string
Tools core.ToolSet
Budget agentloop.Budget
// Capture is the name of a tool whose input the loop should keep. The
// input of its last successful call comes back as AgentResult.Returned.
// It is read from the journal, so a resumed run that replays the call
// still has it.
Capture string
}
// AgentResult is how an agent loop ended.
type AgentResult struct {
Completed bool `json:"completed"`
StopReason string `json:"stop_reason"`
Detail string `json:"detail,omitempty"`
Answer string `json:"answer,omitempty"`
Steps int `json:"steps"`
ToolCalls int `json:"tool_calls"`
Usage chat.Usage `json:"usage"`
// Returned is the input of the agent's last successful call to the tool
// that AgentRequest.Capture names.
Returned jsontext.Value `json:"returned,omitzero"`
}
// Agent runs a tool-using agent loop whose every model call and tool call is
// a step of this run. After a crash the loop resumes from its recorded calls:
// no model call is paid for twice and no tool runs twice. Budgets count the
// calls recorded in earlier attempts.
func (rc *Context) Agent(req AgentRequest) (AgentResult, error) {
journal := rc.Journal[agentloop.Entry]("agent:" + req.Name)
res, err := agentloop.RunLoop(rc.ctx, agentloop.LoopConfig{
Provider: retryModel(req.Provider),
Model: req.Model,
ModelInfo: req.ModelInfo,
System: req.System,
Prompt: req.Prompt,
Tools: req.Tools,
Budget: req.Budget,
Journal: loopJournal{journal},
RunID: rc.run.ID.String() + ":" + req.Name,
})
out := AgentResult{
Completed: res.Status == agentloop.StatusCompleted,
StopReason: res.StopReason,
Detail: res.Detail,
Steps: len(res.Steps),
ToolCalls: len(res.ToolCalls),
Usage: res.Usage,
}
if out.Completed && len(res.Steps) > 0 {
out.Answer = res.Steps[len(res.Steps)-1].Text
}
// An action that may have taken effect parks the loop. The unknown outcome
// is the result, so the workflow can tell the owner.
if errors.Is(err, core.ErrOutcomeUnknown) && out.StopReason == agentloop.StopOutcomeUnknown {
return out, nil
}
if err != nil {
return out, err
}
// A lost lease or a shutdown ends the loop as cancelled; the run isn't
// finished, it resumes elsewhere.
if err := rc.ctx.Err(); err != nil {
return out, err
}
if req.Capture != "" && out.Completed {
if out.Returned, err = returned(rc.ctx, journal, req.Capture); err != nil {
return out, err
}
}
return out, nil
}
// returned only scans entries consumed by the loop. On replay, the next
// position may already contain the workflow step that follows the loop.
func returned(ctx context.Context, j *Journal[agentloop.Entry], tool string) (jsontext.Value, error) {
var out jsontext.Value
end := int64(j.rc.next - j.base)
for pos := range end {
e, err := j.Lookup(ctx, pos)
switch {
case err != nil:
return nil, err
case e == nil:
return out, nil
case e.Kind == agentloop.EntryTool && e.ToolName == tool && e.Error == "" && !e.Unknown:
out = jsontext.Value(e.Input)
}
}
return out, nil
}
// retryModel retries a transient model failure at the same journal position.
// Only a final failure ends the loop, and it records nothing, so a resumed run
// asks again.
func retryModel(p chat.Provider) chat.Provider {
return middleware.RetryChat(middleware.RetryConfig{MaxAttempts: 4}, middleware.ExponentialBackoff{}, middleware.DefaultRetryableError)(p)
}
// loopJournal adapts the run journal for the agent loop.
type loopJournal struct {
*Journal[agentloop.Entry]
}
func (j loopJournal) Record(ctx context.Context, e agentloop.Entry) error {
return j.Journal.Record(ctx, e.Position, e)
}