agentturn

package module
v0.0.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 20, 2026 License: MIT Imports: 14 Imported by: 0

README

agentturn

A composable agent loop in Go over Open Responses: one loop, one transcript type, one tool contract, hooks and queues. Everything else is a front that feeds prompts in and consumes events out, or a subscriber.

  • The transcript is openresponses.Items. What a session stores, what the model receives and what a front renders are the same bytes.
  • The model is any openresponses.Streamer: a remote server through Client.AsAdapter, a local adapter, or another agent served by front/responses.
  • The tool contract is its own library, agenttool, so a tool is written once and runs under any loop. The root module depends on openresponses, agenttool and the standard library; adapters with heavier dependencies are nested modules.

Install

go get github.com/ChristopherDavenport/agentturn

Go 1.25 or later.

A tool, a loop, an agent

type ReadFileArgs struct {
	Path     string `json:"path" desc:"Absolute path to read"`
	MaxBytes int    `json:"max_bytes,omitempty" desc:"Stop after this many bytes"`
}

var ReadFile = agenttool.New("read_file", "Read a file from disk",
	func(ctx context.Context, a ReadFileArgs) (string, error) {
		b, err := os.ReadFile(a.Path)
		return string(b), err
	})

cfg := agentturn.Config{
	Name:         "reader",
	Description:  "Answers questions about files on disk.",
	Model:        openresponses.NewClient(baseURL, openresponses.WithAPIKey(key)).AsAdapter(),
	ModelName:    "gpt-5",
	Instructions: "Be brief.",
	Tools:        []agenttool.Tool{ReadFile},
}

// Low-level: an iterator of events. The loop runs ahead of the consumer
// and the run_end is always the last event.
for ev := range agentturn.Run(ctx, nil, openresponses.Items{openresponses.UserText("What is in go.mod?")}, cfg) {
	switch e := ev.(type) {
	case *agentturn.ItemUpdate:
		if d, ok := e.Stream.(*openresponses.OutputTextDeltaEvent); ok {
			fmt.Print(d.Delta)
		}
	case *agentturn.RunEnd:
		// e.Reason is done, stopped, input_required, aborted or error;
		// a cancelled ctx ends the run with aborted and context.Canceled
		// on e.Err rather than panicking or hanging.
		if e.Err != nil {
			log.Fatal(e.Err)
		}
	}
}

// Stateful: queues, subscribers with barriers, abort, idle.
a := agentturn.New(cfg)
a.Subscribe(func(ctx context.Context, ev agentturn.Event) error {
	// every event is a barrier: the loop waits for this to return
	return nil
})
end, err := a.Prompt(ctx, openresponses.UserText("What is in go.mod?"))

Prompt returns the RunEnd; the error is set only when the run could not start or ended with error. A print front correlates tool_end, which arrives in completion order, with tool_start by call ID rather than by position:

started := map[string]string{}
a.Subscribe(func(_ context.Context, ev agentturn.Event) error {
	switch e := ev.(type) {
	case *agentturn.ToolStart:
		started[e.CallID] = e.Name + " " + string(e.Args)
		fmt.Println("▶", started[e.CallID])
	case *agentturn.ToolEnd:
		fmt.Printf("  [%s] %s\n", started[e.CallID], e.Result.Output.Text)
	}
	return nil
})

A run is one Prompt or Continue until the agent goes idle; a turn is one model call plus the tool executions it requested. The events of a run, in order:

event carries
run_start run ID
turn_start the exact openresponses.Request sent
model_retry a transient model failure about to be retried under Config.Retry: attempt, error, delay
item_start, item_update, item_end an item entering the transcript; item_update wraps the wire StreamEvent verbatim
response_end the folded Response with usage, before any tool of the turn runs
tool_start, tool_update, tool_end one tool call from preflight to result, tool_end in completion order
turn_end the folded Response with usage, and the tool results
run_end the items added this run and the reason: done, stopped, input_required, aborted, error

Tools

Tools come from agenttool: agenttool.New[Args, Out] turns a typed function into a tool, reflecting and validating the schema from the argument struct, and agenttool.Executor runs a batch. The loop only knows the agenttool.Tool interface; see that repository for the contract, the schema generator and the MCP adapters.

A batch of calls runs in parallel, bounded, unless the config or a tool asks for sequential execution. Config.BeforeToolCall is the policy seam: block, rewrite arguments, terminate the run, or defer the call to the caller. A deferred call ends the run with input_required and the pending calls listed; Agent.Resume takes an answer per call and continues, which is how a front asks a human before a tool runs. An answer is an output the front produced, usually a refusal, or an approval, which runs the call inside the loop with its tool events, hooks and execution mode:

cfg.BeforeToolCall = func(_ context.Context, info agentturn.ToolCallInfo) (*agentturn.ToolDecision, error) {
	if info.Call.Name == "delete_file" {
		return &agentturn.ToolDecision{Action: agentturn.Defer}, nil
	}
	return nil, nil
}
end, err := a.Prompt(ctx, openresponses.UserText("Clean up the build directory."))
if err == nil && end.Reason == agentturn.ReasonInputRequired {
	// ask the human about end.Pending, then answer every call
	var answers []agentturn.Answer
	for _, call := range end.Pending {
		if approved(call) {
			answers = append(answers, agentturn.Approve(call.CallID))
		} else {
			answers = append(answers, agentturn.Output(openresponses.NewFunctionCallOutput(call.CallID, "denied by the user")))
		}
	}
	end, err = a.Resume(ctx, answers...)
}

