Step 1：创建第一个 Agent

这是入门教程的 Step 1，目标是创建一个最简单的 AI Agent 并成功调用。

---

创建项目

mkdir MyFirstAgent && cd MyFirstAgent
dotnet new console -n Step1_HelloAgent
cd Step1_HelloAgent
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI

三个包各自的作用：

• Azure.AI.Projects — Azure AI 平台的项目级客户端。AIProjectClient 是 Agent 的入口点，它不做 AI 推理，而是负责资源的连接管理和认证。
• Azure.Identity — Azure SDK 的统一认证库。DefaultAzureCredential 会自动尝试多种认证方式（环境变量 → Azure CLI → Visual Studio → Managed Identity）。
• Microsoft.Agents.AI — Agent 核心库。定义了 AIAgent 基类、ChatClientAgent 实现、AgentSession 会话管理、以及 RunAsync/RunStreamingAsync 等核心方法。

配置 Azure OpenAI 端点

export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
export AZURE_OPENAI_DEPLOYMENT_NAME="gpt-4o-mini"

编写第一个 Agent

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

// 从环境变量读取 Azure OpenAI 端点
var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
    ?? throw new InvalidOperationException("请设置 AZURE_OPENAI_ENDPOINT");

var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME")
    ?? "gpt-4o-mini";

// 第一步：创建 AIProjectClient（Azure AI 项目客户端）
// AIProjectClient 是 Agent 的入口点，它管理模型连接和资源
var projectClient = new AIProjectClient(
    new Uri(endpoint),
    new DefaultAzureCredential());

// 第二步：通过 AsAIAgent 扩展方法创建 Agent
// AsAIAgent 把 AIProjectClient 包装成一个 AIAgent 实例
AIAgent agent = projectClient.AsAIAgent(
    model: deploymentName,
    instructions: "你是一个友好的助手。回答简洁明了。",
    name: "HelloAgent");

// 第三步：运行 Agent（非流式）
// RunAsync 发送消息并等待完整回复
var response = await agent.RunAsync("法国最大的城市是哪个？");
Console.WriteLine(response);

运行这段代码，控制台会输出 Agent 的回答。RunAsync 方法是 Agent 的核心调用方式，它接受用户输入，由 Agent 框架自动处理与 LLM 的通信、工具调用（如果已注册）、上下文管理等一系列复杂操作，最后返回一个 AgentResponse 对象。

关于 DefaultAzureCredential

DefaultAzureCredential 的工作方式是"链式尝试"——按顺序尝试多种认证来源，直到其中一个成功。默认尝试顺序是：环境变量 > Azure CLI > Visual Studio > Managed Identity。如果你在本地用 az login 登录了 Azure CLI，代码中不需要任何额外的配置。

在生产环境中，建议替换为 ManagedIdentityCredential（Azure 托管环境中）或 ChainedTokenCredential（精确控制尝试顺序），避免因意外回退导致的延迟。

流式响应

// 流式输出——每个 Token 生成后立即返回
await foreach (var update in agent.RunStreamingAsync("给我讲一个有趣的事实。"))
{
    Console.Write(update);
}
Console.WriteLine();

流式输出的原理：Agent 不是等 LLM 生成完完整回复才返回，而是每生成一个 Token 就立即通过 RunStreamingAsync 返回给调用者。

完整交互式终端

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException();
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";

AIAgent agent = new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
    .AsAIAgent(model: deploymentName, instructions: "你是一个友好的助手。回答简洁明了。", name: "ChatBot");

Console.WriteLine("🤖 Agent 已就绪！输入 'exit' 退出。\n");

while (true)
{
    Console.Write("🧑 ");
    var input = Console.ReadLine();
    if (string.IsNullOrEmpty(input) || input == "exit") break;

    Console.Write("🤖 ");
    await foreach (var update in agent.RunStreamingAsync(input))
    {
        Console.Write(update);
    }
    Console.WriteLine("\n");
}

要点回顾

• AIProjectClient 是 Agent 的入口，管理模型连接和认证
• AsAIAgent() 把 AIProjectClient 包装为 AIAgent 实例
• RunAsync 用于非流式调用，返回完整 AgentResponse
• RunStreamingAsync 用于流式调用，逐 Token 返回
• DefaultAzureCredential 适合开发环境，生产环境用明确的凭据类型

---

下一步：Step 2：工具调用 — 给 Agent 添加真实的业务能力。