agentturn

package module
v0.0.6 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"
	EventModelBlocked = "model_blocked"
	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")
	// ErrGuard is what a ShouldStopAfterTurn hook wraps to end the run
	// as a policy stop rather than a failure: ReasonStopped with
	// StopGuard, the error on RunEnd.Err.
	ErrGuard = errors.New("agentturn: guard stopped the run")
)

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 ContextWithTrigger added in v0.0.6 

func ContextWithTrigger(ctx context.Context, t Trigger) context.Context

ContextWithTrigger attaches a Trigger to ctx. A run started with that context, through Run, Continue or an Agent, carries it on its RunStart, so a recorder can write what caused the run without the loop learning what a cron job or a channel is.

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 and answer every function call it holds. 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 PendingCalls added in v0.0.6 

func PendingCalls(pending []PendingCall) []*openresponses.FunctionCall

PendingCalls returns the calls of pending, in order.

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, or ErrInputRequired for a transcript with a function call that neither the transcript nor the prompts' leading outputs answer) 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. The queues are untouched: anything steered or queued and not yet appended goes to the next run.

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. The queue has the same life and the same caveat about subscribers as Agent.Steer.

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. A Trigger attached to ctx with ContextWithTrigger is carried on the run's RunStart.

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, then the notes of the answers that carry one, as user messages. 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, the outputs are appended in the calls' transcript order and their notes after them, and anything steered in meanwhile follows. A batch whose results set Terminate ends the run with ReasonStopped without calling the model, and so does any answer built with Refuse. Otherwise the model is 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 the queues are kept, so anything steered or queued under the old configuration goes to the next run under the new one; 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 and go to the next run on the new transcript; a host that does not want them there reads them from Agent.State first.

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.

The queues live in memory: an item accepted here is in no record until a run appends it, and it survives Agent.Abort, [SetConfig] and [SetTranscript] but not the process. A host that promises the sender it has the item persists it itself, reading the queues back from Agent.State, and queues it again after a restart.

A steered item is appended with its own item events, which reach every subscriber. A subscriber that steers in reaction to an event the steered item itself produces, an item_end during a run for instance, feeds the run forever, and nothing reports it: the loop cannot tell a reaction from a fresh input. Steer from a front, a monitor or another goroutine, or from a subscriber only on events it can tell apart from its own items, such as a tool_end or a specific item type it never steers.

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
	// Note is what the user said when answering: it is appended as a
	// user message after the outputs of every answer of the Resume, so
	// the model reads the result and the note together, in that order,
	// in the same turn.
	Note string
	// Terminate ends the run with ReasonStopped and StopRefused once
	// every answer is in, without calling the model, for a refusal that
	// should end the turn so the user can say what to do instead. The
	// outputs are still appended, so the transcript stays a valid input.
	Terminate bool
}

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, ApproveWith or Refuse, and attach what the user said with Answer.WithNote.

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.

func Refuse added in v0.0.6 

func Refuse(out *openresponses.FunctionCallOutput) Answer

Refuse answers a pending call with out and ends the run instead of calling the model: Output with Terminate set.

func (Answer) WithNote added in v0.0.6 

func (a Answer) WithNote(note string) Answer