The same path repairs a run that was aborted mid-batch: the cut-off calls are on end.Pending, and an agent built with agentturn.WithTranscript from a stored session marks them pending again. A front whose user has moved on answers them on the way to the next message instead: a Prompt that opens with an output for each pending call is accepted, and the model sees the outputs and the message in one call. AfterToolCall overrides results; ShouldStopAfterTurn ends a run early.

Every other request member comes from Config.Request, the base the loop builds each turn's request on: tool_choice, max_output_tokens, include: reasoning.encrypted_content for reasoning models, and so on. BeforeModelCall sees the finished request before it is sent.

Config.Retry retries a model call that failed before delivering anything: a 429 or 5xx, a dropped stream, a refused connection. The retry happens inside the turn, honours Retry-After, reports itself as a model_retry event, and is cut short by Abort. An attempt that already delivered an item is never retried, since the transcript may hold part of it.

cfg.Retry = agentturn.Retry{MaxAttempts: 4}

Composition

The loop never learns a sub-agent concept. It knows a Model and a list of Tool, and every composition is one of those two things. A protocol earns a place only with a serve side and a consume side:

protocol serve consume
Open Responses front/responses openresponses.Client.AsAdapter
MCP agenttool/mcpserver agenttool/mcpclient
A2A front/a2a tools/a2a
in-process Agent tools/agent

The MCP row lives in agenttool because MCP is about tools, not about the loop: mcpserver serves any agenttool.Tool, and mcpclient produces them. An agent stands in three places inside another system:

  • As a model. front/responses makes a loop an openresponses.Adapter; openresponses.NewHandler serves it; another loop points its Model at it through Client.AsAdapter.
  • As a tool. tools/agent wraps a Config as a Tool: a child run on a fresh transcript, progress through Call.OnUpdate, the final text as the output and a ChildInfo in Result.Details.
  • As a peer. front/a2a exposes a loop to A2A callers; tools/a2a wraps a remote A2A agent as a Tool.

Config.Name and Config.Description are the single source for how an agent presents itself in every one of these.

Modules

path module depends on
. (agentturn), front/responses, compact, tools/agent root openresponses, agenttool
front/a2a, tools/a2a nested github.com/a2aproject/a2a-go
session nested github.com/ChristopherDavenport/agentsession

Every module shares the root's version and is tagged at the same commit, the nested ones with their directory as the prefix (front/a2a/v0.0.2); each is fetched with go get like any module.

compact is the reference Transform: when the transcript exceeds a token budget it folds the older part and splices the result in front of the recent tail, caching it by prefix so repeated turns cost nothing. New folds through the model's Compact endpoint; NewLocal asks an ordinary model call for a summary and splices it in as a message, for the servers that do not implement compaction.

c := compact.New(model, compact.WithBudget(60_000))
cfg.Transform = c.Transform

l := compact.NewLocal(model, compact.WithBudget(60_000), compact.WithModel("gpt-5-mini"))
cfg.Transform = l.Transform

WithOnFold reports every fold, applied or failed, with the index at which the transcript was split, so a recorder can write it.

session subscribes an Agent to an agentsession store: items on item_end, the response entry with its request hash on response_end, config entries as settings change, tool list changes as deltas, a compaction entry for every fold the compact transform reports, and a session of its own for every child run it observes, linked from the parent. Because every event is a barrier, a turn's tool preflight waits for the assistant items to be durable.

rec, s, err := session.Start(ctx, store, agentsession.Header{CWD: cwd})
defer rec.Attach(agent)()
specialist := agent.New(childCfg, agent.WithObserver(rec.Observe))
c := compact.NewLocal(model, compact.WithOnFold(rec.Fold))

Design

The plan is docs/plans/agent-layer.md. Invariants the tests hold:

  • The transcript after a run is a valid Open Responses input: every function_call is answered before the next user message, or the run ended with the unanswered calls on RunEnd.Pending, whether a hook deferred them or an abort or failure cut them off. Agent.Resume answers them; Prompt and Continue refuse until it has.
  • Exactly one run_end per run, nothing after it.
  • item_end for an assistant item follows output_item.done; partial items never reach subscribers as item_end.
  • Abort cancels the model stream and running tools through the context; the transcript keeps only completed items. Every event the abort leaves behind, the tool_end of each cut-off call and the run_end, still reaches subscribers, with a context whose cancellation is lifted.
  • Events for one run are delivered from one goroutine.

License

MIT. See LICENSE.

Documentation

Overview

Package agentturn is a composable agent loop over Open Responses: one loop, one transcript type, one tool contract, hooks and queues. Everything else is a front that feeds prompts in and consumes events out, or a subscriber.

