LoopAgent class

A DelegatingAIAgent that re-invokes the wrapped agent in a loop until the configured LoopEvaluator set decides to stop.

After each run of the wrapped agent, the configured evaluators are asked whether to re-invoke the agent and what feedback to carry forward. When multiple evaluators are supplied they are evaluated in order; the first evaluator that asks to re-invoke wins, its feedback drives the next iteration, and the remaining evaluators are not evaluated. The loop stops only when every evaluator asks to stop, so evaluator order is priority order.

The caller's initial messages are sent to the wrapped agent exactly once. By default (when LoopAgentOptions.freshContextPerIteration is false) the loop reuses a single session and sends only the winning evaluator's feedback as the next input. When fresh context is enabled, each re-invocation restarts from the original input plus an aggregated feedback log and the session is reset. An evaluator may instead supply the exact next messages via LoopEvaluation.proceedWithMessages.

The loop is bounded by a global safety cap (LoopAgentOptions.maxIterations). If an iteration produces a pending tool-approval request, the loop stops and returns that response rather than resolving the approval automatically.

Inheritance

• Object
• AIAgent
• DelegatingAIAgent
• LoopAgent

Available extensions

• AgentEvaluationExtensions
• AIAgentExtensions
• AIAgentStructuredOutputExtensions

Constructors

LoopAgent(AIAgent innerAgent, LoopEvaluator evaluator, {LoopAgentOptions? options, LoggerFactory? loggerFactory})

Creates a LoopAgent with a single evaluator.

LoopAgent.withEvaluators(AIAgent innerAgent, Iterable<LoopEvaluator> evaluators, {LoopAgentOptions? options, LoggerFactory? loggerFactory})

Creates a LoopAgent with one or more evaluators, evaluated in order.

Properties

debuggerDisplay → String

no setter, inherited

description → String?

Gets a description of the agent's purpose and capabilities.

no setter, inherited

hashCode → int

The hash code for this object.

no setter, inherited

id → String

Gets the unique identifier for this agent instance.

no setter, inherited

idCore → String?

A custom identifier for the agent, which derived classes can override.

no setter, inherited

innerAgent → AIAgent

The underlying agent that receives delegated operations.

final, inherited

name → String?

Gets the human-readable name of the agent.

no setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

asAIFunction({AIFunctionFactoryOptions? options, AgentSession? session}) → AIFunction

Available on AIAgent, provided by the AIAgentExtensions extension

Creates an AIFunction that runs this AIAgent.

asBuilder() → AIAgentBuilder

Available on AIAgent, provided by the AIAgentExtensions extension

Creates a new AIAgentBuilder using this agent as the pipeline root.

createSession({CancellationToken? cancellationToken}) → Future<AgentSession>

Creates a new conversation session compatible with this agent.

inherited

createSessionCore({CancellationToken? cancellationToken}) → Future<AgentSession>

Core implementation of session creation logic.

inherited

deserializeSession(dynamic serializedState, {Object? jsonSerializerOptions, CancellationToken? cancellationToken}) → Future<AgentSession>

Deserializes an agent session from a previously serialized state.

inherited

deserializeSessionCore(dynamic serializedState, {Object? jsonSerializerOptions, CancellationToken? cancellationToken}) → Future<AgentSession>

Core implementation of session deserialization.

inherited

evaluate(Iterable<String> queries, String evalName, Iterable<String>? expectedOutput, Iterable<Iterable<ExpectedToolCall>>? expectedToolCalls, CancellationToken cancellationToken, {AgentEvaluator? evaluator, ConversationSplitter? splitter, int? numRepetitions, ChatConfiguration? chatConfiguration, Iterable<AgentEvaluator>? evaluators, Iterable<AgentResponse>? responses}) → Future<AgentEvaluationResults>

Available on AIAgent, provided by the AgentEvaluationExtensions extension

Evaluates an agent by running it against test queries and scoring the responses.

evaluateWithMeai(Iterable<String> queries, String evalName, Evaluator evaluator, ChatConfiguration chatConfiguration, {Iterable<String>? expectedOutput, Iterable<Iterable<ExpectedToolCall>>? expectedToolCalls, ConversationSplitter? splitter, int? numRepetitions, CancellationToken? cancellationToken}) → Future<AgentEvaluationResults>

Available on AIAgent, provided by the AgentEvaluationExtensions extension

Wraps an MEAI Evaluator and evaluates this agent with it.

getService(Type serviceType, {Object? serviceKey}) → Object?

Returns a service of the specified serviceType, or null.

inherited

getServiceOf<T extends Object>({Object? serviceKey}) → T?

Returns a service of type T, or null.

inherited

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

run(AgentSession? session, AgentRunOptions? options, {CancellationToken? cancellationToken, String? message, Iterable<ChatMessage>? messages}) → Future<AgentResponse>

Runs the agent with the provided messages and returns the full response.

inherited

runCore(Iterable<ChatMessage> messages, {AgentSession? session, AgentRunOptions? options, CancellationToken? cancellationToken}) → Future<AgentResponse>

Core implementation of the agent invocation logic.

override

runCoreStreaming(Iterable<ChatMessage> messages, {AgentSession? session, AgentRunOptions? options, CancellationToken? cancellationToken}) → Stream<AgentResponseUpdate>

Core implementation of the agent streaming invocation logic.

override

runStreaming(AgentSession? session, AgentRunOptions? options, {CancellationToken? cancellationToken, String? message, Iterable<ChatMessage>? messages}) → Stream<AgentResponseUpdate>

Runs the agent in streaming mode.

inherited

runTyped<T>(AgentSession? session, {AgentRunOptions? options, CancellationToken? cancellationToken, String? message, Iterable<ChatMessage>? messages}) → Future<AgentResponseOf<T>>

Available on AIAgent, provided by the AIAgentStructuredOutputExtensions extension

Runs the agent and attempts to deserialize the response as type T.

serializeSession(AgentSession session, {Object? jsonSerializerOptions, CancellationToken? cancellationToken}) → Future

Serializes an agent session to a JSON-compatible map.

inherited

serializeSessionCore(AgentSession session, {Object? jsonSerializerOptions, CancellationToken? cancellationToken}) → Future

Core implementation of session serialization.

inherited

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Constants

defaultMaxIterations → const int

The default value used for LoopAgentOptions.maxIterations when none is specified.