AIAgent 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.
Provides the base abstraction for all AI agents, defining the core interface for agent interactions and conversation management.
public abstract class AIAgenttype AIAgent = classPublic MustInherit Class AIAgent- Inheritance
-
AIAgent
- Derived
Remarks
AIAgent serves as the foundational class for implementing AI agents that can participate in conversations and process user requests. An agent instance may participate in multiple concurrent conversations, and each conversation may involve multiple agents working together.
Security considerations: An AIAgent orchestrates data flow across trust boundaries — messages are sent to external AI services, context providers, chat history stores, and function tools. Agent Framework passes messages through as-is without validation or sanitization. Developers must be aware that:
- User-supplied messages may contain prompt injection attempts designed to manipulate LLM behavior.
- LLM responses should be treated as untrusted output — they may contain hallucinations, malicious payloads (e.g., scripts, SQL), or content influenced by indirect prompt injection. Always validate and sanitize LLM output before rendering in HTML, executing as code, or using in database queries.
- Messages with different roles carry different trust levels:
systemmessages have the highest trust and must be developer-controlled;user,assistant, andtoolmessages should be treated as untrusted.
Constructors
| Name | Description |
|---|---|
| AIAgent() | |
Properties
| Name | Description |
|---|---|
| CurrentRunContext |
Gets or sets the AgentRunContext for the current agent run. |
| Description |
Gets a description of the agent's purpose, capabilities, or behavior. |
| Id |
Gets the unique identifier for this agent instance. |
| IdCore |
Gets a custom identifier for the agent, which can be overridden by derived classes. |
| Name |
Gets the human-readable name of the agent. |
Methods
| Name | Description |
|---|---|
| CreateSessionAsync(CancellationToken) |
Creates a new conversation session that is compatible with this agent. |
| CreateSessionCoreAsync(CancellationToken) |
Core implementation of session creation logic. |
| DeserializeSessionAsync(JsonElement, JsonSerializerOptions, CancellationToken) |
Deserializes an agent session from its JSON serialized representation. |
| DeserializeSessionCoreAsync(JsonElement, JsonSerializerOptions, CancellationToken) |
Core implementation of session deserialization logic. |
| 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. |
| RunAsync(ChatMessage, AgentSession, AgentRunOptions, CancellationToken) |
Runs the agent with a single chat message. |
| 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(String, AgentSession, AgentRunOptions, CancellationToken) |
Runs the agent with a text message from the user. |
| 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. |
| RunCoreStreamingAsync(IEnumerable<ChatMessage>, AgentSession, AgentRunOptions, CancellationToken) |
Core implementation of the agent streaming invocation logic with a collection of chat messages. |
| RunStreamingAsync(AgentSession, AgentRunOptions, CancellationToken) |
Runs the agent in streaming mode without providing new input messages, relying on existing context and instructions. |
| RunStreamingAsync(ChatMessage, AgentSession, AgentRunOptions, CancellationToken) |
Runs the agent in streaming mode with a single chat message. |
| RunStreamingAsync(IEnumerable<ChatMessage>, AgentSession, AgentRunOptions, CancellationToken) |
Runs the agent in streaming mode with a collection of chat messages, providing the core streaming invocation logic. |
| RunStreamingAsync(String, AgentSession, AgentRunOptions, CancellationToken) |
Runs the agent in streaming mode with a text message from the user. |
| SerializeSessionAsync(AgentSession, JsonSerializerOptions, CancellationToken) |
Serializes an agent session to its JSON representation. |
| SerializeSessionCoreAsync(AgentSession, JsonSerializerOptions, CancellationToken) |
Core implementation of session serialization logic. |