The transcript is openresponses.Items. What a session stores, what the model receives and what a front renders are the same bytes. The model is any openresponses.Streamer: a remote server through openresponses.Client.AsAdapter, a local adapter, or another agent served by front/responses.

Vocabulary

A run is one Run, Continue, Agent.Prompt or Agent.Continue until the agent goes idle. A turn is one model call plus the tool executions it requested.

Transcript and openresponses.Items are one type under two names, and the name says what a value is. A Transcript is a whole conversation: what Run starts from, what Filter and Transform see and return, what a hook or a tool reads from its context. Items is a fragment: the prompts of a run, the outputs of a batch, the items a run added.

Low-level loop

Run and Continue are observational: they yield Event values in order and the loop does not wait for the consumer between phases. The RunEnd is always the last event and says how the run ended. 

for ev := range agentturn.Run(ctx, transcript, prompts, cfg) {
	switch e := ev.(type) {
	case *agentturn.ItemUpdate:
		if d, ok := e.Stream.(*openresponses.OutputTextDeltaEvent); ok {
			fmt.Print(d.Delta)
		}
	case *agentturn.RunEnd:
		if e.Err != nil { ... }
	}
}

Agent

Agent adds queues, subscribers and run control over the same loop. Subscribers are awaited in registration order and every event is a barrier: tool preflight for a turn does not start until every subscriber has returned for the assistant item, and Agent.Prompt settles only after the run_end subscribers finish.

Composition

The loop never learns a sub-agent concept. It knows a Model and a list of agenttool.Tool, and every composition is one of those two things: front/responses serves a loop as a model, tools/agent wraps a config as a tool, and the A2A and MCP adapters do the same across a protocol.

Index

Constants

View Source 
const (
	EventRunStart    = "run_start"
	EventTurnStart   = "turn_start"
	EventModelRetry  = "model_retry"
	EventResponseEnd = "response_end"
	EventItemStart   = "item_start"
	EventItemUpdate  = "item_update"
	EventItemEnd     = "item_end"
	EventToolStart   = "tool_start"
	EventToolUpdate  = "tool_update"
	EventToolEnd     = "tool_end"
	EventTurnEnd     = "turn_end"
	EventRunEnd      = "run_end"
)

Event type names.

View Source 
const EventBuffer = 256

EventBuffer is how many events the loop can run ahead of the consumer of Run or Continue before it blocks; Agent delivers every event synchronously and has no buffer.

Variables

View Source 
var (
	// ErrRunning is returned when Prompt, Continue, Resume, SetConfig or
	// SetTranscript is called while a run is active.
	ErrRunning = errors.New("agentturn: agent is already running")
	// ErrInputRequired is returned when the last run left calls
	// unanswered, deferred to the caller or cut off by an abort or a
	// failure; answer them through [Agent.Resume], or open the next
	// [Agent.Prompt] with their outputs. The typed errors of tools/agent
	// and tools/a2a match it with errors.Is, so a host can ask "does any
	// sub-agent need input" once.
	ErrInputRequired = errors.New("agentturn: pending tool calls must be resumed before continuing")
	// ErrNotPending is returned when Resume was given an answer for a
	// call that is not pending, left a pending call unanswered, or was
	// called with nothing pending, and when a Prompt opens with an
	// output for a call that is not pending.
	ErrNotPending = errors.New("agentturn: output does not answer a pending call")
)

Errors returned by Agent.

View Source 
var (
	// ErrNoModel is returned when Config.Model is nil.
	ErrNoModel = errors.New("agentturn: config has no model")
	// ErrCannotContinue is returned when the transcript does not end
	// with a user message or a function call output, so there is
	// nothing for the model to answer.
	ErrCannotContinue = errors.New("agentturn: transcript must end with a user message or a function call output to continue")
	// ErrNoPrompt is returned when Run was called with no prompt items.
	ErrNoPrompt = errors.New("agentturn: no prompt items")
)

Errors returned before a run starts. Every error the package produces, sentinel or wrapped, begins with "agentturn:".

Functions

func CanContinue added in v0.0.4 

func CanContinue(t Transcript) bool

CanContinue reports whether the model has something to answer: the transcript ends with a user message or a function call output.

func ContextWithRunID added in v0.0.5 

func ContextWithRunID(ctx context.Context, runID string) context.Context

ContextWithRunID attaches a run ID to ctx. The loop does this with its own for everything a run calls, the transform, the hooks, the model and the tools, so a tool that composes another agent, and whatever observes that child, can tell which run it was called from.

func ContextWithTranscript added in v0.0.4 

func ContextWithTranscript(ctx context.Context, t Transcript) context.Context

ContextWithTranscript attaches a transcript to ctx. The loop does this with its working transcript before running a turn's hooks and tools, so a tool that composes another agent can seed it from the conversation without the host threading anything through.

func Continue 

func Continue(ctx context.Context, t Transcript, cfg Config) iter.Seq[Event]

Continue drives the loop from the transcript as it stands, which must satisfy CanContinue. Events arrive as for Run.

func DefaultBackoff added in v0.0.4 

func DefaultBackoff(attempt int, err error) time.Duration

