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
| RunAsync(AgentThread, AgentRunOptions, CancellationToken) |
Run the agent with no message assuming that all required instructions are already provided to the agent or on the thread. |
| RunAsync(ChatMessage, AgentThread, AgentRunOptions, CancellationToken) |
Runs the agent with a single chat message. |
| RunAsync(IEnumerable<ChatMessage>, AgentThread, AgentRunOptions, CancellationToken) |
Runs the agent with a collection of chat messages, providing the core invocation logic that all other overloads delegate to. |
| RunAsync(String, AgentThread, AgentRunOptions, CancellationToken) |
Runs the agent with a text message from the user. |
RunAsync(AgentThread, AgentRunOptions, CancellationToken)
Run the agent with no message assuming that all required instructions are already provided to the agent or on the thread.
public System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentRunResponse> RunAsync(Microsoft.Agents.AI.AgentThread? thread = default, Microsoft.Agents.AI.AgentRunOptions? options = default, System.Threading.CancellationToken cancellationToken = default);member this.RunAsync : Microsoft.Agents.AI.AgentThread * Microsoft.Agents.AI.AgentRunOptions * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentRunResponse>Public Function RunAsync (Optional thread As AgentThread = Nothing, Optional options As AgentRunOptions = Nothing, Optional cancellationToken As CancellationToken = Nothing) As Task(Of AgentRunResponse)Parameters
- thread
- AgentThread
The conversation thread to use for this invocation. If null, a new thread will be created.
The thread 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 AgentRunResponse with the agent's output.
Remarks
This overload is useful when the agent has sufficient context from previous messages in the thread or from its initial configuration to generate a meaningful response without additional input.
Applies to
RunAsync(ChatMessage, AgentThread, AgentRunOptions, CancellationToken)
Runs the agent with a single chat message.
public System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentRunResponse> RunAsync(Microsoft.Extensions.AI.ChatMessage message, Microsoft.Agents.AI.AgentThread? thread = default, Microsoft.Agents.AI.AgentRunOptions? options = default, System.Threading.CancellationToken cancellationToken = default);member this.RunAsync : Microsoft.Extensions.AI.ChatMessage * Microsoft.Agents.AI.AgentThread * Microsoft.Agents.AI.AgentRunOptions * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentRunResponse>Public Function RunAsync (message As ChatMessage, Optional thread As AgentThread = Nothing, Optional options As AgentRunOptions = Nothing, Optional cancellationToken As CancellationToken = Nothing) As Task(Of AgentRunResponse)Parameters
- message
- ChatMessage
The chat message to send to the agent.
- thread
- AgentThread
The conversation thread to use for this invocation. If null, a new thread will be created.
The thread 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 AgentRunResponse with the agent's output.
Exceptions
message is null.
Applies to
RunAsync(IEnumerable<ChatMessage>, AgentThread, AgentRunOptions, CancellationToken)
Runs the agent with a collection of chat messages, providing the core invocation logic that all other overloads delegate to.
public abstract System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentRunResponse> RunAsync(System.Collections.Generic.IEnumerable<Microsoft.Extensions.AI.ChatMessage> messages, Microsoft.Agents.AI.AgentThread? thread = default, Microsoft.Agents.AI.AgentRunOptions? options = default, System.Threading.CancellationToken cancellationToken = default);abstract member RunAsync : seq<Microsoft.Extensions.AI.ChatMessage> * Microsoft.Agents.AI.AgentThread * Microsoft.Agents.AI.AgentRunOptions * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentRunResponse>Public MustOverride Function RunAsync (messages As IEnumerable(Of ChatMessage), Optional thread As AgentThread = Nothing, Optional options As AgentRunOptions = Nothing, Optional cancellationToken As CancellationToken = Nothing) As Task(Of AgentRunResponse)Parameters
- messages
- IEnumerable<ChatMessage>
The collection of messages to send to the agent for processing.
- thread
- AgentThread
The conversation thread to use for this invocation. If null, a new thread will be created.
The thread 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 AgentRunResponse with the agent's output.
Remarks
This is the primary invocation method that implementations must override. 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 thread if one is provided.
Applies to
RunAsync(String, AgentThread, AgentRunOptions, CancellationToken)
Runs the agent with a text message from the user.
public System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentRunResponse> RunAsync(string message, Microsoft.Agents.AI.AgentThread? thread = default, Microsoft.Agents.AI.AgentRunOptions? options = default, System.Threading.CancellationToken cancellationToken = default);member this.RunAsync : string * Microsoft.Agents.AI.AgentThread * Microsoft.Agents.AI.AgentRunOptions * System.Threading.CancellationToken -> System.Threading.Tasks.Task<Microsoft.Agents.AI.AgentRunResponse>Public Function RunAsync (message As String, Optional thread As AgentThread = Nothing, Optional options As AgentRunOptions = Nothing, Optional cancellationToken As CancellationToken = Nothing) As Task(Of AgentRunResponse)Parameters
- message
- String
The user message to send to the agent.
- thread
- AgentThread
The conversation thread to use for this invocation. If null, a new thread will be created.
The thread 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 AgentRunResponse 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.