---

name: azure-ai-agents-persistent-dotnet description: Azure AI Agents Persistent SDK for .NET。用于创建和管理具有线程、消息、运行和工具的AI代理的低级SDK。 risk: unknown source: community date_added: '2026-02-27'

Azure.AI.Agents.Persistent (.NET)

用于创建和管理持久化AI代理的低级SDK，支持线程、消息、运行和工具。

安装

dotnet add package Azure.AI.Agents.Persistent --prerelease
dotnet add package Azure.Identity

当前版本: 稳定版 v1.1.0，预览版 v1.2.0-beta.8

环境变量

PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
MODEL_DEPLOYMENT_NAME=gpt-4o-mini
AZURE_BING_CONNECTION_ID=<bing-connection-resource-id>
AZURE_AI_SEARCH_CONNECTION_ID=<search-connection-resource-id>

认证

using Azure.AI.Agents.Persistent;
using Azure.Identity;

var projectEndpoint = Environment.GetEnvironmentVariable("PROJECT_ENDPOINT");
PersistentAgentsClient client = new(projectEndpoint, new DefaultAzureCredential());

客户端层级结构

PersistentAgentsClient
├── Administration  → 代理 CRUD 操作
├── Threads         → 线程管理
├── Messages        → 消息操作
├── Runs            → 运行执行和流式传输
├── Files           → 文件上传/下载
└── VectorStores    → 向量存储管理

核心工作流

1. 创建代理

var modelDeploymentName = Environment.GetEnvironmentVariable("MODEL_DEPLOYMENT_NAME");

PersistentAgent agent = await client.Administration.CreateAgentAsync(
    model: modelDeploymentName,
    name: "Math Tutor",
    instructions: "You are a personal math tutor. Write and run code to answer math questions.",
    tools: [new CodeInterpreterToolDefinition()]
);

2. 创建线程和消息

// 创建线程
PersistentAgentThread thread = await client.Threads.CreateThreadAsync();

// 创建消息
await client.Messages.CreateMessageAsync(
    thread.Id,
    MessageRole.User,
    "I need to solve the equation \`3x + 11 = 14\`. Can you help me?"
);

3. 运行代理（轮询模式）

// 创建运行
ThreadRun run = await client.Runs.CreateRunAsync(
    thread.Id,
    agent.Id,
    additionalInstructions: "Please address the user as Jane Doe."
);

// 轮询等待完成
do
{
    await Task.Delay(TimeSpan.FromMilliseconds(500));
    run = await client.Runs.GetRunAsync(thread.Id, run.Id);
}
while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress);

// 获取消息
await foreach (PersistentThreadMessage message in client.Messages.GetMessagesAsync(
    threadId: thread.Id, 
    order: ListSortOrder.Ascending))
{
    Console.Write($"{message.Role}: ");
    foreach (MessageContent content in message.ContentItems)
    {
        if (content is MessageTextContent textContent)
            Console.WriteLine(textContent.Text);
    }
}

4. 流式响应

AsyncCollectionResult<StreamingUpdate> stream = client.Runs.CreateRunStreamingAsync(
    thread.Id, 
    agent.Id
);

await foreach (StreamingUpdate update in stream)
{
    if (update.UpdateKind == StreamingUpdateReason.RunCreated)
    {
        Console.WriteLine("--- 运行已启动！ ---");
    }
    else if (update is MessageContentUpdate contentUpdate)
    {
        Console.Write(contentUpdate.Text);
    }
    else if (update.UpdateKind == StreamingUpdateReason.RunCompleted)
    {
        Console.WriteLine("\n--- 运行已完成！ ---");
    }
}

5. 函数调用

// 定义函数工具
FunctionToolDefinition weatherTool = new(
    name: "getCurrentWeather",
    description: "Gets the current weather at a location.",
    parameters: BinaryData.FromObjectAsJson(new
    {
        Type = "object",
        Properties = new
        {
            Location = new { Type = "string", Description = "City and state, e.g. San Francisco, CA" },
            Unit = new { Type = "string", Enum = new[] { "c", "f" } }
        },
        Required = new[] { "location" }
    }, new JsonSerializerOptions { PropertyNamingPolicy = JsonNamingPolicy.CamelCase })
);

// 创建带函数的代理
PersistentAgent agent = await client.Administration.CreateAgentAsync(
    model: modelDeploymentName,
    name: "Weather Bot",
    instructions: "You are a weather bot.",
    tools: [weatherTool]
);

// 在轮询期间处理函数调用
do
{
    await Task.Delay(500);
    run = await client.Runs.GetRunAsync(thread.Id, run.Id);

    if (run.Status == RunStatus.RequiresAction 
        && run.RequiredAction is SubmitToolOutputsAction submitAction)
    {
        List<ToolOutput> outputs = [];
        foreach (RequiredToolCall toolCall in submitAction.ToolCalls)
        {
            if (toolCall is RequiredFunctionToolCall funcCall)
            {
                // 执行函数并获取结果
                string result = ExecuteFunction(funcCall.Name, funcCall.Arguments);
                outputs.Add(new ToolOutput(funcCall.Id, result));
            }
        }
        run = await client.Runs.SubmitToolOutputsToRunAsync(thread.Id, run.Id, outputs);
    }
}
while (run.Status == RunStatus.Queued || run.Status == RunStatus.InProgress
    || run.Status == RunStatus.RequiresAction);

限制

• 仅在任务明确匹配上述范围时使用此技能。
• 不要将输出视为特定环境验证、测试或专家审查的替代品。
• 如果缺少必要的输入、权限、安全边界或成功标准，请停下来要求澄清。