DefaultBackoff is the Retry.Backoff used when none is set: the Retry-After header of an openresponses error when it names a number of seconds, otherwise 500ms doubled per retry and capped at 30s, without jitter.

func DefaultRetryable added in v0.0.4 

func DefaultRetryable(err error) bool

DefaultRetryable is the Retry.Retryable used when none is set: an openresponses error with status 408, 409, 429 or 5xx, a stream that ended before its terminal event, and transport failures (net.Error, an unexpected EOF, a reset or refused connection). Everything else, a 4xx in particular, is final.

func Run 

func Run(ctx context.Context, t Transcript, prompts openresponses.Items, cfg Config) iter.Seq[Event]

Run appends prompts to the transcript and drives the loop until the agent goes idle. Events are yielded in order and the RunEnd is the single terminal: it is always the last event, its Reason says how the run ended and its Err carries the failure when Reason is ReasonError, the context error when Reason is ReasonAborted, and nil otherwise. A misuse before the run starts (ErrNoPrompt, ErrCannotContinue, ErrNoModel, a duplicate tool name) yields one RunEnd with ReasonError and no other event.

The loop runs ahead of the consumer by up to EventBuffer events and applies backpressure after that. Breaking out of the loop cancels the run and blocks until it has wound down.

The transcript is not modified; the items the run appended are on the RunEnd.

func RunIDFromContext added in v0.0.5 

func RunIDFromContext(ctx context.Context) string

RunIDFromContext returns the ID of the run whose hook or tool call the context belongs to, or "" outside a loop.

func VisibleFilter 

func VisibleFilter(visible ...string) func(Transcript) Transcript

VisibleFilter returns a filter like DefaultFilter that keeps the listed extension item types.

Types

type Agent 

type Agent struct {
	// contains filtered or unexported fields
}

Agent is the stateful loop: a transcript, queues, subscribers and run control over Run. One run at a time; a second Prompt while one is active returns ErrRunning. The zero Agent has no model and is idle; use New.

Subscribers are called synchronously, in registration order, for every event, so every event is a barrier: the loop does not move to the next phase until each subscriber has returned. A subscriber that returns an error ends the run with ReasonError. Every event is delivered with a context whose cancellation is lifted: Agent.Abort reaches the model stream and the running tools, and the events that follow it, the tool_end of a cut-off call and the run_end among them, still reach a subscriber that writes durable state with a context it can use. A subscriber that fails while the run is being aborted ends it with ReasonAborted and its error joined to the context error on RunEnd.Err.

func New 

func New(cfg Config, opts ...Option) *Agent

New builds an agent.

func (*Agent) Abort 

func (a *Agent) Abort()

Abort cancels the active run, if any. The model stream and running tools see the cancellation through their context and the run ends with ReasonAborted.

func (*Agent) Config 

func (a *Agent) Config() Config

Config returns the agent's configuration.

func (*Agent) Continue 

func (a *Agent) Continue(ctx context.Context) (*RunEnd, error)

Continue runs from the transcript as it stands, which must satisfy CanContinue, and returns as Agent.Prompt does.

func (*Agent) FollowUp 

func (a *Agent) FollowUp(items ...openresponses.Item)

FollowUp queues items to be injected when the run would otherwise end, so the agent keeps going instead of going idle.

func (*Agent) Prompt 

func (a *Agent) Prompt(ctx context.Context, items ...openresponses.Item) (*RunEnd, error)

Prompt appends items and runs until idle. It returns when the run_end subscribers have returned, with the RunEnd that says how the run ended: done, stopped, input_required with the pending calls, or aborted with the context error on RunEnd.Err. The error is set only when the run could not start (ErrNoPrompt, ErrRunning, ErrInputRequired, ErrNotPending, ErrNoModel) or ended with ReasonError, in which case it is RunEnd.Err and the RunEnd is returned alongside.

While calls are pending, a prompt that opens with a function_call_output for each of them is accepted: the outputs are appended with their item events ahead of the message, so the next model call sees the answers and the message together, which is what a front wants after an abort when the user's next line is the next prompt. A leading output for a call that is not pending returns ErrNotPending; a prompt that leaves a pending call unanswered returns ErrInputRequired.

func (*Agent) Resume 

func (a *Agent) Resume(ctx context.Context, answers ...Answer) (*RunEnd, error)

Resume answers the calls the last run left pending and continues, whether they were deferred to the caller or cut off by an abort or a failure. Every pending call must have exactly one answer, and no answer may name a call that is not pending. An answer is an output or an approval: a caller that refuses a call answers it with the refusal as text, which the model then sees; a caller that approves a deferred call lets the loop run it.

The outputs are appended with their item events first. The approved calls then run as one batch as the loop runs any batch, with BeforeToolCall skipped because the decision has been made: tool_start, tool_update and tool_end are emitted with Turn 0, Sequential and MaxParallelTools apply, AfterToolCall runs, and the outputs are appended in the calls' transcript order. A batch whose every result sets Terminate ends the run with ReasonStopped without calling the model. The model is then called and the run returns as Agent.Prompt does. With nothing pending, Resume returns ErrNotPending.

func (*Agent) SetConfig added in v0.0.4 

