AIAgent.RunAsync Method
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.
Overloads
| Name | Description |
|---|---|
| RunAsync(String, AgentSession, AgentRunOptions, CancellationToken) |
Runs the agent with a text message from the user. |
| 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. |
| RunAsync(ChatMessage, AgentSession, AgentRunOptions, CancellationToken) |
Runs the agent with a single chat message. |
| 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. |
| 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 |
RunAsync(String, AgentSession, AgentRunOptions, CancellationToken)
Runs the agent with a text message from the user.
public System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentResponse> RunAsync(string message, Microsoft.Agents.AI.AgentSession? session = default, Microsoft.Agents.AI.AgentRunOptions? options = default, System.Threading.CancellationToken cancellationToken = default);member this.RunAsync : string * Microsoft.Agents.AI.AgentSession * Microsoft.Agents.AI.AgentRunOptions * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentResponse>Public Function RunAsync (message As String, Optional session As AgentSession = Nothing, Optional options As AgentRunOptions = Nothing, Optional cancellationToken As CancellationToken = Nothing) As Task(Of AgentResponse)Parameters
- message
- String
The user message to send to the agent.
- session
- AgentSession
The conversation session to use for this invocation. If null, a new session will be created.
The session will be updated with the input message and any response messages generated during invocation.
- options
- AgentRunOptions
Optional configuration parameters for controlling the agent's invocation behavior.
- cancellationToken
- CancellationToken
The CancellationToken to monitor for cancellation requests. The default is None.
Returns
A task that represents the asynchronous operation. The task result contains an AgentResponse with the agent's output.
Exceptions
message is null, empty, or contains only whitespace.
Remarks
The provided text will be wrapped in a ChatMessage with the User role before being sent to the agent. This is a convenience method for simple text-based interactions.
Applies to
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.
public System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentResponse> RunAsync(System.Collections.Generic.IEnumerable<Microsoft.Extensions.AI.ChatMessage> messages, Microsoft.Agents.AI.AgentSession? session = default, Microsoft.Agents.AI.AgentRunOptions? options = default, System.Threading.CancellationToken cancellationToken = default);member this.RunAsync : seq<Microsoft.Extensions.AI.ChatMessage> * Microsoft.Agents.AI.AgentSession * Microsoft.Agents.AI.AgentRunOptions * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentResponse>Public Function RunAsync (messages As IEnumerable(Of ChatMessage), Optional session As AgentSession = Nothing, Optional options As AgentRunOptions = Nothing, Optional cancellationToken As CancellationToken = Nothing) As Task(Of AgentResponse)Parameters
- messages
- IEnumerable<ChatMessage>
The collection of messages to send to the agent for processing.
- session
- AgentSession
The conversation session to use for this invocation. If null, a new session will be created.
The session will be updated with the input messages and any response messages generated during invocation.
- options
- AgentRunOptions
Optional configuration parameters for controlling the agent's invocation behavior.
- cancellationToken
- CancellationToken
The CancellationToken to monitor for cancellation requests. The default is None.
Returns
A task that represents the asynchronous operation. The task result contains an AgentResponse with the agent's output.
Remarks
This method delegates to RunCoreAsync(IEnumerable<ChatMessage>, AgentSession, AgentRunOptions, CancellationToken) to perform the actual agent invocation. It handles collections of messages, allowing for complex conversational scenarios including multi-turn interactions, function calls, and context-rich conversations.
The messages are processed in the order provided and become part of the conversation history. The agent's response will also be added to session if one is provided.
Applies to
RunAsync(ChatMessage, AgentSession, AgentRunOptions, CancellationToken)
Runs the agent with a single chat message.
public System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentResponse> RunAsync(Microsoft.Extensions.AI.ChatMessage message, Microsoft.Agents.AI.AgentSession? session = default, Microsoft.Agents.AI.AgentRunOptions? options = default, System.Threading.CancellationToken cancellationToken = default);member this.RunAsync : Microsoft.Extensions.AI.ChatMessage * Microsoft.Agents.AI.AgentSession * Microsoft.Agents.AI.AgentRunOptions * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentResponse>Public Function RunAsync (message As ChatMessage, Optional session As AgentSession = Nothing, Optional options As AgentRunOptions = Nothing, Optional cancellationToken As CancellationToken = Nothing) As Task(Of AgentResponse)Parameters
- message
- ChatMessage
The chat message to send to the agent.
- session
- AgentSession
The conversation session to use for this invocation. If null, a new session will be created.
The session will be updated with the input message and any response messages generated during invocation.
- options
- AgentRunOptions
Optional configuration parameters for controlling the agent's invocation behavior.
- cancellationToken
- CancellationToken
The CancellationToken to monitor for cancellation requests. The default is None.
Returns
A task that represents the asynchronous operation. The task result contains an AgentResponse with the agent's output.
Exceptions
message is null.
Applies to
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.
public System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentResponse> RunAsync(Microsoft.Agents.AI.AgentSession? session = default, Microsoft.Agents.AI.AgentRunOptions? options = default, System.Threading.CancellationToken cancellationToken = default);member this.RunAsync : Microsoft.Agents.AI.AgentSession * Microsoft.Agents.AI.AgentRunOptions * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentResponse>Public Function RunAsync (Optional session As AgentSession = Nothing, Optional options As AgentRunOptions = Nothing, Optional cancellationToken As CancellationToken = Nothing) As Task(Of AgentResponse)Parameters
- session
- AgentSession
The conversation session to use for this invocation. If null, a new session will be created.
The session will be updated with any response messages generated during invocation.
- options
- AgentRunOptions
Optional configuration parameters for controlling the agent's invocation behavior.
- cancellationToken
- CancellationToken
The CancellationToken to monitor for cancellation requests. The default is None.
Returns
A task that represents the asynchronous operation. The task result contains an AgentResponse with the agent's output.
Remarks
This overload is useful when the agent has sufficient context from previous messages in the session or from its initial configuration to generate a meaningful response without additional input.
Applies to
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 T.
public System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentResponse<T>> RunAsync<T>(Microsoft.Agents.AI.AgentSession? session = default, System.Text.Json.JsonSerializerOptions? serializerOptions = default, Microsoft.Agents.AI.AgentRunOptions? options = default, System.Threading.CancellationToken cancellationToken = default);member this.RunAsync : Microsoft.Agents.AI.AgentSession * System.Text.Json.JsonSerializerOptions * Microsoft.Agents.AI.AgentRunOptions * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentResponse<'T>>Public Function RunAsync(Of T) (Optional session As AgentSession = Nothing, Optional serializerOptions As JsonSerializerOptions = Nothing, Optional options As AgentRunOptions = Nothing, Optional cancellationToken As CancellationToken = Nothing) As Task(Of AgentResponse(Of T))Type Parameters
- T
The type of structured output to request.
Parameters
- session
- AgentSession
The conversation session to use for this invocation. If null, a new session will be created.
The session will be updated with any response messages generated during invocation.
- serializerOptions
- JsonSerializerOptions
Optional JSON serializer options to use for deserializing the response.
- options
- AgentRunOptions
Optional configuration parameters for controlling the agent's invocation behavior.
- cancellationToken
- CancellationToken
The CancellationToken to monitor for cancellation requests. The default is None.
Returns
A task that represents the asynchronous operation. The task result contains an AgentResponse<T> with the agent's output.
Remarks
This overload is useful when the agent has sufficient context from previous messages in the session or from its initial configuration to generate a meaningful response without additional input.
Applies to
RunAsync<T>(ChatMessage, AgentSession, JsonSerializerOptions, AgentRunOptions, CancellationToken)
Runs the agent with a single chat message, requesting a response of the specified type T.
public System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentResponse<T>> RunAsync<T>(Microsoft.Extensions.AI.ChatMessage message, Microsoft.Agents.AI.AgentSession? session = default, System.Text.Json.JsonSerializerOptions? serializerOptions = default, Microsoft.Agents.AI.AgentRunOptions? options = default, System.Threading.CancellationToken cancellationToken = default);member this.RunAsync : Microsoft.Extensions.AI.ChatMessage * Microsoft.Agents.AI.AgentSession * System.Text.Json.JsonSerializerOptions * Microsoft.Agents.AI.AgentRunOptions * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentResponse<'T>>Public Function RunAsync(Of T) (message As ChatMessage, Optional session As AgentSession = Nothing, Optional serializerOptions As JsonSerializerOptions = Nothing, Optional options As AgentRunOptions = Nothing, Optional cancellationToken As CancellationToken = Nothing) As Task(Of AgentResponse(Of T))Type Parameters
- T
The type of structured output to request.
Parameters
- message
- ChatMessage
The chat message to send to the agent.
- session
- AgentSession
The conversation session to use for this invocation. If null, a new session will be created.
The session will be updated with the input message and any response messages generated during invocation.
- serializerOptions
- JsonSerializerOptions
Optional JSON serializer options to use for deserializing the response.
- options
- AgentRunOptions
Optional configuration parameters for controlling the agent's invocation behavior.
- cancellationToken
- CancellationToken
The CancellationToken to monitor for cancellation requests. The default is None.
Returns
A task that represents the asynchronous operation. The task result contains an AgentResponse<T> with the agent's output.
Exceptions
message is null.
Applies to
RunAsync<T>(IEnumerable<ChatMessage>, AgentSession, JsonSerializerOptions, AgentRunOptions, CancellationToken)
Runs the agent with a collection of chat messages, requesting a response of the specified type T.
public System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentResponse<T>> RunAsync<T>(System.Collections.Generic.IEnumerable<Microsoft.Extensions.AI.ChatMessage> messages, Microsoft.Agents.AI.AgentSession? session = default, System.Text.Json.JsonSerializerOptions? serializerOptions = default, Microsoft.Agents.AI.AgentRunOptions? options = default, System.Threading.CancellationToken cancellationToken = default);member this.RunAsync : seq<Microsoft.Extensions.AI.ChatMessage> * Microsoft.Agents.AI.AgentSession * System.Text.Json.JsonSerializerOptions * Microsoft.Agents.AI.AgentRunOptions * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentResponse<'T>>Public Function RunAsync(Of T) (messages As IEnumerable(Of ChatMessage), Optional session As AgentSession = Nothing, Optional serializerOptions As JsonSerializerOptions = Nothing, Optional options As AgentRunOptions = Nothing, Optional cancellationToken As CancellationToken = Nothing) As Task(Of AgentResponse(Of T))Type Parameters
- T
The type of structured output to request.
Parameters
- messages
- IEnumerable<ChatMessage>
The collection of messages to send to the agent for processing.
- session
- AgentSession
The conversation session to use for this invocation. If null, a new session will be created.
The session will be updated with the input messages and any response messages generated during invocation.
- serializerOptions
- JsonSerializerOptions
Optional JSON serializer options to use for deserializing the response.
- options
- AgentRunOptions
Optional configuration parameters for controlling the agent's invocation behavior.
- cancellationToken
- CancellationToken
The CancellationToken to monitor for cancellation requests. The default is None.
Returns
A task that represents the asynchronous operation. The task result contains an AgentResponse<T> with the agent's output.
Remarks
This method handles collections of messages, allowing for complex conversational scenarios including multi-turn interactions, function calls, and context-rich conversations.
The messages are processed in the order provided and become part of the conversation history. The agent's response will also be added to session if one is provided.
Applies to
RunAsync<T>(String, AgentSession, JsonSerializerOptions, AgentRunOptions, CancellationToken)
Runs the agent with a text message from the user, requesting a response of the specified type T.
public System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentResponse<T>> RunAsync<T>(string message, Microsoft.Agents.AI.AgentSession? session = default, System.Text.Json.JsonSerializerOptions? serializerOptions = default, Microsoft.Agents.AI.AgentRunOptions? options = default, System.Threading.CancellationToken cancellationToken = default);member this.RunAsync : string * Microsoft.Agents.AI.AgentSession * System.Text.Json.JsonSerializerOptions * Microsoft.Agents.AI.AgentRunOptions * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentResponse<'T>>Public Function RunAsync(Of T) (message As String, Optional session As AgentSession = Nothing, Optional serializerOptions As JsonSerializerOptions = Nothing, Optional options As AgentRunOptions = Nothing, Optional cancellationToken As CancellationToken = Nothing) As Task(Of AgentResponse(Of T))Type Parameters
- T
The type of structured output to request.
Parameters
- message
- String
The user message to send to the agent.
- session
- AgentSession
The conversation session to use for this invocation. If null, a new session will be created.
The session will be updated with the input message and any response messages generated during invocation.
- serializerOptions
- JsonSerializerOptions
Optional JSON serializer options to use for deserializing the response.
- options
- AgentRunOptions
Optional configuration parameters for controlling the agent's invocation behavior.
- cancellationToken
- CancellationToken
The CancellationToken to monitor for cancellation requests. The default is None.
Returns
A task that represents the asynchronous operation. The task result contains an AgentResponse<T> with the agent's output.
Exceptions
message is null, empty, or contains only whitespace.
Remarks
The provided text will be wrapped in a ChatMessage with the User role before being sent to the agent. This is a convenience method for simple text-based interactions.