Documentation
¶
Overview ¶
Package executor holds the contract shared by the agent executors (claudeexecutor, googleexecutor, chatcompletionexecutor): the conditions every executor reports the same way, so a caller can handle them without knowing which provider ran the agent.
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
var ErrInputTooLarge = errors.New("agent request exceeds model input budget")
ErrInputTooLarge reports that a model request exceeded the input budget of the model's serving context window and was rejected before the provider was called. Resending the same conversation fails the same way, so callers should treat it as non-retriable. Executors that enforce an input budget wrap it, so a caller can recognize the condition with errors.Is without importing a provider-specific error type.
var ErrMaxTurns = errors.New("agent exceeded maximum conversation turns")
ErrMaxTurns reports that an agent run stopped because it reached its conversation-turn budget before the agent submitted a result. Every executor wraps it, so a caller can recognize the condition with errors.Is regardless of which provider ran the agent and decide what to do with the run's partial work.
Functions ¶
This section is empty.
Types ¶
type MaxTurnsError ¶ added in v0.11.19
type MaxTurnsError struct {
// Turns is the turn budget the run enforced. For a resumed or continued
// run that is the budget of that run alone, not of the whole conversation.
Turns int
// Continuation is the conversation as it stood after its last turn, in
// the envelope shape a resume reads, so an executor that can continue a
// conversation picks it up at a larger budget instead of starting over.
// It carries no pending tool calls and no remaining budget: nothing is
// parked, and the budget is the continuing executor's. Nil means the
// executor that ran out cannot continue the conversation.
//
// It carries no Deadline either, because it is meant to be continued in
// the same process. A caller that persists it stamps its own Deadline,
// which ValidateForContinue then enforces.
//
// It is excluded from JSON: its provider state is the whole transcript
// (system prompt, tool results, repository content), which must not leak
// into a status record that marshals the error.
Continuation *checkpoint.Envelope `json:"-"`
}
MaxTurnsError is the ErrMaxTurns an executor returns when it can say more than the sentinel does. It unwraps to ErrMaxTurns and reads the same, so a caller that matches with errors.Is is unaffected; one that wants the run's partial work extracts it with errors.AsType.
Example ¶
A MaxTurnsError still matches ErrMaxTurns; a caller that can continue the conversation reads its Continuation, and one that cannot sees nil.
package main
import (
"errors"
"fmt"
"chainguard.dev/driftlessaf/agents/executor"
)
func main() {
var err error = &executor.MaxTurnsError{Turns: 16}
fmt.Println(errors.Is(err, executor.ErrMaxTurns))
fmt.Println(err)
if exhausted, ok := errors.AsType[*executor.MaxTurnsError](err); ok {
fmt.Println(exhausted.Continuation != nil)
}
}
Output: true agent exceeded maximum conversation turns (16) false
Example (Json) ¶
A MaxTurnsError marshals without its Continuation: the transcript in its provider state never reaches a status record that serializes the error.
package main
import (
"encoding/json"
"fmt"
"chainguard.dev/driftlessaf/agents/checkpoint"
"chainguard.dev/driftlessaf/agents/executor"
)
func main() {
err := &executor.MaxTurnsError{Turns: 16, Continuation: &checkpoint.Envelope{
ProviderState: json.RawMessage(`{"system":"the whole transcript"}`),
}}
b, merr := json.Marshal(err)
if merr != nil {
fmt.Println(merr)
return
}
fmt.Println(string(b))
}
Output: {"Turns":16}
func (*MaxTurnsError) Error ¶ added in v0.11.19
func (e *MaxTurnsError) Error() string
Error reads as the wrapped sentinel with the enforced budget appended.
func (*MaxTurnsError) Unwrap ¶ added in v0.11.19
func (e *MaxTurnsError) Unwrap() error
Unwrap returns ErrMaxTurns.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
Package claudeexecutor provides a generic executor for Claude-based agents that reduces boilerplate while maintaining flexibility for agent-specific logic.
|
Package claudeexecutor provides a generic executor for Claude-based agents that reduces boilerplate while maintaining flexibility for agent-specific logic. |
|
Package googleexecutor provides a generic Google AI (Gemini) executor for AI agents.
|
Package googleexecutor provides a generic Google AI (Gemini) executor for AI agents. |
|
internal
|
|
|
execshared
Package execshared holds behavior shared by the executor implementations (claudeexecutor, googleexecutor, chatcompletionexecutor) so each backend applies identical semantics: prompt-suffix handling, resource-label defaults, the submit routing predicate, the bounded tool-call dispatch pool, and the submit-gate validation tail.
|
Package execshared holds behavior shared by the executor implementations (claudeexecutor, googleexecutor, chatcompletionexecutor) so each backend applies identical semantics: prompt-suffix handling, resource-label defaults, the submit routing predicate, the bounded tool-call dispatch pool, and the submit-gate validation tail. |
|
telemetry
Package telemetry provides the shared GenAI metrics recorder used by the executor implementations (claudeexecutor, googleexecutor, chatcompletionexecutor) so each backend emits identically-shaped metrics, differing only in the gen_ai.provider.name attribute.
|
Package telemetry provides the shared GenAI metrics recorder used by the executor implementations (claudeexecutor, googleexecutor, chatcompletionexecutor) so each backend emits identically-shaped metrics, differing only in the gen_ai.provider.name attribute. |
|
openai
|
|
|
chatcompletionexecutor
Package chatcompletionexecutor provides a multi-turn conversation executor for OpenAI-compatible chat completion APIs, including Vertex AI's partner model endpoint.
|
Package chatcompletionexecutor provides a multi-turn conversation executor for OpenAI-compatible chat completion APIs, including Vertex AI's partner model endpoint. |
|
responsesexecutor
Package responsesexecutor runs stateless, streaming Responses conversations with client-side tools and validated terminal submissions.
|
Package responsesexecutor runs stateless, streaming Responses conversations with client-side tools and validated terminal submissions. |
|
Package retry provides exponential backoff retry logic for handling transient errors.
|
Package retry provides exponential backoff retry logic for handling transient errors. |
|
Package systemone calls System One compatible models through their serving providers.
|
Package systemone calls System One compatible models through their serving providers. |