func (a *Agent) SetConfig(cfg Config) error

SetConfig replaces the configuration for the next run: model, instructions, reasoning, tools, hooks, all of it. It returns ErrRunning while a run is active. Subscribers and queues are kept; a session recorder attached to the agent sees the change as a config delta on the next turn.

func (*Agent) SetTranscript added in v0.0.4 

func (a *Agent) SetTranscript(t Transcript) error

SetTranscript replaces the transcript, as when switching to another branch of a session. It returns ErrRunning while a run is active. The pending calls are derived from the new transcript as WithTranscript derives them, so whatever the old transcript was waiting on is forgotten and whatever the new one is waiting on must be answered through Agent.Resume. Queued Steer and FollowUp items are kept.

func (*Agent) State 

func (a *Agent) State() State

State returns a snapshot.

func (*Agent) Steer 

func (a *Agent) Steer(items ...openresponses.Item)

Steer queues items to be injected after the current tool batch, before the next model call. When the agent is idle they are consumed by the next run at the same point.

func (*Agent) Subscribe 

func (a *Agent) Subscribe(fn func(context.Context, Event) error) (unsubscribe func())

Subscribe registers fn for every event and returns a function that removes it. Subscribing during a run takes effect from the next event.

func (*Agent) WaitForIdle 

func (a *Agent) WaitForIdle(ctx context.Context) error

WaitForIdle blocks until no run is active or ctx is done. An agent that has never run is idle.

type Answer added in v0.0.5 

type Answer struct {
	// CallID names the pending call.
	CallID string
	// Output, when set, answers the call without running it: a refusal
	// as text, or the result of a call the caller ran itself.
	Output *openresponses.FunctionCallOutput
	// Args, for an approval, replaces the arguments the tool receives,
	// as ToolDecision.Args does. nil keeps the call's own.
	Args json.RawMessage
}

Answer resolves one pending call for Agent.Resume: an output the caller produced, or an approval that runs the call inside the loop. Build one with Output, Approve or ApproveWith.

func Approve added in v0.0.5 

func Approve(callID string) Answer

Approve runs the pending call with the arguments the model gave.

func ApproveWith added in v0.0.5 

func ApproveWith(callID string, args json.RawMessage) Answer

ApproveWith runs the pending call with args in place of the model's.

func Output added in v0.0.5 

func Output(out *openresponses.FunctionCallOutput) Answer

Output answers a pending call with out.

type Config 

type Config struct {
	// Name is how the agent names itself when composed: the tool name in
	// tools/agent, the server name in front/mcp, the agent card in
	// front/a2a.
	Name string
	// Description is one paragraph about the agent, used the same way.
	Description string

	// Model streams responses. Required.
	Model Model
	// ModelName is the model field of every request.
	ModelName string
	// Instructions is the instructions field of every request.
	Instructions string

	// Tools the model may call. The loop reads it at the start of each
	// turn.
	Tools []agenttool.Tool
	// ToolProvider, when set, supplies the tools for each turn in place
	// of Tools, so a source whose tool list changes, such as a remote
	// MCP server, is picked up on the next turn. It is called once per
	// turn, before the model call, and the same list serves the turn's
	// tool batch, so a call resolves against the tools the model was
	// offered.
	//
	// A provider that returns a snapshot offers a change one turn late
	// when the change is still in flight as the turn starts: a tool
	// whose result announces a new tool returns before the refresh that
	// fetches it has completed. A provider that must offer the change
	// on the very next call waits for it here, bounded by ctx, as
	// mcpclient's Await does:
	//
	//	cfg.ToolProvider = func(ctx context.Context) []agenttool.Tool {
	//		ctx, cancel := context.WithTimeout(ctx, 2*time.Second)
	//		defer cancel()
	//		_ = remote.Await(ctx)
	//		return remote.Tools()
	//	}
	ToolProvider func(ctx context.Context) []agenttool.Tool

	// Reasoning is the reasoning field of every request: effort and
	// summary. The zero value leaves the request's own.
	Reasoning openresponses.ReasoningConfig
	// Text is the text field of every request: output format and
	// verbosity. The zero value leaves the request's own.
	Text openresponses.TextConfig

	// Request is the base of every request the loop sends: tool_choice,
	// parallel_tool_calls, max_output_tokens, temperature, truncation,
	// include, safety_identifier, prompt_cache_key, service_tier and
	// every other member are copied from it. The loop owns input, tools,
	// store, stream and previous_response_id, and ModelName,
	// Instructions, Reasoning and Text take precedence over the same
	// members here when set. The loop adds nothing else: the run and
	// turn IDs are on every event, not on the request, so the settings
	// the model sees change only when this config does.
	Request openresponses.Request

	// BeforeModelCall runs on the fully built request of each turn, just
	// before it is sent and before turn_start reports it. It may change
	// anything; a change to Input has the same effect on session
	// verification as a Transform.
	BeforeModelCall func(context.Context, *openresponses.Request) error

	// Retry is the policy for transient model failures. The zero value
	// retries nothing; see [Retry].
	Retry Retry

	// ToolExecution selects parallel (default) or sequential batches.
	ToolExecution ExecutionMode
	// MaxParallelTools bounds a parallel batch; zero means
	// agenttool.DefaultMaxParallel.
	MaxParallelTools int
	// MaxTurns stops a run after this many turns with ReasonStopped;
	// zero means no limit.
	MaxTurns int

	// Filter drops app-only items before each model call and returns
	// the conversation the model sees. nil means [DefaultFilter].
	Filter func(Transcript) Transcript
	// Transform runs before each model call on the whole transcript and
	// may return a shorter or otherwise edited one for that call only:
	// prune, compact, inject context. It receives a copy of the slice
	// and must not mutate the items. The working transcript is not
	// replaced.
	Transform func(context.Context, Transcript) (Transcript, error)

	// BeforeToolCall runs once per call, in the model's order, before any
	// call of the batch executes. A nil decision allows the call.
	BeforeToolCall func(context.Context, ToolCallInfo) (*ToolDecision, error)
	// AfterToolCall runs when a call completes and may replace its
	// result. A nil override keeps the result.
	AfterToolCall func(context.Context, ToolResultInfo) (*ToolOverride, error)
	// ShouldStopAfterTurn ends the run after a turn even when the model
	// requested tools.
	ShouldStopAfterTurn func(context.Context, TurnInfo) (bool, error)

	// RequestExtra is passed through as Request.Extra on every call.
	RequestExtra map[string]any
}

