چیزهای جدید در چارچوب عامل مایکروسافت: تجربیات تعاملی، حافظه و اجرای مقاوم
عاملی که به یک سوال پاسخ می‌دهد نقطه شروع است. عاملی که کارهای مفیدی را به انجام می‌رساند به موارد بیشتری نیاز دارد: رابطی که کاربران بتوانند با آن تعامل داشته باشند، حافظه‌ای فراتر از
عاملی که به یک سوال پاسخ می‌دهد نقطه شروع است. عاملی که کارهای مفیدی را به انجام می‌رساند به موارد بیشتری نیاز دارد: رابطی که کاربران بتوانند با آن تعامل داشته باشند، حافظه‌ای فراتر از مکالمه فعلی، محیطی مناسب برای اجرای کد و روشی برای بازیابی زمانی که کار متوقف می‌شود.
به‌روزرسانی‌های اخیر چارچوب عامل مایکروسافت (Microsoft Agent Framework) این نیازها را در دات‌نت (.NET) و پایتون برطرف می‌کند. در ادامه نحوه استفاده از آن‌ها آورده شده است؛ از اتصال یک عامل به برنامه‌تان گرفته تا اجرا و دیباگ کردن جریان‌های کاری طولانی‌مدت.
پیش‌نیازها و راه‌اندازی
با دستور az login وارد شوید. متغیر FOUNDRY_PROJECT_ENDPOINT را روی نقطه پایانی پروژه Foundry خود و FOUNDRY_MODEL را روی نام مدل مستقر شده خود تنظیم کنید.
پایتون
پکیج‌های مربوط به نمونه‌های AG-UI و حافظه را نصب کنید:
pip install --pre agent-framework-foundry agent-framework-ag-ui azure-identity aiohttp fastapi uvicorn
برای CodeAct، همچنین ادغام Hyperlight را روی یک پلتفرم پشتیبانی‌شده نصب کنید:
pip install --pre agent-framework-hyperlight
برای نمونه حافظه، متغیر FOUNDRY_MEMORY_STORE_NAME را روی یک فروشگاه حافظه موجود در Foundry که با استقرار مدل‌های چت و امبینگ پشتیبانی‌شده پیکربندی شده است، تنظیم کنید. برای راه‌اندازی و نمونه‌های دات‌نت به حافظه معنایی مدیریت شده Foundry مراجعه کنید.
دات‌نت (.NET)
یک پروژه جدید Blazor ایجاد کنید و وابستگی‌های مورد نیاز را نصب کنید:
dotnet new blazor -n FoundryAgUi
cd FoundryAgUi
dotnet add package Azure.Identity
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Microsoft.Agents.AI.Foundry --prerelease
dotnet add package Microsoft.Agents.AI.Hosting.AGUI.AspNetCore --prerelease
اتصال عامل‌ها به برنامه‌های تعاملی با AG-UI
یک رابط عامل مفید باید فراتر از پاسخ نهایی را ارتباط دهد. کاربران باید پیشرفت را ببینند، فعالیت ابزار را درک کنند، عملیات را تایید کنند و با نتایج تعامل داشته باشند.
AG-UI یک پروتکل باز و مبتنی بر رویداد را برای این تعامل فراهم می‌کند. ادغام چارچوب عامل مایکروسافت به شما امکان می‌دهد یک عامل را از طریق یک نقطه پایانی AG-UI در معرض دید قرار دهید و فرانت‌اندهای سازگار، از جمله برنامه‌های ساخته‌شده با CopilotKit یا کامپوننت‌های جدید Blazor AI برای ایجاد رابط‌های کاربری عاملی در دات‌نت را متصل کنید.
پایتون: قرار دادن یک عامل در معرض دید از طریق FastAPI (نسخه پایدار)
کد زیر را به عنوان app.py ذخیره کنید و دستور uvicorn app:app --reload را اجرا کنید:
import os
from contextlib import asynccontextmanager
from fastapi import FastAPI
from agent_framework import Agent
from agent_framework.ag_ui import add_agent_framework_fastapi_endpoint
from agent_framework.foundry import FoundryChatClient
from azure.identity.aio import AzureCliCredential
credential = AzureCliCredential()
agent = Agent(
client=FoundryChatClient(
project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
model=os.environ["FOUNDRY_MODEL"],
credential=credential,
),
name="ResearchAssistant",
instructions="Help users research topics and explain your findings.",
)
@asynccontextmanager
async def lifespan(app: FastAPI):
async with credential, agent:
yield
app = FastAPI(lifespan=lifespan)
add_agent_framework_fastapi_endpoint(app, agent, "/ag-ui")
بیشتر بدانید: شروع سریع: ساخت عامل‌ها با استفاده از Responses API.
این یکپارچه‌سازی، اجرای عامل را به رویدادهای AG-UI برای پاسخ‌های جریانی (streaming)، فعالیت ابزار و سایر تعاملات پشتیبانی‌شده تبدیل می‌کند.
کارهای اخیر پایتون فراتر از چت است: نقطه‌گذاری (checkpointing) و از سرگیری جریان کار، تداوم بهبودیافته تایید، به‌روزرسانی‌های حالت مشترک و پیش‌بینی‌کننده، و ادغام اختیاری A2UI برای رابط‌های تولید شده توسط عامل.
گیت‌هاب: پکیج Python AG-UI و شروع سریع · نمونه‌های تعاملی
دات‌نت: قرار دادن یک عامل متصل به Foundry در معرض دید از طریق ASP.NET Core (پیش‌نمایش عمومی)
این مثال از همان پیکربندی Foundry، نام عامل، دستورالعمل‌ها و نقطه پایانی /ag-ui مانند مثال پایتون استفاده می‌کند. فایل Program.cs را با کد زیر جایگزین کنید و dotnet run را اجرا کنید:
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;
string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string model = Environment.GetEnvironmentVariable("FOUNDRY_MODEL")
?? throw new InvalidOperationException("FOUNDRY_MODEL is not set.");
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddAGUIServer();
AIAgent agent = new AIProjectClient(
new Uri(endpoint), new AzureCliCredential())
.AsAIAgent(
model: model,
name: "ResearchAssistant",
instructions: "Help users research topics and explain your findings.");
var app = builder.Build();
app.MapAGUIServer("/ag-ui", agent);
await app.RunAsync();
پشتیبانی به‌روزرسانی‌شده دات‌نت برای AG-UI از SDK جدید AG-UI .NET استفاده می‌کند که انتزاع‌هایی را برای رویدادهای AG-UI و همچنین پشتیبانی از کلاینت و سرور مبتنی بر Microsoft.Extensions.AI فراهم می‌کند.
ادغام میزبانی دات‌نت همچنان در حالت پیش‌نمایش است. هر دو زبان از تجربیات عامل تعاملی پشتیبانی می‌کنند، اما قابلیت‌های آن‌ها یکسان نیست—به جای فرض برابری ویژگی‌ها، از نمونه‌های خاص هر زبان استفاده کنید.
این نقاط پایانی حداقلی همچنین قبل از استقرار به امنیت برنامه نیاز دارند: احراز هویت فراخوانندگان و مجوز دسترسی به جلسات آن‌ها. شناسه نخ (thread ID) یک مکالمه را مشخص می‌کند؛ این مشخص نمی‌کند چه کسی اجازه دسترسی به آن را دارد.
اسناد و نمونه‌ها: ادغام AG-UI با چارچوب عامل، نمونه‌های AG-UI چارچوب عامل برای دات‌نت
استفاده مجدد از منطق عامل در کانال‌های مختلف
AG-UI عامل‌ها را به فرانت‌اندهای تعاملی متصل می‌کند. پکیج‌های جدید کانال‌های عامل و جریان کار پایتون به یک مشکل دیگر در یکپارچه‌سازی می‌پردازند: قرار دادن همان منطق عامل در معرض دید از طریق پروتکل‌ها و سطوح مختلف.
این پکیج‌ها کمکی‌هایی را برای OpenAI Responses، تلگرام، A2A و MCP فراهم می‌کنند. این موارد اهداف مختلفی را دنبال می‌کنند: پیام‌رسانی به کاربران، سرویس‌دهی به کلاینت‌های API، ارتباط با سایر عامل‌ها، و قرار دادن قابلیت‌ها به عنوان ابزار.
کمک‌کننده‌های جلسه مشترک، کد مربوط به عامل را کوچک نگه می‌دارند. برای مثال، در داخل یک تابع ناهمگام (async):
from agent_framework_hosting import AgentState
state = AgentState(agent)
session = await state.get_or_create_session("demo-session")
result = await agent.run(
"Summarize the research we have collected.",
session=session,
)
await state.set_session("demo-session", session)
print(result.text)
برنامه شما مالک نگاشت بین هویت یک کانال و یک جلسه مجاز، به همراه سیاست ذخیره‌سازی و همزمانی (concurrency) است. شناسه جلسه ثابت در بالا برای یک نمایش محلی است—نه یک استراتژی هویت در سطح پروداکشن (Production).
این جداسازی به توسعه‌دهندگان اجازه می‌دهد بدون از دست دادن کنترل بر مسیریابی برنامه، احراز هویت یا ماندگاری (persistence)، از منطق عامل استفاده مجدد کنند.
گیت‌هاب: نمونه میزبانی Responses · نمونه میزبانی تلگرام
بررسی تخصصی: معرفی کانال‌های عامل و جریان کار
اضافه کردن حافظه از طریق ارائه‌دهندگان زمینه (context providers)
تاریخچه مکالمه آنچه گفته شده را حفظ می‌کند. حافظه بلندمدت‌تر به یک عامل کمک می‌کند بدون پخش مجدد کل متن، اطلاعات مفید را وارد یک مکالمه جدید کند. حافظه در سرویس عامل Foundry از طریق FoundryMemoryProvider با چارچوب عامل مایکروسافت یکپارچه می‌شود که خاطرات مرتبط را قبل از اجرا بازیابی می‌کند و اطلاعات مکالمه را برای استخراج حافظه ناهمگام بعد از آن ارسال می‌کند.
مثال پایتون زیر هم استنتاج مدل و هم حافظه را به پروژه Foundry شما متصل می‌کند. این را به عنوان memory_demo.py ذخیره کنید:
import argparse
import asyncio
import os
from agent_framework import Agent, InMemoryHistoryProvider
from agent_framework.foundry import FoundryChatClient, FoundryMemoryProvider
from azure.ai.projects.aio import AIProjectClient
from azure.identity.aio import AzureCliCredential
async def main(message: str) -> None:
async with (
AzureCliCredential() as credential,
AIProjectClient(
endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
credential=credential,
allow_preview=True,
) as project_client,
):
memory = FoundryMemoryProvider(
project_client=project_client,
memory_store_name=os.environ["FOUNDRY_MEMORY_STORE_NAME"],
scope="demo-user",
update_delay=0,
)
async with Agent(
client=FoundryChatClient(
project_client=project_client,
model=os.environ["FOUNDRY_MODEL"],
),
instructions="Use relevant remembered preferences when helping the user.",
context_providers=[
memory,
InMemoryHistoryProvider(load_messages=False),
],
default_options={"store": False},
) as agent:
response = await agent.run(
message, session=agent.create_session()
)
print(response.text)
if __name__ == "__main__":
parser = argparse.ArgumentParser()
parser.add_argument("message")
asyncio.run(main(parser.parse_args().message))
ابتدا یک ترجیح را ثبت کنید:
python memory_demo.py "For project updates, I prefer a short summary followed by action items."
پس از اتمام استخراج حافظه، یک فرآیند جداگانه را برای پرسیدن آن ترجیح (سلیقه) آغاز کنید:
python memory_demo.py "How should you format my next project update?"
هر بار فراخوانی، یک نشست (جلسه) جدید با همان محدوده حافظه ایجاد می‌کند. ذخیره‌سازی پاسخ در سمت سرور و بارگذاری رونوشت محلی غیرفعال هستند، بنابراین فراخوانی دوم مکالمه اول را دوباره پخش نمی‌کند. استخراج حافظه به صورت ناهمگام (asynchronous) انجام می‌شود: update_delay=0 پردازش را بدون تأخیر دسته‌ای (batching delay) آغاز می‌کند اما یادآوری فوری را تضمین نمی‌کند.
برای محیط پروداکشن (تولید)، محدوده را به جای پذیرش یک شناسه دلخواه ارائه‌شده توسط کاربر، از هویت احراز هویت‌شده برنامه مشتق کنید. از یک اعتبارنامه مناسب برای پروداکشن استفاده کنید، سیاست‌های نگهداری و حذف حافظه برنامه خود را اعمال کنید و کیفیت یادآوری را ارزیابی کنید.
سرویس Azure Cosmos DB از طریق یکپارچه‌سازی Python-preview CosmosMemoryContextProvider، با بازیابی ترکیبی برداری (hybrid vector) و تمام‌متن (full-text) به عنوان یک گزینه باقی می‌ماند. پکیج حافظه Cosmos DB و بررسی فنی عمیق را مشاهده کنید.
اجرای وظایف چندمرحله‌ای مناسب با CodeAct
برخی از وظایف عامل (agent) شامل عملیات کوچک و قابل زنجیره‌سازی زیادی هستند. درخواست از مدل برای انتخاب یک ابزار، بررسی نتیجه و انتخاب ابزاری دیگر در هر مرحله می‌تواند تاخیر غیرضروری و مصرف توکن را افزایش دهد.
CodeAct به مدل اجازه می‌دهد تا توالی‌های مناسب را به عنوان یک برنامه بیان کند و یک نتیجه یکپارچه دریافت نماید.
این نمونه پایتون از یک ابزار محاسبه خالص و یک کلاینت مدل متصل به Foundry استفاده می‌کند. آن را به عنوان codeact_demo.py ذخیره کرده و دستور python codeact_demo.py را اجرا کنید.
import asyncio
import os
from agent_framework import Agent, tool
from agent_framework.foundry import FoundryChatClient
from agent_framework_hyperlight import HyperlightCodeActProvider
from azure.identity.aio import AzureCliCredential
@tool
def line_total(unit_price_cents: int, quantity: int) -> int:
"""Calculate a line total in cents."""
return unit_price_cents * quantity
async def main() -> None:
async with AzureCliCredential() as credential:
codeact = HyperlightCodeActProvider(
tools=[line_total],
approval_mode="never_require",
)
async with Agent(
client=FoundryChatClient(
project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
model=os.environ["FOUNDRY_MODEL"],
credential=credential,
),
name="OrderCalculator",
instructions="Use execute_code to combine calculations when useful.",
context_providers=[codeact],
) as agent:
response = await agent.run(
"Calculate the combined total for 12 items at 250 cents each "
"and 8 items at 175 cents each."
)
print(response.text)
if __name__ == "__main__":
asyncio.run(main())
HyperlightCodeActProvider ابزار اجرا و دستورالعمل‌ها را فراهم می‌کند. ابزارهای ثبت‌شده از طریق call_tool(…) برای کد تولیدشده در دسترس هستند.
مرز جداسازی اهمیت دارد: Hyperlight کد تولیدشده توسط مدل را ایزوله می‌کند؛ ابزارهای ثبت‌شده برنامه در زمان اجرای (runtime) برنامه شما اجرا می‌شوند. آن ابزارها مجوزها و مسئولیت‌های خاص خود را حفظ می‌کنند. این نمونه اجرای خودکار را مجاز می‌داند زیرا تنها ابزار آن محاسبات ریاضی را انجام می‌دهد. اقداماتی که نیازمند تأیید فردی هستند باید به‌طور صریح دارای محدودیت تأیید (approval-gated) باقی بمانند.
راهنمای گام‌به‌گام CodeAct تأخیر تقریباً ۵۰٪ کمتر و مصرف توکن بیش از ۶۰٪ کمتر را در بار کاری ارزیابی‌شده خود گزارش می‌دهد. این موارد را به عنوان نتایج مختص به بار کاری در نظر بگیرید و موازنه را در برنامه خود بسنجید.
گیت‌هاب: پکیج Hyperlight پایتون و پیش‌نیازهای پلتفرم · نمونه‌های CodeAct در دات‌نت (.NET)
قابلیت بازیابی را به کارهای طولانی‌مدت اضافه کنید
یک تایم‌اوت طولانی‌تر، یک عامل را مقاوم نمی‌سازد. کارهای طولانی‌مدت به حالت اجرای قابل بازیابی، راهی برای اتصال مجدد به نتایج و رفتاری مشخص هنگام متوقف شدن یک فرآیند نیاز دارند.
یکپارچه‌سازی Agent Framework با عامل‌های میزبانی‌شده در Foundry Agent Service، نقاط بررسی (checkpoints) گردش کار و نشست‌های عامل را به پاسخ‌های پس‌زمینه مقاوم متصل می‌کند.
پایتون: فعال‌سازی اجرای پس‌زمینه مقاوم
پس از ساخت یک گردش کار، میزبان (host) پاسخ‌های آن را پیکربندی کنید:
from agent_framework_foundry_hosting import ResponsesHostServer
from azure.ai.agentserver.responses import ResponsesServerOptions
workflow_agent = workflow.as_agent(name="report-workflow")
server = ResponsesHostServer(
workflow_agent,
options=ResponsesServerOptions(resilient_background=True),
)
server.run()
نمونه کامل پایتون یک گردش کار شمارش معکوس می‌سازد تا مشاهده قابلیت بازیابی آسان باشد. شما می‌توانید یک درخواست پس‌زمینه ارسال کنید، سرور را متوقف نمایید، آن را مجدداً راه‌اندازی کنید و دوباره به پاسخ متصل شوید.
برای آن نمونه، بدنه درخواست به صورت زیر است:
{
"input": "Count down from 20",
"background": true,
"store": true,
"stream": true
}
گیت‌هاب: گردش کار طولانی‌مدت مقاوم در پایتون
دات‌نت (.NET): پیکربندی میزبان پاسخ‌های مقاوم
یکپارچه‌سازی متناظر در دات‌نت از AddFoundryResponses استفاده می‌کند:
using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry.Hosting;
using Microsoft.Agents.AI.Workflows;
AIAgent agent = workflow.AsAIAgent(
id: "report-workflow",
name: "report-workflow",
includeWorkflowOutputsInResponse: true);
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFoundryResponses(
agent,
configure: options => options.ResilientBackground = true);
var app = builder.Build();
app.MapFoundryResponses();
await app.RunAsync();
هنگام بازیابی، میزبان حالت ذخیره‌شده را دوباره بارگذاری می‌کند و نقطه بررسی گردش کار مرتبط با پاسخ ذخیره‌شده را انتخاب می‌کند. یک فرآیند راه‌اندازی مجدد شده باید هویت‌های منطبق گردش کار و اجراکننده (executor) را بازسازی کند.
بازیابی به معنای اجرای دقیقاً یک‌باره (exactly-once) اثرات خارجی نیست. یک مرحله متوقف‌شده ممکن است دوباره اجرا شود. اگر یک ابزار ایمیلی ارسال می‌کند، پرداختی را انجام می‌دهد یا در سرویس دیگری می‌نویسد، آن عملیات را به گونه‌ای طراحی کنید که در برابر تلاش‌های مجدد (retries) مقاوم باشد - برای مثال، از طریق کلیدهای هم‌ارزی (idempotency keys) در لایه پایین‌دست.
گیت‌هاب: گردش کار مقاوم در دات‌نت همراه با دستورالعمل‌های استقرار · نمایش بازیابی محلی و هم‌ارزی (idempotency)
برای Azure Functions، افزونه Durable برای Agent Framework یک مسیر اجرای پایدار (durable-execution) مجزا را فراهم می‌کند. برای آن مدل میزبانی، نمونه‌های Azure Functions را مشاهده کنید.
ما همچنین در حال توسعه چرخه عمر توسعه در VS Code هستیم. پشتیبانی Foundry Toolkit به توسعه‌دهندگان اجازه می‌دهد یک عامل طولانی‌مدت را راه‌اندازی کنند، تعامل را ترک کرده و بدون شروع مجدد کار، دوباره متصل شوند تا پیشرفت یا نتایج را بررسی کنند.
با قابلیتی شروع کنید که برنامه‌تان در ادامه به آن نیاز دارد
این قابلیت‌ها قابل ترکیب هستند. شما می‌توانید یک فرانت‌اند AG-UI متصل کنید، حافظه اضافه کنید، CodeAct را ارزیابی کنید یا میزبانی گردش کار مقاوم را بدون اینکه هر ویژگی را به عنوان یک پیش‌نیاز اجباری در نظر بگیرید، به کار بگیرید.
مخزن مایکروسافت اجنت فریم‌ورک را بررسی کنید، یک نمونه برای زبان و محیط اجرایی خود انتخاب کنید و کار را از آنجا توسعه دهید. هدف، عاملی است که کاربران بتوانند کار آن را دنبال کنند و توسعه‌دهندگان بتوانند رفتار آن را درک کرده، بازیابی و بهبود ببخشند.
نظر مهندس بهمن آبادی: توسعه ایجنت‌های هوش مصنوعی از پاسخ‌دهی صرف به سمت معماری سیستم‌های توزیع‌شده حرکت کرده است؛ جایی که الگوهایی مثل CodeAct برای بهینه‌سازی توکن، حافظه معنایی پایدار و مکانیزم‌های بازیابی (Checkpointer)، مرز بین اسکریپت‌های آزمایشی و سرویس‌های Enterprise-grade را تعیین می‌کنند. به عنوان طراح سیستم، تمرکز باید روی جداسازی لایه اجرای ناهمگام و اعمال سیاست‌های Idempotency در ابزارها باشد تا پایداری جریان‌های کاری طولانی‌مدت تضمین شود.