AIAgent API Reference
The base abstraction for all AI agents, defining the core interface for agent interactions and conversation management.
AIAgent
Provides the foundational class for implementing AI agents that can participate in conversations and process user requests.
using Microsoft.Agents.AI;
Overview
The AIAgent class serves as the base for implementing AI agents in the .NET SDK. An agent instance may participate in multiple concurrent conversations, and each conversation may involve multiple agents working together.
Properties
The unique identifier for this agent instance. For in-memory agents, defaults to a randomly-generated ID, while service-backed agents typically use the identifier assigned by the backing service.
The human-readable name of the agent, used for display purposes and to help users identify the agent’s purpose or capabilities.
A description of the agent’s purpose, capabilities, or behavior. Helps models and users understand the agent’s intended purpose.
Gets or sets the AgentRunContext for the current agent run. This value flows across async calls.
Methods
CreateSessionAsync()
Creates a new conversation session that is compatible with this agent.
public ValueTask<AgentSession> CreateSessionAsync(
CancellationToken cancellationToken = default
)
cancellationToken
CancellationToken
default:"default"
The cancellation token to monitor for cancellation requests.
A new AgentSession instance ready for use with this agent.
RunAsync()
Runs the agent with the provided messages, session, and options.
// Run with no message (uses existing session context)
public Task<AgentResponse> RunAsync(
AgentSession? session = null,
AgentRunOptions? options = null,
CancellationToken cancellationToken = default
)
// Run with a text message
public Task<AgentResponse> RunAsync(
string message,
AgentSession? session = null,
AgentRunOptions? options = null,
CancellationToken cancellationToken = default
)
// Run with a single chat message
public Task<AgentResponse> RunAsync(
ChatMessage message,
AgentSession? session = null,
AgentRunOptions? options = null,
CancellationToken cancellationToken = default
)
// Run with a collection of chat messages
public Task<AgentResponse> RunAsync(
IEnumerable<ChatMessage> messages,
AgentSession? session = null,
AgentRunOptions? options = null,
CancellationToken cancellationToken = default
)
The message to send to the agent. String messages are automatically wrapped in a ChatMessage with ChatRole.User.
A collection of messages to send to the agent for processing.
The conversation session to use. If null, a new session will be created. The session is updated with input messages and response messages.
Optional configuration parameters for controlling the agent’s invocation behavior.
cancellationToken
CancellationToken
default:"default"
The cancellation token to monitor for cancellation requests.
An AgentResponse containing the agent’s output, including all generated messages and metadata.
RunStreamingAsync()
Runs the agent in streaming mode, providing real-time updates as the agent generates its response.
// Stream with no message
public IAsyncEnumerable<AgentResponseUpdate> RunStreamingAsync(
AgentSession? session = null,
AgentRunOptions? options = null,
CancellationToken cancellationToken = default
)
// Stream with a text message
public IAsyncEnumerable<AgentResponseUpdate> RunStreamingAsync(
string message,
AgentSession? session = null,
AgentRunOptions? options = null,
CancellationToken cancellationToken = default
)
// Stream with a single chat message
public IAsyncEnumerable<AgentResponseUpdate> RunStreamingAsync(
ChatMessage message,
AgentSession? session = null,
AgentRunOptions? options = null,
CancellationToken cancellationToken = default
)
// Stream with a collection of chat messages
public IAsyncEnumerable<AgentResponseUpdate> RunStreamingAsync(
IEnumerable<ChatMessage> messages,
AgentSession? session = null,
AgentRunOptions? options = null,
CancellationToken cancellationToken = default
)
The message to send to the agent. String messages are automatically wrapped in a ChatMessage with ChatRole.User.
A collection of messages to send to the agent for processing.
The conversation session to use. If null, a new session will be created.
Optional configuration parameters for controlling the agent’s invocation behavior.
cancellationToken
CancellationToken
default:"default"
The cancellation token to monitor for cancellation requests.
return
IAsyncEnumerable<AgentResponseUpdate>
An asynchronous enumerable of AgentResponseUpdate instances representing the streaming response. Each update represents a portion of the complete response.
SerializeSessionAsync()
Serializes an agent session to its JSON representation for persistent storage.
public ValueTask<JsonElement> SerializeSessionAsync(
AgentSession session,
JsonSerializerOptions? jsonSerializerOptions = null,
CancellationToken cancellationToken = default
)
The session to serialize.
Optional settings to customize the serialization process.
cancellationToken
CancellationToken
default:"default"
The cancellation token to monitor for cancellation requests.
A JsonElement containing the serialized session state.
DeserializeSessionAsync()
Deserializes an agent session from its JSON serialized representation.
public ValueTask<AgentSession> DeserializeSessionAsync(
JsonElement serializedState,
JsonSerializerOptions? jsonSerializerOptions = null,
CancellationToken cancellationToken = default
)
A JsonElement containing the serialized session state.
Optional settings to customize the deserialization process.
cancellationToken
CancellationToken
default:"default"
The cancellation token to monitor for cancellation requests.
A restored AgentSession instance with the state from the serialized data.
GetService()
Retrieves a service of the specified type from the agent.
public virtual object? GetService(
Type serviceType,
object? serviceKey = null
)
public TService? GetService<TService>(
object? serviceKey = null
)
The type of object being requested.
An optional key that can be used to help identify the target service.
The found object, or null if not available.
Example: Basic Agent Usage
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
// Create an agent (using ChatClientAgent as a concrete implementation)
var chatClient = new OpenAIChatClient(model: "gpt-4", apiKey: Environment.GetEnvironmentVariable("OPENAI_API_KEY"));
var agent = chatClient.AsAIAgent(
instructions: "You are a helpful assistant.",
name: "Assistant",
description: "A helpful AI assistant"
);
// Create a session
var session = await agent.CreateSessionAsync();
// Run the agent
var response = await agent.RunAsync(
"What is the capital of France?",
session: session
);
Console.WriteLine(response.Text);
Example: Streaming Responses
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
var agent = chatClient.AsAIAgent(
instructions: "You are a helpful assistant.",
name: "Assistant"
);
var session = await agent.CreateSessionAsync();
// Stream the response
await foreach (var update in agent.RunStreamingAsync(
"Tell me a short story.",
session: session
))
{
Console.Write(update.Text);
}
Example: Multi-Turn Conversation
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
var agent = chatClient.AsAIAgent(
instructions: "You are a helpful assistant."
);
var session = await agent.CreateSessionAsync();
// First turn
var response1 = await agent.RunAsync("My name is Alice.", session);
Console.WriteLine(response1.Text);
// Second turn (agent remembers the context)
var response2 = await agent.RunAsync("What's my name?", session);
Console.WriteLine(response2.Text); // Should say "Alice"
Example: Session Serialization
using Microsoft.Agents.AI;
using System.Text.Json;
var agent = chatClient.AsAIAgent();
var session = await agent.CreateSessionAsync();
// Have a conversation
await agent.RunAsync("Remember: my favorite color is blue.", session);
// Serialize the session
var serialized = await agent.SerializeSessionAsync(session);
var sessionJson = JsonSerializer.Serialize(serialized);
// Save to storage (database, file, etc.)
File.WriteAllText("session.json", sessionJson);
// Later: load and deserialize
var loadedJson = File.ReadAllText("session.json");
var loadedElement = JsonSerializer.Deserialize<JsonElement>(loadedJson);
var restoredSession = await agent.DeserializeSessionAsync(loadedElement);
// Continue the conversation
var response = await agent.RunAsync("What's my favorite color?", restoredSession);
Console.WriteLine(response.Text); // Should say "blue"
Protected Methods
These methods are intended for implementation by derived classes:
CreateSessionCoreAsync()
Core implementation of session creation logic.
protected abstract ValueTask<AgentSession> CreateSessionCoreAsync(
CancellationToken cancellationToken = default
);
RunCoreAsync()
Core implementation of the agent invocation logic.
protected abstract Task<AgentResponse> RunCoreAsync(
IEnumerable<ChatMessage> messages,
AgentSession? session = null,
AgentRunOptions? options = null,
CancellationToken cancellationToken = default
);
RunCoreStreamingAsync()
Core implementation of the agent streaming invocation logic.
protected abstract IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingAsync(
IEnumerable<ChatMessage> messages,
AgentSession? session = null,
AgentRunOptions? options = null,
CancellationToken cancellationToken = default
);
SerializeSessionCoreAsync()
Core implementation of session serialization logic.
protected abstract ValueTask<JsonElement> SerializeSessionCoreAsync(
AgentSession session,
JsonSerializerOptions? jsonSerializerOptions = null,
CancellationToken cancellationToken = default
);
DeserializeSessionCoreAsync()
Core implementation of session deserialization logic.
protected abstract ValueTask<AgentSession> DeserializeSessionCoreAsync(
JsonElement serializedState,
JsonSerializerOptions? jsonSerializerOptions = null,
CancellationToken cancellationToken = default
);