Config describes an agent. The zero value is not usable: Model is required.

func (Config) BaseRequest 

func (c Config) BaseRequest(ctx context.Context) openresponses.Request

BaseRequest returns the request every turn starts from: Config.Request with the loop-owned transport members set (store false, stream true, no previous_response_id), ModelName, Instructions, Reasoning and Text applied over it, RequestExtra merged over its Extra, and the tool definitions of the moment. Only Input is added by the loop; a recorder uses this to write the initial settings.

func (Config) ResolveTools added in v0.0.4 

func (c Config) ResolveTools(ctx context.Context) []agenttool.Tool

ResolveTools returns the tools of the moment: ToolProvider's answer when it is set, Tools otherwise. The loop consults it once per turn, before the model call; a front that builds its own request uses it so the provider fallback lives in one place.

type Event 

type Event interface {
	EventType() string
}

Event is one step of a run. Concrete types are RunStart, TurnStart, ModelRetry, ItemStart, ItemUpdate, ItemEnd, ResponseEnd, ToolStart, ToolUpdate, ToolEnd, TurnEnd and RunEnd. Decoded values are pointers, so switch on *ItemUpdate and so on.

type ExecutionMode 

type ExecutionMode int

ExecutionMode selects how a batch of tool calls runs. 

const (
	// ExecParallel runs the calls of a batch concurrently, bounded by
	// [Config.MaxParallelTools], unless a tool in the batch is
	// agenttool.Sequential.
	ExecParallel ExecutionMode = iota
	// ExecSequential runs every batch one call at a time in the model's
	// order.
	ExecSequential
)

type ItemEnd 

type ItemEnd struct {
	RunID string
	Turn  int
	Item  openresponses.Item
	// ResponseID is the ID of the response that produced the item, and
	// empty for an item the loop appended itself.
	ResponseID string
}

ItemEnd carries a completed item. For an assistant item it is emitted only after output_item.done; partial items never arrive here. The item is in the transcript when this event is delivered.

func (*ItemEnd) EventType 

func (*ItemEnd) EventType() string

EventType returns "item_end".

type ItemStart 

type ItemStart struct {
	RunID string
	Turn  int
	Item  openresponses.Item
	// ResponseID is the ID of the response streaming the item, and empty
	// for an item the loop appended itself.
	ResponseID string
}

ItemStart announces an item entering the transcript: a prompt or queued message, an assistant item as the stream opens it, or a function call output. For an assistant item the Item is the live accumulated value and fills in as updates arrive.

func (*ItemStart) EventType 

func (*ItemStart) EventType() string

EventType returns "item_start".

type ItemUpdate 

type ItemUpdate struct {
	RunID      string
	Turn       int
	Item       openresponses.Item
	Stream     openresponses.StreamEvent
	ResponseID string
}

ItemUpdate carries one wire event for an assistant item. Stream is the openresponses event verbatim, so a front switches on the same concrete types it would use against a remote server. Item is the accumulated item so far.

func (*ItemUpdate) EventType 

func (*ItemUpdate) EventType() string

EventType returns "item_update".

type Model 

type Model = openresponses.Streamer

Model is anything that can stream an Open Responses response.

type ModelRetry added in v0.0.4 

type ModelRetry struct {
	RunID string
	Turn  int
	// Attempt is the number of the attempt that failed, from 1; the
	// next attempt is Attempt+1.
	Attempt int
	Err     error
	Delay   time.Duration
}

ModelRetry reports that a model call failed and will be attempted again after Delay, under Config.Retry. It follows the turn_start of the turn; no item of the failed attempt reached subscribers.

func (*ModelRetry) EventType added in v0.0.4 

func (*ModelRetry) EventType() string

EventType returns "model_retry".

type Option 

