معرفی کانال‌های عامل (Agent) و جریان کاری (Workflow)

Eduard van Valkenburg — 2026-08-26T14:47:23+00:00

چارچوب عامل مایکروسافت برای پایتون (Microsoft Agent Framework for Python)، میزبانی عامل‌های شما را در کانال‌های مختلف با سادگی و انعطاف‌پذیری امکان‌پذیر می‌کند. به تلگرام، A2A، MCP و موارد دیگر متصل شوید.

یک عامل یا جریان کاری زمانی مفید است که افراد و سایر سیستم‌ها بتوانند از طریق رابط‌ها و کانال‌هایی که از قبل استفاده می‌کنند، به آن دسترسی داشته باشند. این رابط ممکن است یک کلاینت پاسخ‌های OpenAI، تلگرام، عامل دیگری با استفاده از A2A یا یک کلاینت MCP باشد. به عنوان سازنده یک عامل و جریان کاری، شما به کنترلی نیاز دارید که تعیین کند عامل را در چه کانال‌هایی در معرض دید قرار دهید و چگونه رفتار کند. برای کمک به این موضوع، ما کانال‌هایی را در چارچوب عامل مایکروسافت برای عامل‌ها و جریان‌های کاری در پایتون معرفی می‌کنیم.

کانال‌های مورد نیاز برنامه‌تان را انتخاب کنید

بسته‌های جدید حول یک هسته میزبانی مشترک کوچک و مجموعه‌ای از یکپارچه‌سازی‌های مختص هر کانال سازماندهی شده‌اند:

• بسته agent-framework-hosting ابزارهای کمکی مشترک برای عامل، جریان کاری و وضعیت نشست (session-state) را فراهم می‌کند.
• بسته agent-framework-hosting-responses درخواست‌ها و نتایج OpenAI Responses را تبدیل می‌کند.
• بسته agent-framework-hosting-telegram به‌روزرسانی‌ها و عملیات خروجی تلگرام را تبدیل می‌کند.
• بسته agent-framework-hosting-a2a عامل‌ها and جریان‌های کاری را به انواع بومی A2A SDK متصل می‌کند.
• بسته agent-framework-hosting-mcp عامل‌ها و جریان‌های کاری را به عنوان ابزارهای بومی MCP ارائه می‌دهد.

هر بسته کانال بر روی مرز پروتکل خود تمرکز دارد. برنامه شما همچنان از فریمورک وب یا SDK بومی انتخابی خود استفاده می‌کند و مدیریت مسیریابی، احراز هویت، مجوزدهی، ذخیره‌سازی، پردازش پس‌زمینه و استقرار را بر عهده دارد.

این بدان معناست که می‌توانید یک یا چند کانال را بدون قرار دادن عامل یا جریان کاری در یک زمان اجرای (runtime) برنامه جدید، یا بدون نیاز به نگهداری چندباره یک عامل با چندین SDK، اضافه کنید.

یک مدل هدف و وضعیت مشترک

بسته agent-framework-hosting پایه و اساس مشترکی را فراهم می‌کند که در هر کانال استفاده می‌شود. کلاس AgentState یک هدف عامل را به همراه ذخیره‌ساز نشست آن نگه می‌دارد، در حالی که WorkflowState یک هدف جریان کاری را از یک نمونه، کارخانه (factory) یا سازنده (builder) حل‌وفصل می‌کند:

    from agent_framework_hosting import AgentState, WorkflowState

agent_state = AgentState(agent)
workflow_state = WorkflowState(workflow_builder, cache_target=False)

  

هر دو نوع وضعیت، یک روش سازگار به هندلرها و آداپتورهای کانال می‌دهند تا هدف خود را حل‌وفصل کنند. هدف را می‌توان مستقیماً ایجاد کرد یا از طریق کد راه‌اندازی همگام یا ناهمگام تأمین کرد، و همچنین می‌توان آن را کش کرد یا برای هر درخواست مجدداً ایجاد نمود.

برای عامل‌ها، AgentState شناسه نشست‌های انتخاب‌شده توسط برنامه را به مقادیر AgentSession نگاشت می‌کند. این بسته عمداً تصمیم نمی‌گیرد که چگونه یک فراخواننده Responses، کاربر تلگرام، زمینه A2A یا کلاینت MCP به یک شناسه نشست تبدیل شود. شما این نگاشت را در برنامه خود می‌سازید؛ کد resolve_session_id در زیر تنها یک کد نمونه از برنامه است، نه تابعی که توسط چارچوب عامل ارائه شده باشد:

    # Application-defined identity and session mapping.