WithNote returns the answer with note attached.

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

	// BeforeTurn runs at the start of each turn, before the request is
	// built, and returns items the loop appends to the transcript with
	// their item events, as it appends a queued message: the time, a
	// reminder due, the state of the environment, whatever the model
	// needs this turn. The items are then facts about the transcript, so
	// a recorded session rebuilds the request they were part of, which
	// injection through Transform cannot give. nil or no items appends
	// nothing. A guard on the request itself belongs in BeforeModelCall.
	BeforeTurn func(context.Context, TurnStartInfo) (openresponses.Items, error)

	// 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 is one the record cannot describe, so
	// a session recorder writes that call without a request hash; a
	// change to a setting is recorded as a config delta. A hook that
	// refuses the call ends the run with ReasonError after a
	// [ModelBlocked] event carrying the request as built; a guard that
	// calls a model is on the critical path of every first token, since
	// the request is not final until the hook returns.
	BeforeModelCall func(context.Context, *openresponses.Request) error

	// OutputGuard runs on each assistant message as the stream completes
	// it, after output_item.done and before the message is appended to
	// the transcript and delivered as item_end, and may replace it with
	// another message, a placeholder for one that must not reach the
	// user, the transcript or the record. nil keeps the message. The
	// deltas of the original have already been delivered as item_update,
	// so a front that must not show withheld text renders on item_end.
	// Function calls, reasoning and every other output item never reach
	// it, so a replay still has what it needs; a guard that also wants
	// to end the run returns an error wrapping [ErrGuard] from
	// ShouldStopAfterTurn, which sees the turn with TurnInfo.Final set.
	OutputGuard func(context.Context, OutputInfo) (*openresponses.Message, 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. An override replaces the
	// result before tool_end is delivered and before the output is
	// appended, so no subscriber and no recorder sees what the tool
	// returned: bytes cut here exist nowhere afterwards. A cap on tool
	// output therefore belongs in the tool, the only place the whole
	// output exists, which can cut the middle so both ends survive and
	// leave the full bytes where the model can read them, naming that
	// place in the text it returns; a Transform, which shapes one call
	// and never replaces the transcript, is the other placement that
	// keeps the record whole. This hook is for a policy on the result
	// the model sees, not for saving space.
	AfterToolCall func(context.Context, ToolResultInfo) (*ToolOverride, error)
	// ShouldStopAfterTurn ends the run after a turn even when the model
	// requested tools: true ends it with ReasonStopped and StopHook. An
	// error wrapping [ErrGuard] ends it with ReasonStopped, StopGuard
	// and the error on RunEnd.Err, so a policy that stops a run is told
	// apart from a failure; any other error ends it with ReasonError.
	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, ModelBlocked, 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 ModelBlocked added in v0.0.6 

type ModelBlocked struct {
	RunID   string
	Turn    int
	Request openresponses.Request
	Err     error
}

ModelBlocked reports that Config.BeforeModelCall refused the turn's request, so no call was made: Request is the request as built when the hook ran and Err is the hook's error. It is the last event before the run ends with ReasonError, in place of the turn_start the call would have had, so a recorder can write the call that was refused as distinct from one that was made and failed.

func (*ModelBlocked) EventType added in v0.0.6 

func (*ModelBlocked) EventType() string

EventType returns "model_blocked".

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 anywhere in it that have no output are pending, with PendingUnknown as their reason since the loop cannot say whether they ran, as they would be after the run that made them: Prompt and Continue return ErrInputRequired until Agent.Resume has answered them, or a Prompt opens with their outputs.

type OutputInfo added in v0.0.6 

type OutputInfo struct {
	RunID      string
	Turn       int
	ResponseID string
	// Message is the message as the model produced it.
	Message *openresponses.Message
}

OutputInfo describes an assistant message the stream has completed, for Config.OutputGuard.

type PendingCall added in v0.0.6 

type PendingCall struct {
	Call   *openresponses.FunctionCall
	Reason PendingReason
}

PendingCall is a function call with no output and the reason it has none.

type PendingReason added in v0.0.6 

type PendingReason string

PendingReason says why a call has no output. 

const (
	// PendingDeferred: BeforeToolCall handed the call to the caller and
	// nothing has answered it. The tool did not run.
	PendingDeferred PendingReason = "deferred"
	// PendingAborted: the run was aborted or failed while the call was
	// in flight, after its tool_start. The tool may have run to
	// completion, so its side effect may have happened.
	PendingAborted PendingReason = "aborted"
	// PendingUnknown: the call was found without an output in a
	// transcript the agent was seeded with, so the loop cannot say
	// whether it ran. A session recorded with dispatch entries can.
	PendingUnknown PendingReason = "unknown"
)

Pending reasons.

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 the loop chose not to call the model again:
	// ShouldStopAfterTurn, a terminating tool result, MaxTurns or a
	// refusal on Resume. RunEnd.Cause says which.
	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
	// Cause says what stopped the run when Reason is ReasonStopped, and
	// is empty otherwise.
	Cause StopCause
	// Err is set when Reason is ReasonError; 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, so errors.Is finds the context error either way;
	// and to the guard's error when Reason is ReasonStopped with Cause
	// StopGuard.
	Err error
	// Pending lists the function calls in the transcript with no
	// function_call_output, in transcript order, each with why: 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 []PendingCall
}

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
	Source  Source
	Trigger Trigger
}

RunStart opens a run. Source says whether the run answers pending calls or begins from input; Trigger is what the caller attached to the context with ContextWithTrigger, zero when nothing was.

func (*RunStart) EventType 

func (*RunStart) EventType() string

EventType returns "run_start".

type Source added in v0.0.6 

type Source string

Source says what a run began from, in the terms the session format records: an input, or the answers to calls an earlier run left pending. 

const (
	// SourceInput is a run that begins with new input, or with nothing:
	// Prompt, Continue, and the low-level Run and Continue.
	SourceInput Source = "input"
	// SourceResume is a run that begins by answering a call that was
	// pending when it started: Resume, and a Prompt that opens with the
	// outputs of the pending calls.
	SourceResume Source = "resume"
)