type Option func(*Agent)

Option configures a new Agent.

func WithTranscript 

func WithTranscript(t Transcript) Option

WithTranscript starts the agent from an existing transcript, as when resuming a session. Function calls after the last user message that have no output are pending, as they would be after the run that made them: Prompt and Continue return ErrInputRequired until Agent.Resume has answered them.

type Reason 

type Reason string

Reason says why a run ended. 

const (
	// ReasonDone means the model produced a final answer with no tool
	// calls and no queued follow-ups.
	ReasonDone Reason = "done"
	// ReasonStopped means ShouldStopAfterTurn, a terminating tool batch
	// or MaxTurns ended the run.
	ReasonStopped Reason = "stopped"
	// ReasonInputRequired means BeforeToolCall deferred one or more
	// calls to the caller; RunEnd.Pending lists them and the run
	// continues once their outputs are appended (see Agent.Resume).
	ReasonInputRequired Reason = "input_required"
	// ReasonAborted means the context was cancelled. A tool batch cut
	// off by the abort leaves its calls on RunEnd.Pending.
	ReasonAborted Reason = "aborted"
	// ReasonError means the model, a hook or a subscriber failed;
	// RunEnd.Err says which.
	ReasonError Reason = "error"
)

Run end reasons.

type ResponseEnd 

type ResponseEnd struct {
	RunID    string
	Turn     int
	Response *openresponses.Response
}

ResponseEnd carries the folded response of a turn, usage included, as soon as the stream ends and before any tool of the turn runs. Its output items have all been delivered with item_end. A response that failed is delivered here too, before the run ends with the error, so a recorder can write it.

func (*ResponseEnd) EventType 

func (*ResponseEnd) EventType() string

EventType returns "response_end".

type Retry added in v0.0.4 

type Retry struct {
	// MaxAttempts is the number of attempts per turn, the first
	// included. Zero or one means no retry.
	MaxAttempts int
	// Backoff returns how long to wait before the next attempt, given
	// the number of the attempt that failed and its error. nil means
	// [DefaultBackoff].
	Backoff func(attempt int, err error) time.Duration
	// Retryable reports whether err is worth another attempt. nil means
	// [DefaultRetryable].
	Retryable func(error) bool
}

Retry says when a failed model call is attempted again. A retry happens inside the turn: the same request is sent again after a delay, a ModelRetry event tells subscribers, and the turn_start and response_end of the turn are delivered once. Only an attempt that delivered nothing is retried: once an item of the attempt has reached subscribers, or the server has answered with a failed response, the failure is final, because the transcript or a recorder may already hold part of it. Abort cuts a delay short.

type RunEnd 

type RunEnd struct {
	RunID  string
	Items  Transcript
	Reason Reason
	// Err is set when Reason is ReasonError, and to the context error
	// when Reason is ReasonAborted, wrapping the failure of a subscriber
	// or a hook when one failed for a reason of its own while the run
	// was being aborted; errors.Is finds the context error either way.
	Err error
	// Pending lists the function calls of the run with no
	// function_call_output, in transcript order: the calls a deferred
	// decision handed to the caller when Reason is ReasonInputRequired,
	// and the calls an abort or a failure cut off before their outputs
	// were appended. It is empty for ReasonDone and ReasonStopped. The
	// transcript is a valid input again once each has an output, which
	// Agent.Resume appends.
	Pending []*openresponses.FunctionCall
}

RunEnd closes a run. Exactly one is emitted per run and nothing follows it. Items are the items the run appended to the transcript. A run refused before it started (ErrNoPrompt, ErrCannotContinue, ErrNoModel) is one RunEnd with ReasonError, an empty RunID and no other event.

func (*RunEnd) EventType 

func (*RunEnd) EventType() string

EventType returns "run_end".

type RunStart 

type RunStart struct {
	RunID string
}

RunStart opens a run.

func (*RunStart) EventType 

func (*RunStart) EventType() string

EventType returns "run_start".

type State 

type State struct {
	// Transcript is a copy of the slice; items are shared.
	Transcript Transcript
	Running    bool
	RunID      string
	Turn       int
	// Steering and FollowUps count the queued items.
	Steering  int
	FollowUps int
	// Pending lists the calls awaiting outputs, deferred or cut off by
	// an abort or a failure; Continue refuses until Resume has answered
	// them, and Prompt unless it opens with their outputs.
	Pending []*openresponses.FunctionCall
}

State is a snapshot of the agent.

type ToolAction added in v0.0.4 

type ToolAction int

ToolAction is what BeforeToolCall decides for a call. 

const (
	// Allow runs the call. It is the zero value, so a decision that only
	// rewrites Args or sets Terminate allows the call.
	Allow ToolAction = iota
	// Block refuses the call. The model sees ToolDecision.Reason as the
	// error output.
	Block
	// Defer hands the call to the caller instead of running it: the
	// other calls of the batch proceed, no output is appended for this
	// one, and the run ends with ReasonInputRequired listing it. The
	// caller appends the output later and continues.
	Defer
)

type ToolCallInfo 