session_id = resolve_session_id(authenticated_user, channel_identity)
session = await agent_state.get_or_create_session(session_id)

  

این نگاشت است که به یک مکالمه اجازه می‌دهد در کانال‌های مختلف ادامه پیدا کند. اگر یک کاربر احراز هویت‌شده‌ی یکسان از طریق Responses و تلگرام به یک شناسه نشست متعارفِ یکسان تبدیل شود، هر دو کانال همان AgentSession را بارگیری و به‌روزرسانی می‌کنند. اگر به شناسه‌های متفاوتی تبدیل شوند، تاریخچه‌های آن‌ها جداگانه باقی می‌ماند. برنامه شما مالک پیوند هویت، مجوزدهی و کنترل‌های همگام‌سازی است که نشست‌های مشترک را امن می‌کنند.

جریان‌های کاری از همان مدل حل‌وفصل هدف از طریق WorkflowState استفاده می‌کنند، در حالی که ذخیره‌سازی نقطه‌بررسی (checkpoint) و نگاشت شناسه‌های ادامه کانال به نقاط‌بررسی، همچنان متعلق به برنامه است. در هر دو نوع هدف، لایه میزبانی مشترک، تعریف عامل یا جریان کاری را مستقل از کانال‌های اطراف آن نگه می‌دارد؛ بسته‌های کانال، ورودی و خروجی مختص پروتکل خود را مدیریت می‌کنند.

پاسخ‌های OpenAI (OpenAI Responses)

ابزارهای کمکی Responses یک درخواست ورودی را به مقادیر اجرایی چارچوب عامل تبدیل کرده و نتیجه تکمیل‌شده یا استریم‌شده را دوباره به قالب Responses تبدیل می‌کنند:

    from agent_framework_hosting_responses import (
    create_response_id,
    responses_from_run,
    responses_session_id,
    responses_to_run,
)

run = responses_to_run(body)
session_id, is_conversation = responses_session_id(body)
response_id = create_response_id()
session = await agent_state.get_or_create_session(session_id or response_id)
result = await (await agent_state.get_target()).run(
    run["messages"],
    session=session,
    options=run["options"],
)
await agent_state.set_session(session_id if is_conversation else response_id, session)
response = responses_from_run(
    result,
    response_id=response_id,
    conversation_id=session_id if is_conversation else None,
)

  

برنامه تصمیم می‌گیرد که شناسه‌های پاسخ و شناسه‌های مکالمه چگونه به نشست‌ها نگاشت شوند. همچنین تصمیم می‌گیرد که فراخوانندگان چه گزینه‌های درخواستی را می‌توانند کنترل کنند، چه زمانی استریم انجام شود، چگونه شناسه‌های ادامه را مجاز بشمارد و وضعیت نشست کجا ذخیره شود.

نمونه عامل Responses قابل اجرا، مسیریابی بومی FastAPI، استریم، ادامه نشست و یک خط‌مشی گزینه‌های متعلق به برنامه را به نمایش می‌گذارد.

جریان‌های کاری می‌توانند از همان رابط Responses استفاده کنند. به جای ذخیره یک AgentSession، برنامه شناسه‌های پاسخ را به نقاط‌بررسی جریان کاری نگاشت می‌کند. برای پیاده‌سازی کامل، به نمونه جریان کاری Responses مراجعه کنید.

تلگرام (Telegram)

ابزارهای کمکی تلگرام، به‌روزرسانی‌های بومی را به ورودی چارچوب عامل ترجمه کرده و یک اجرای استریم‌شده را به عملیات‌های تلگرام تبدیل می‌کنند. برنامه، آن عملیات را از طریق فراخوانی‌های مستقیم HTTP یا یک SDK تلگرام مانند aiogram یا python-telegram-bot اجرا می‌کند.

دستورات (Commands)، احراز هویت وب‌هوک، نظرسنجی (polling)، مدیریت رسانه، محدودسازی نرخ ویرایش (edit throttling) و خط‌مشی تحویل، کدهای معمولی برنامه باقی می‌ مانند. شما همچنین می‌توانید دستورالعمل‌های مختص کانال را به صورت دستی یا از طریق یک ارائه‌دهنده زمینه (context provider) اضافه کنید، مثلاً برای سفارشی‌سازی قالب پاسخ برای تلگرام.