Run sources.

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; Steered and Queued
	// are the items themselves, copies of the queues, so a host can
	// persist what it accepted and queue it again after a restart.
	Steering  int
	FollowUps int
	Steered   openresponses.Items
	Queued    openresponses.Items
	// Pending lists the calls awaiting outputs, each with why: deferred,
	// cut off by an abort or a failure, or found unanswered in a seeded
	// transcript. Continue refuses until Resume has answered them, and
	// Prompt unless it opens with their outputs.
	Pending []PendingCall
}

State is a snapshot of the agent.

type StopCause added in v0.0.6 

type StopCause string

StopCause says what ended a run with ReasonStopped. 

const (
	// StopMaxTurns: Config.MaxTurns was reached with tools still being
	// called.
	StopMaxTurns StopCause = "max_turns"
	// StopHook: ShouldStopAfterTurn returned true.
	StopHook StopCause = "hook"
	// StopGuard: ShouldStopAfterTurn returned an error wrapping
	// [ErrGuard]; the error is on RunEnd.Err.
	StopGuard StopCause = "guard"
	// StopTerminate: every result of the batch set Terminate, so the
	// tools answered on the model's behalf.
	StopTerminate StopCause = "terminate"
	// StopPartialTerminate: some results of the batch set Terminate and
	// others did not. The run ends so the host can act on the call that
	// asked to end it; the other calls ran and their outputs are in the
	// transcript.
	StopPartialTerminate StopCause = "partial_terminate"
	// StopRefused: an answer built with [Refuse] ended the run instead
	// of calling the model.
	StopRefused StopCause = "refused"
)

Stop causes.

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
	// Batch is every call of the turn in the model's order and Index is
	// this call's position in it. BeforeToolCall runs for each call of
	// the batch, in order, before any call executes, so a hook that
	// defers one call can defer the rest of the batch and hold all of
	// it for the answer.
	Batch []*openresponses.FunctionCall
	Index int
}

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
	// By names who decided, for the record: the session format knows
	// "human" for a person the hook waited on, "policy" for a rule it
	// evaluated on its own and "agent" for another model. Empty is read
	// as policy. The loop does not use it.
	By string
	// Note is text the model sees with the result: it is appended after
	// the batch's outputs as a developer message, so the model reads the
	// result and the note together, in that order, in the same turn. It
	// applies to an allowed call; a blocked call carries its Reason.
	Note string
}

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
	Decision *ToolDecision
}

ToolStart announces a tool call after preflight, in the model's order. Args are the arguments the tool receives, which a decision may have rewritten; the function_call item in the transcript keeps the model's. Decision is what BeforeToolCall returned for the call, nil when there was no hook or it returned nil; for a call approved through Agent.Resume it carries the caller's arguments, when they gave any, and nothing else.

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 Trigger added in v0.0.6 

type Trigger struct {
	Kind string
	Ref  string
}

Trigger names what caused a run, in the caller's own terms: a cron job, a channel message, a user's turn. The loop learns nothing from it; it carries the value from ContextWithTrigger to RunStart so a recorder can write it. Kind is the category and Ref the instance; a recorder joins them as "kind:ref" when both are set.

func TriggerFromContext added in v0.0.6 

func TriggerFromContext(ctx context.Context) Trigger

TriggerFromContext returns the trigger attached to ctx, or the zero Trigger.

func (Trigger) IsZero added in v0.0.6 

func (t Trigger) IsZero() bool

IsZero reports whether the trigger names nothing.

func (Trigger) String added in v0.0.6 

func (t Trigger) String() string

String returns "kind:ref", or whichever of the two is set.

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
	// Final is set when the model called no tools, so the response is
	// the run's answer unless a queued follow-up keeps it going.
	Final bool
	// 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
	Inputs  openresponses.Items
}

TurnStart opens a turn and carries the exact request sent to the model. Inputs are the items appended to the transcript since the previous turn's response, or since the run started for the first turn: the tool outputs, the steered and queued messages, the items BeforeTurn added. They are what this turn's response answers, so a front that routes replies to the message that caused them reads them here rather than counting item events between turns.

func (*TurnStart) EventType 

func (*TurnStart) EventType() string

EventType returns "turn_start".

type TurnStartInfo added in v0.0.6 

type TurnStartInfo struct {
	RunID string
	Turn  int
	// Transcript is the working transcript as the turn starts. It is the
	// loop's live slice; do not mutate it or keep it past the hook.
	Transcript Transcript
}

TurnStartInfo describes a turn about to start, for Config.BeforeTurn.

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.