type ToolCallInfo struct {
	RunID string
	Turn  int
	// Call is the function_call item as the model produced it.
	Call *openresponses.FunctionCall
	// Tool is the tool that will run, or nil when no tool has that
	// name; the call then fails with an error output unless the hook
	// blocks it first.
	Tool agenttool.Tool
	// Args are the arguments as raw JSON.
	Args json.RawMessage
}

ToolCallInfo describes a call before it runs.

type ToolDecision 

type ToolDecision struct {
	// Action allows, blocks or defers the call.
	Action ToolAction
	// Reason is the message the model sees when Action is Block.
	Reason string
	// Terminate hints the loop to stop after the batch, as a tool result
	// would. It composes with Allow and Block.
	Terminate bool
	// Args, when non-nil, replaces the arguments the tool receives.
	Args json.RawMessage
}

ToolDecision is a hook's verdict on a call.

type ToolEnd 

type ToolEnd struct {
	RunID    string
	Turn     int
	CallID   string
	Name     string
	Result   agenttool.Result
	Err      error
	Blocked  bool
	Deferred bool
}

ToolEnd carries a finished call, in completion order. Err is set when the tool failed, the arguments were invalid or no tool had the name; Blocked is set when BeforeToolCall refused the call. In both cases Result holds the error output the model sees. Deferred is set when BeforeToolCall handed the call to the caller: nothing ran, Result is empty and no output is appended. A call cancelled by an abort ends with the context error as Err; its output is not appended either, and the call is listed on RunEnd.Pending.

func (*ToolEnd) EventType 

func (*ToolEnd) EventType() string

EventType returns "tool_end".

type ToolOverride 

type ToolOverride struct {
	Result agenttool.Result
	Err    error
}

ToolOverride replaces the result of a call.

type ToolResultInfo 

type ToolResultInfo struct {
	RunID  string
	Turn   int
	Call   *openresponses.FunctionCall
	Tool   agenttool.Tool
	Args   json.RawMessage
	Result agenttool.Result
	Err    error
}

ToolResultInfo describes a completed call.

type ToolStart 

type ToolStart struct {
	RunID  string
	Turn   int
	CallID string
	Name   string
	Args   json.RawMessage
}

ToolStart announces a tool call after preflight, in the model's order.

func (*ToolStart) EventType 

func (*ToolStart) EventType() string

EventType returns "tool_start".

type ToolUpdate 

type ToolUpdate struct {
	RunID   string
	Turn    int
	CallID  string
	Name    string
	Partial agenttool.Result
}

ToolUpdate carries progress from a running tool.

func (*ToolUpdate) EventType 

func (*ToolUpdate) EventType() string

EventType returns "tool_update".

type Transcript 

type Transcript = openresponses.Items

Transcript is the conversation as the model sees it, plus app-only items that the Config.Filter removes before each call.

func DefaultFilter 

func DefaultFilter(t Transcript) Transcript

DefaultFilter drops every item whose type carries a slug prefix such as "agentturn:note", which marks an app-only extension item, and nil items. It is the Filter when Config.Filter is nil.

func TranscriptFromContext added in v0.0.4 

func TranscriptFromContext(ctx context.Context) (Transcript, bool)

TranscriptFromContext returns the transcript the loop attached to the context of a hook or a tool call: the working transcript as it stood when the batch started, the calls of the batch included. It is a snapshot; do not mutate it.

type TurnEnd 

type TurnEnd struct {
	RunID       string
	Turn        int
	Response    *openresponses.Response
	ToolResults []agenttool.Result
}

TurnEnd closes a turn with the folded response, usage included, and the tool results in the model's order.

func (*TurnEnd) EventType 

func (*TurnEnd) EventType() string

EventType returns "turn_end".

type TurnInfo 

type TurnInfo struct {
	RunID    string
	Turn     int
	Response *openresponses.Response
	// ToolResults are the results of this turn's calls in the model's
	// order, empty when the model called no tools.
	ToolResults []agenttool.Result
	// Transcript is the working transcript after the turn. It is the
	// loop's live slice; do not mutate it or keep it past the hook.
	Transcript Transcript
}

TurnInfo describes a finished turn.

type TurnStart 

type TurnStart struct {
	RunID   string
	Turn    int
	Request openresponses.Request
}

TurnStart opens a turn and carries the exact request sent to the model.

func (*TurnStart) EventType 

func (*TurnStart) EventType() string

EventType returns "turn_start".

Source Files

View all Source files

Directories

Path Synopsis
Package compact is the reference compaction Transform for agentturn: when a transcript grows past a token budget, the older part is folded into a shorter form and the recent part is kept verbatim.
 Package compact is the reference compaction Transform for agentturn: when a transcript grows past a token budget, the older part is folded into a shorter form and the recent part is kept verbatim.
front
responses
Package responses serves an agent as an Open Responses server: the loop as an openresponses.Adapter.
 Package responses serves an agent as an Open Responses server: the loop as an openresponses.Adapter.
a2a module
session module
tools
agent
Package agent wraps an agent configuration as a tool, so one loop can delegate to another in process.
 Package agent wraps an agent configuration as a tool, so one loop can delegate to another in process.
a2a module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.