نمونه تلگرام شامل برنامه‌های کامل نظرسنجی و وب‌هوک با استفاده از aiogram است. این نمونه ویرایش‌های استریم‌شده، دستوراتی مانند /new، تبدیل رسانه، ترتیب‌بندی در سطح چت و استمرار نشست را به نمایش می‌گذارد.

A2A و MCP

برای A2A، کلاس‌های AgentA2AAdapter و WorkflowA2AAdapter کارت‌های عامل بومی را تولید می‌کنند و حالت‌های ورودی و خروجی اعلام‌شده را با ابزارهای کمکی تبدیل همگام نگه می‌دارند. برنامه شما همچنان مالک اجراکننده بومی A2A، چرخه عمر وظیفه، صف رویداد، مسیرها و ذخیره‌ساز وظایف است.

نمونه میزبانی A2A نحوه ارائه یک عامل چارچوب عامل را از طریق یک سرور بومی A2A نشان می‌دهد.

برای MCP، کلاس‌های AgentMCPTool و WorkflowMCPTool ابزارهای بومی را از اهداف چارچوب عامل مشتق می‌کنند. برنامه‌ها همچنین می‌توانند از توابع تبدیل رده پایین‌تر با سروری مانند FastMCP یا با هندلرهای ثبت‌شده مستقیم MCP استفاده کنند.

نمونه‌های میزبانی MCP تبدیل دستی، FastMCP، ابزارهای عامل تولیدشده، عامل‌های آگاه از نشست و ابزارهای مشتق‌شده از جریان کاری را پوشش می‌دهند.

ترکیب کانال خود را بسازید

یک عامل یا جریان کاریِ واحد می‌تواند به بیش از یک کانال خدمت‌رسانی کند. هر کانال می‌تواند قوانین مجوزدهی و دستورالعمل‌های ارائه‌ی خاص خود را داشته باشد، در حالی که هدف زیرین و زیرساخت برنامه را به اشتراک می‌گذارد.

به عنوان توسعه‌دهنده، شما حل‌کننده‌ای (resolver) را تعریف می‌کنید که هویت مختص کانال را به یک شناسه نشست نگاشت می‌کند. یک حل‌کننده یکپارچه به کاربر اجازه می‌دهد در یک کلاینت Responses شروع کرده و در تلگرام ادامه دهد، یا بین هر کانال پشتیبانی‌شده‌ی دیگری جابه‌جا شود، بدون اینکه نیاز به شروع یک مکالمه جدید باشد. نگه داشتن هویت‌های کانال در فضاهای نام جداگانه نیز هر زمان که تجربه کاربری مورد نظر باشد، همچنان در دسترس است.

این انعطاف‌پذیری در مورد فریمورک برنامه نیز صدق می‌کند. نمونه‌های HTTP فعلی از FastAPI استفاده می‌کنند، اما ابزارهای کمکی در مرز تبدیل پروتکل و وضعیت اجرا عمل می‌کنند. شما می‌توانید آن‌ها را با جنگو (Django)، فلاسگ (Flask)، یک فریمورک وب دیگر پایتون، یک سرویس موجود یا یک SDK پروتکل بومی یکپارچه کنید.

گام بعدی…

ما برنامه‌ریزی کرده‌ایم که با ارائه کانال‌های بیشتر، ابزارهای کمکی اضافی و سایر ویژگی‌ها برای ساده‌تر کردن میزبانی عامل شما، این قابلیت را بیش از پیش گسترش دهیم! اما برای ساختن موارد درست، می‌خواهیم نظرات شما را بشنویم؛ اینکه چه چیزی کار می‌کند، چه چیزی کار نمی‌کند، و برای تکمیل سناریوی خود از ابتدا تا انتها به چه چیز دیگری نیاز دارید. بنابراین، از این بسته‌ها برای اتصال یک عامل یا جریان کاری چارچوب عامل به پروتکل‌ها و کانال‌هایی که کاربرانتان نیاز دارند، در داخل برنامه و زیرساختی که هم‌اکنون از آن استفاده می‌کنید، بهره ببرید.

با مستندات میزبانی چارچوب عامل و نمونه‌های قابل‌اجرای لینک‌شده در بالا شروع کنید، ترکیب کانالی که متناسب با کاربران شماست را بسازید، و در بخش مسئله پایتون: کانال‌ها شماره 6265 به ما بگویید چه چیزی به خوبی کار می‌کند و به چه یکپارچه‌سازی‌هایی در قدم بعدی نیاز دارید.