LoopAgent Class
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
A DelegatingAIAgent that re-invokes the wrapped agent in a loop until the configured LoopEvaluator set decides to stop.
public sealed class LoopAgent : Microsoft.Agents.AI.DelegatingAIAgenttype LoopAgent = class
inherit DelegatingAIAgentPublic NotInheritable Class LoopAgent
Inherits DelegatingAIAgent- Inheritance
Remarks
After each run of the wrapped agent, the configured evaluators are asked whether to re-invoke the agent and what feedback to carry forward. This enables patterns such as iterative refinement, working through a task list, or judging whether the original request was answered. Out-of-the-box evaluators include AIJudgeLoopEvaluator, CompletionMarkerLoopEvaluator, and DelegateLoopEvaluator.
When multiple evaluators are supplied they are evaluated in order after each iteration. 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. Consequently, evaluator order is priority order and Stop() means "this evaluator does not request continuation" rather than a veto that terminates the loop; place stop-only guards accordingly.
The caller's initial messages are sent to the wrapped agent exactly once. By default (when FreshContextPerIteration is false) the loop reuses a single session and sends only the winning evaluator's feedback as the next input, letting the agent continue from session history. When FreshContextPerIteration is true, each re-invocation restarts from the original input messages plus an aggregated feedback log, and the session is reset for each iteration: a loop-owned session is created anew, while a caller-supplied session is restored from a snapshot taken at the start of the run (so the wrapped agent must support session serialization). An evaluator may instead supply the exact next messages via ContinueWithMessages(IEnumerable<ChatMessage>), bypassing this construction.
The loop is bounded by a global safety cap (MaxIterations) regardless of the evaluators. If an iteration produces a pending tool-approval request, the loop stops and returns that response to the caller rather than attempting to resolve the approval automatically.
A non-streaming run returns, by default, a single AgentResponse that aggregates the full transcript in order: the on-behalf-of messages the loop injected for each re-invocation followed by that iteration's response messages. The caller's original input messages are not echoed. Set NonStreamingReturnsLastResponseOnly to instead return only the final iteration's response. A streaming run always yields every iteration's updates, emitting the injected on-behalf-of messages as updates before each re-invocation. The injected messages can be attributed with OnBehalfOfAuthorName, or omitted from the surfaced output entirely with ExcludeOnBehalfOfMessages.
Constructors
| Name | Description |
|---|---|
| LoopAgent(AIAgent, IEnumerable<LoopEvaluator>, LoopAgentOptions, ILoggerFactory) |
Initializes a new instance of the LoopAgent class with one or more evaluators. |
| LoopAgent(AIAgent, LoopEvaluator, LoopAgentOptions, ILoggerFactory) |
Initializes a new instance of the LoopAgent class with a single evaluator. |
Fields
| Name | Description |
|---|---|
| DefaultMaxIterations |
The default value used for MaxIterations when none is specified. |
Properties
| Name | Description |
|---|---|
| Description |
Gets a description of the agent's purpose, capabilities, or behavior. (Inherited from DelegatingAIAgent) |
| Id |
Gets the unique identifier for this agent instance. (Inherited from AIAgent) |
| IdCore |
Gets a custom identifier for the agent, which can be overridden by derived classes. (Inherited from DelegatingAIAgent) |
| InnerAgent |
Gets the inner agent instance that receives delegated operations. (Inherited from DelegatingAIAgent) |
| Name |
Gets the human-readable name of the agent. (Inherited from DelegatingAIAgent) |
Methods
| Name | Description |
|---|---|
| CreateSessionAsync(CancellationToken) |
Creates a new conversation session that is compatible with this agent. (Inherited from AIAgent) |
| CreateSessionCoreAsync(CancellationToken) |
Core implementation of session creation logic. (Inherited from DelegatingAIAgent) |
| DeserializeSessionAsync(JsonElement, JsonSerializerOptions, CancellationToken) |
Deserializes an agent session from its JSON serialized representation. (Inherited from AIAgent) |
| DeserializeSessionCoreAsync(JsonElement, JsonSerializerOptions, CancellationToken) |
Core implementation of session deserialization logic. (Inherited from DelegatingAIAgent) |
| GetService(Type, Object) |
Asks the AIAgent for an object of the specified type |
| GetService<TService>(Object) |
Asks the AIAgent for an object of type |
| RunAsync(AgentSession, AgentRunOptions, CancellationToken) |
Run the agent with no message assuming that all required instructions are already provided to the agent or on the session. (Inherited from AIAgent) |
| RunAsync(ChatMessage, AgentSession, AgentRunOptions, CancellationToken) |
Runs the agent with a single chat message. (Inherited from AIAgent) |
| RunAsync(IEnumerable<ChatMessage>, AgentSession, AgentRunOptions, CancellationToken) |
Runs the agent with a collection of chat messages, providing the core invocation logic that all other overloads delegate to. (Inherited from AIAgent) |
| RunAsync(String, AgentSession, AgentRunOptions, CancellationToken) |
Runs the agent with a text message from the user. (Inherited from AIAgent) |
| RunAsync<T>(AgentSession, JsonSerializerOptions, AgentRunOptions, CancellationToken) |
Run the agent with no message assuming that all required instructions are already provided to the agent or on the session, and requesting a response of the specified type |
| RunAsync<T>(ChatMessage, AgentSession, JsonSerializerOptions, AgentRunOptions, CancellationToken) |
Runs the agent with a single chat message, requesting a response of the specified type |
| RunAsync<T>(IEnumerable<ChatMessage>, AgentSession, JsonSerializerOptions, AgentRunOptions, CancellationToken) |
Runs the agent with a collection of chat messages, requesting a response of the specified type |
| RunAsync<T>(String, AgentSession, JsonSerializerOptions, AgentRunOptions, CancellationToken) |
Runs the agent with a text message from the user, requesting a response of the specified type |
| RunCoreAsync(IEnumerable<ChatMessage>, AgentSession, AgentRunOptions, CancellationToken) |
Core implementation of the agent invocation logic with a collection of chat messages. (Inherited from DelegatingAIAgent) |
| RunCoreStreamingAsync(IEnumerable<ChatMessage>, AgentSession, AgentRunOptions, CancellationToken) |
Core implementation of the agent streaming invocation logic with a collection of chat messages. (Inherited from DelegatingAIAgent) |
| RunStreamingAsync(AgentSession, AgentRunOptions, CancellationToken) |
Runs the agent in streaming mode without providing new input messages, relying on existing context and instructions. (Inherited from AIAgent) |
| RunStreamingAsync(ChatMessage, AgentSession, AgentRunOptions, CancellationToken) |
Runs the agent in streaming mode with a single chat message. (Inherited from AIAgent) |
| RunStreamingAsync(IEnumerable<ChatMessage>, AgentSession, AgentRunOptions, CancellationToken) |
Runs the agent in streaming mode with a collection of chat messages, providing the core streaming invocation logic. (Inherited from AIAgent) |
| RunStreamingAsync(String, AgentSession, AgentRunOptions, CancellationToken) |
Runs the agent in streaming mode with a text message from the user. (Inherited from AIAgent) |
| SerializeSessionAsync(AgentSession, JsonSerializerOptions, CancellationToken) |
Serializes an agent session to its JSON representation. (Inherited from AIAgent) |
| SerializeSessionCoreAsync(AgentSession, JsonSerializerOptions, CancellationToken) |
Core implementation of session serialization logic. (Inherited from DelegatingAIAgent) |