Microsoft مهام سير عمل إطار عمل العامل - استخدام مهام سير العمل كعوامل

يوفر هذا المستند نظرة عامة حول كيفية استخدام مهام سير العمل كعوامل في إطار عمل عامل Microsoft.

نظرة عامة

في بعض الأحيان قمت ببناء سير عمل متطور مع عوامل متعددة ومنفذين مخصصين ومنطق معقد - ولكنك تريد استخدامه تماما مثل أي عامل آخر. هذا بالضبط ما يتيح لك وكلاء سير العمل القيام به. من خلال التفاف سير العمل الخاص بك ك Agent، يمكنك التفاعل معه من خلال نفس واجهة برمجة التطبيقات المألوفة التي تستخدمها لعامل دردشة بسيط.

الفوائد الرئيسة

• الواجهة الموحدة: التفاعل مع مهام سير العمل المعقدة باستخدام نفس واجهة برمجة التطبيقات مثل العوامل البسيطة
• توافق واجهة برمجة التطبيقات: دمج مهام سير العمل مع الأنظمة الموجودة التي تدعم واجهة العامل
• إمكانية الإنشاء: استخدام عوامل سير العمل ككتل إنشاء في أنظمة عوامل أكبر أو مهام سير عمل أخرى
• إدارة الجلسة: الاستفادة من جلسات عمل العامل لحالة المحادثة والاستئناف
• دعم الدفق: الحصول على تحديثات في الوقت الحقيقي أثناء تنفيذ سير العمل

كيفية عملها

عند تحويل سير عمل إلى عامل:

1. يتم التحقق من صحة سير العمل للتأكد من أن منفذ البداية الخاص به يمكنه قبول أنواع الإدخال المطلوبة
2. يتم إنشاء جلسة عمل لإدارة حالة المحادثة
3. يتم توجيه رسائل الإدخال إلى منفذ بدء سير العمل
4. يتم تحويل أحداث سير العمل إلى تحديثات استجابة العامل
5. تظهر طلبات الإدخال الخارجية (من RequestInfoExecutor) كمكالمات دالة

متطلبات

لاستخدام سير عمل كعامل، يجب أن يكون منفذ بدء سير العمل قادرا على التعامل معه IEnumerable<ChatMessage> كمدخل. يتم استيفاء هذا تلقائيا عند استخدام المنفذين المستندين إلى العامل الذين تم إنشاؤهم باستخدام AsAIAgent.

إنشاء عامل سير عمل

استخدم أسلوب الملحق AsAIAgent() لتحويل أي سير عمل متوافق إلى عامل:

using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Workflows;
using Microsoft.Extensions.AI;

// Create agents
AIAgent researchAgent = chatClient.AsAIAgent("You are a researcher. Research and gather information on the given topic.");
AIAgent writerAgent = chatClient.AsAIAgent("You are a writer. Write clear, engaging content based on research.");
AIAgent reviewerAgent = chatClient.AsAIAgent("You are a reviewer. Review the content and provide a final polished version.");

// Build a sequential workflow
var workflow = new WorkflowBuilder(researchAgent)
    .AddEdge(researchAgent, writerAgent)
    .AddEdge(writerAgent, reviewerAgent)
    .Build();

// Convert the workflow to an agent
AIAgent workflowAgent = workflow.AsAIAgent(
    id: "content-pipeline",
    name: "Content Pipeline Agent",
    description: "A multi-agent workflow that researches, writes, and reviews content"
);

معلمات AsAIAgent

المعلمه	Type	Description
id	string?	معرف فريد اختياري للعامل. يتم إنشاؤه تلقائيا إذا لم يتم توفيره.
name	string?	اسم العرض الاختياري للعامل.
description	string?	وصف اختياري لغرض العامل.
executionEnvironment	IWorkflowExecutionEnvironment?	بيئة التنفيذ الاختيارية. الإعدادات الافتراضية لتكوين سير العمل أو InProcessExecution.Concurrent استنادا إليهInProcessExecution.OffThread.
includeExceptionDetails	bool	إذا true، يتضمن رسائل استثناء في محتوى الخطأ. تتغير افتراضيا إلى false.
includeWorkflowOutputsInResponse	bool	إذا true، يحول مخرجات سير العمل الصادرة إلى محتوى في استجابات العامل. تتغير افتراضيا إلى false.

استخدام عوامل سير العمل

إنشاء جلسة عمل

تتطلب كل محادثة مع عامل سير عمل جلسة عمل لإدارة الحالة:

// Create a new session for the conversation
AgentSession session = await workflowAgent.CreateSessionAsync();

التنفيذ غير المتدفق

لحالات الاستخدام البسيطة حيث تريد الاستجابة الكاملة:

var messages = new List<ChatMessage>
{
    new(ChatRole.User, "Write an article about renewable energy trends in 2025")
};

AgentResponse response = await workflowAgent.RunAsync(messages, session);

foreach (ChatMessage message in response.Messages)
{
    Console.WriteLine($"{message.AuthorName}: {message.Text}");
}

تنفيذ الدفق

للحصول على تحديثات في الوقت الحقيقي أثناء تنفيذ سير العمل:

var messages = new List<ChatMessage>
{
    new(ChatRole.User, "Write an article about renewable energy trends in 2025")
};

await foreach (AgentResponseUpdate update in workflowAgent.RunStreamingAsync(messages, session))
{
    // Process streaming updates from each agent in the workflow
    if (!string.IsNullOrEmpty(update.Text))
    {
        Console.Write(update.Text);
    }
}

معالجة طلبات الإدخال الخارجية

عندما يحتوي سير العمل على منفذين يطلبون إدخالا خارجيا (باستخدام RequestInfoExecutor)، تظهر هذه الطلبات كمكالمات دالة في استجابة العامل:

await foreach (AgentResponseUpdate update in workflowAgent.RunStreamingAsync(messages, session))
{
    // Check for function call requests
    foreach (AIContent content in update.Contents)
    {
        if (content is FunctionCallContent functionCall)
        {
            // Handle the external input request
            Console.WriteLine($"Workflow requests input: {functionCall.Name}");
            Console.WriteLine($"Request data: {functionCall.Arguments}");

            // Provide the response in the next message
        }
    }
}

تسلسل الجلسة واستئنافها

يمكن تسلسل جلسات عمل عامل سير العمل لاستمرارها واستئنافها لاحقا:

// Serialize the session state
JsonElement serializedSession = await workflowAgent.SerializeSessionAsync(session);

// Store serializedSession to your persistence layer...

// Later, resume the session
AgentSession resumedSession = await workflowAgent.DeserializeSessionAsync(serializedSession);

// Continue the conversation
await foreach (var update in workflowAgent.RunStreamingAsync(newMessages, resumedSession))
{
    Console.Write(update.Text);
}

Important

تحتوي جلسة عمل عامل سير العمل المتسلسلة على نقطة التحقق الداخلية لسير العمل. إذا كان التطبيق الخاص بك يعيد بناء سير العمل قبل إلغاء تسلسل جلسة العمل أو تشغيلها، يجب إعادة إنشاء كل عامل داخلي بنفس ChatClientAgentOptions.Id (وإذا Name تم تعيين، نفس ).Name

يعرف id الذي تم تمريره إلى workflow.AsAIAgent(...) عامل سير العمل الخارجي فقط. لا يستقر هويات المنفذ للوكلاء داخل سير العمل. للحصول على إرشادات التكوين، راجع إعادة الترطيب من نقاط التحقق.

متطلبات

لاستخدام سير عمل كعامل، يجب أن يكون منفذ بدء سير العمل قادرا على معالجة إدخال الرسالة. يتم استيفاء هذا تلقائيا عند استخدام Agent المنفذين المستندين إلى عامل أو.

إنشاء عامل سير عمل

اتصل as_agent() بأي سير عمل متوافق لتحويله إلى عامل:

from agent_framework.foundry import FoundryChatClient
from agent_framework.orchestrations import SequentialBuilder
from azure.identity import AzureCliCredential

# Create your chat client and agents
client = FoundryChatClient(
    project_endpoint="<your-endpoint>",
    model="<your-deployment>",
    credential=AzureCliCredential(),
)

researcher = client.as_agent(
    name="Researcher",
    instructions="Research and gather information on the given topic.",
)

writer = client.as_agent(
    name="Writer",
    instructions="Write clear, engaging content based on research.",
)

# Build a sequential workflow
workflow = SequentialBuilder(participants=[researcher, writer]).build()

# Convert the workflow to an agent
workflow_agent = workflow.as_agent(name="Content Pipeline Agent")

معلمات as_agent

المعلمه	Type	Description
name	str | None	اسم العرض الاختياري للعامل. يتم إنشاؤه تلقائيا إذا لم يتم توفيره.

استخدام عوامل سير العمل

إنشاء جلسة عمل

يمكنك اختياريا إنشاء جلسة عمل لإدارة حالة المحادثة عبر عدة دورات:

# Create a new session for the conversation
session = await workflow_agent.create_session()

Note

جلسات العمل اختيارية. إذا لم تمرر session إلى run()، فإن العامل يعالج الحالة داخليا. إذا workflow.as_agent() تم إنشاء بدون context_providers، يضيف InMemoryHistoryProvider() إطار العمل بشكل افتراضي بحيث تعمل المحفوظات متعددة الأدوار خارج الصندوق. إذا قمت بتمريرها context_providers بشكل صريح، يتم استخدام هذه القائمة as-is.

التنفيذ غير المتدفق

لحالات الاستخدام البسيطة حيث تريد الاستجابة الكاملة:

# You can pass a plain string as input
response = await workflow_agent.run("Write an article about AI trends")

for message in response.messages:
    print(f"{message.author_name}: {message.text}")

تنفيذ الدفق

للحصول على تحديثات في الوقت الحقيقي أثناء تنفيذ سير العمل:

async for update in workflow_agent.run(
    "Write an article about AI trends",
    stream=True,
):
    if update.text:
        print(update.text, end="", flush=True)

معالجة طلبات الإدخال الخارجية

عندما يحتوي سير العمل على منفذين يطلبون إدخالا خارجيا (باستخدام request_info)، تظهر هذه الطلبات كمكالمات دالة في استجابة العامل. يستخدم استدعاء الدالة الاسم WorkflowAgent.REQUEST_INFO_FUNCTION_NAME:

from agent_framework import Content, Message, WorkflowAgent

response = await workflow_agent.run("Process my request")

# Look for function calls in the response
human_review_function_call = None
for message in response.messages:
    for content in message.contents:
        if content.name == WorkflowAgent.REQUEST_INFO_FUNCTION_NAME:
            human_review_function_call = content

توفير الاستجابات للطلبات المعلقة

لمتابعة تنفيذ سير العمل بعد طلب إدخال خارجي، أنشئ نتيجة دالة وأرسلها مرة أخرى:

if human_review_function_call:
    # Parse the request arguments
    request = WorkflowAgent.RequestInfoFunctionArgs.from_json(
        human_review_function_call.arguments
    )

    # Create a response (your custom response type)
    result_data = MyResponseType(approved=True, feedback="Looks good")

    # Create the function call result
    function_result = Content.from_function_result(
        call_id=human_review_function_call.call_id,
        result=result_data,
    )

    # Send the response back to continue the workflow
    response = await workflow_agent.run(Message("tool", [function_result]))

مثال كامل

فيما يلي مثال كامل يوضح عامل سير العمل مع إخراج الدفق:

import asyncio
import os

from agent_framework.foundry import FoundryChatClient
from agent_framework.orchestrations import SequentialBuilder
from azure.identity import AzureCliCredential


async def main():
    # Set up the chat client
    client = FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
        model=os.environ["FOUNDRY_MODEL"],
        credential=AzureCliCredential(),
    )

    # Create specialized agents
    researcher = client.as_agent(
        name="Researcher",
        instructions="Research the given topic and provide key facts.",
    )

    writer = client.as_agent(
        name="Writer",
        instructions="Write engaging content based on the research provided.",
    )

    reviewer = client.as_agent(
        name="Reviewer",
        instructions="Review the content and provide a final polished version.",
    )

    # Build a sequential workflow
    workflow = SequentialBuilder(participants=[researcher, writer, reviewer]).build()

    # Convert to a workflow agent
    workflow_agent = workflow.as_agent(name="Content Creation Pipeline")

    # Run the workflow
    print("Starting workflow...")
    print("=" * 60)

    current_author = None
    async for update in workflow_agent.run(
        "Write about quantum computing",
        stream=True,
    ):
        # Show when different agents are responding
        if update.author_name and update.author_name != current_author:
            if current_author:
                print("\n" + "-" * 40)
            print(f"\n[{update.author_name}]:")
            current_author = update.author_name

        if update.text:
            print(update.text, end="", flush=True)

    print("\n" + "=" * 60)
    print("Workflow completed!")


if __name__ == "__main__":
    asyncio.run(main())

فهم تحويل الحدث

عند تشغيل سير عمل كعامل، يتم تحويل أحداث سير العمل إلى استجابات العامل. يعتمد نوع الاستجابة على كيفية استدعاء run():

• run(): إرجاع تحتوي AgentResponse على النتيجة الكاملة بعد انتهاء سير العمل
• run(..., stream=True): إرجاع الكائنات غير المتزامنة أثناء AgentResponseUpdate تنفيذ سير العمل، مما يوفر تحديثات في الوقت الحقيقي

as_agent() إعادة توجيه كل من "output" (المحطة الطرفية) والأحداث "intermediate" إلى المتصل. مجموعة أنواع الأحداث التي تمت إعادة توجيهها هي AGENT_FORWARDED_EVENT_TYPES = {"output", "intermediate"}. يتم إسقاط كافة الأحداث الداخلية لسير العمل الأخرى.

أثناء التنفيذ، يتم تعيين أحداث سير العمل الداخلية إلى استجابات العامل كما يلي:

حدث سير العمل	استجابة الوكيل
event.type == "output"	إجابة المحطة الطرفية - تم تمريرها ك AgentResponseUpdate (دفق) أو مجمعة في AgentResponse (غير دفق). response.text إرجاع مخرجات المحطة الطرفية هذه فقط.
event.type == "intermediate"	تقدم المراقبة — يتم عرضه كمحتوى text_reasoning في AgentResponseUpdate. غير مضمن في response.text.
event.type == "request_info"	تم تحويله إلى محتوى استدعاء دالة باستخدام WorkflowAgent.REQUEST_INFO_FUNCTION_NAME
أحداث أخرى	تم تجاهله (سير العمل الداخلي فقط)

يسمح لك هذا التحويل باستخدام واجهة العامل القياسية مع الاستمرار في الوصول إلى معلومات سير العمل التفصيلية عند الحاجة. تقوم .text الخاصية على كل من AgentResponse وإرجاع AgentResponseUpdate إجابة المحطة الطرفية ("output") فقط؛ فحص text_reasoning عناصر المحتوى للوصول إلى التقدم المتوسط.

يلتف Go مهام سير العمل كوكلاء مع workflow/agentworkflow. يتيح هذا للمتصلين استخدام واجهات برمجة التطبيقات لتشغيل العامل العادي أثناء تنفيذ الموفر لسير العمل خلف الكواليس.

متطلبات

يجب أن يقبل []*message.Messageمنفذ بدء سير العمل . منفذو العامل المستضاف والمنفذون المكونون مع messageworkflow.Configure تلبية هذا المطلب.

إنشاء عامل سير عمل

استخدم agentworkflow.New لتضمين أي سير عمل متوافق كعامل:

wfAgent, err := agentworkflow.New(wf, agentworkflow.AgentConfig{
    IncludeOutputsInResponse: true,
    Config: agent.Config{
        Name: "WorkflowAgent",
    },
})
if err != nil {
    return err
}

تدفق عمل العامل. معلمات تكوين العامل

المعلمه	Type	Description
Config	agent.Config	تكوين العامل المضمن، بما في ذلك الاسم والوصف والبرامج الوسيطة والأدوات وخيارات التشغيل.
Environment	*inproc.ExecutionEnvironment	بيئة التنفيذ الاختيارية. الإعدادات الافتراضية ل inproc.OffThreadأو إلى inproc.Concurrent عندما يسمح سير العمل بالتنفيذ المتزامن.
IncludeErrorDetails	bool	إذا true، يتضمن رسائل خطأ سير العمل التفصيلية في استجابات العامل. تتغير افتراضيا إلى false.
IncludeOutputsInResponse	bool	إذا true، يحول مخرجات رسالة سير العمل الصادرة إلى محتوى في استجابات العامل. تتغير افتراضيا إلى false.

استخدام عوامل سير العمل

إنشاء جلسة عمل

إنشاء جلسة عمل عامل عندما تريد استمرار حالة سير العمل عبر المنعطفات:

session, err := wfAgent.CreateSession(ctx)
if err != nil {
    return err
}

التنفيذ غير المتدفق

استخدم RunText الاستجابة للتنفيذ غير المتدفق أو Run اجمعها:

response, err := wfAgent.RunText(ctx, "Analyze this", agent.WithSession(session)).Collect()
if err != nil {
    return err
}
fmt.Println(response.String())

تنفيذ الدفق

للحصول على تحديثات في الوقت الحقيقي أثناء تنفيذ سير العمل:

for update, err := range wfAgent.RunText(ctx, "Analyze this", agent.WithSession(session), agent.Stream(true)) {
    if err != nil {
        return err
    }
    fmt.Print(update.String())
}

معالجة طلبات الإدخال الخارجية

تظهر الطلبات الخارجية من سير العمل كمحتوى استدعاء دالة في استجابة العامل. افحص رسائل الاستجابة بحثا عن محتوى الطلب وأرسل الاستجابة المطابقة في تشغيل لاحق.

var requestCall *message.FunctionCallContent
for content := range response.Contents() {
    if call, ok := content.(*message.FunctionCallContent); ok {
        requestCall = call
        break
    }
}

توفير الاستجابات للطلبات المعلقة

لمتابعة تنفيذ سير العمل، قم بإرجاع محتوى الاستجابة المطابق إلى عامل سير العمل:

result := &message.FunctionResultContent{
    CallID: requestCall.CallID,
    Result: "approved",
}

response, err = wfAgent.Run(
    ctx,
    []*message.Message{{
        Role:     message.RoleTool,
        Contents: []message.Content{result},
    }},
    agent.WithSession(session),
).Collect()
if err != nil {
    return err
}

تسلسل الجلسة واستئنافها

يمكن تسلسل جلسات عمل عامل سير العمل لاستمرارها واستئنافها لاحقا:

// Serialize the session state.
serializedSession, err := json.Marshal(session)
if err != nil {
    return err
}

// Store serializedSession to your persistence layer...

// Later, resume the session.
var resumedSession agent.Session
if err := json.Unmarshal(serializedSession, &resumedSession); err != nil {
    return err
}

for update, err := range wfAgent.RunText(ctx, "Continue the article", agent.WithSession(&resumedSession), agent.Stream(true)) {
    if err != nil {
        return err
    }
    fmt.Print(update.String())
}

مثال كامل

ينشئ المثال التالي سير عمل البنية الأساسية لبرنامج ربط العمليات التجارية للمحتوى، ويلفه كعامل، ويتدفق الاستجابات من خلال واجهة برمجة تطبيقات العامل العادي:

package main

import (
    "cmp"
    "context"
    "fmt"
    "log"
    "os"

    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
    "github.com/microsoft/agent-framework-go/workflow/agentworkflow"

    "github.com/Azure/azure-sdk-for-go/sdk/azidentity"
)

func main() {
    ctx := context.Background()
    endpoint := os.Getenv("FOUNDRY_PROJECT_ENDPOINT")
    model := cmp.Or(os.Getenv("FOUNDRY_MODEL"), "gpt-4o-mini")

    credential, err := azidentity.NewDefaultAzureCredential(nil)
    if err != nil {
        log.Fatal(err)
    }

    researcher := foundryprovider.NewAgent(endpoint, credential, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
        Instructions: "Research and gather information on the given topic.",
        Config:      agent.Config{Name: "Researcher"},
    })
    writer := foundryprovider.NewAgent(endpoint, credential, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
        Instructions: "Write clear, engaging content based on research.",
        Config:      agent.Config{Name: "Writer"},
    })
    reviewer := foundryprovider.NewAgent(endpoint, credential, foundryprovider.ModelDeployment(model), foundryprovider.AgentConfig{
        Instructions: "Review the content and provide a final polished version.",
        Config:      agent.Config{Name: "Reviewer"},
    })

    wf, err := agentworkflow.NewSequentialWorkflowBuilder(researcher, writer, reviewer).
        WithName("content-pipeline").
        Build()
    if err != nil {
        log.Fatal(err)
    }

    wfAgent, err := agentworkflow.New(wf, agentworkflow.AgentConfig{
        IncludeOutputsInResponse: true,
        Config: agent.Config{
            Name: "Content Pipeline Agent",
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    session, err := wfAgent.CreateSession(ctx)
    if err != nil {
        log.Fatal(err)
    }

    for update, err := range wfAgent.RunText(ctx, "Write about quantum computing", agent.WithSession(session), agent.Stream(true)) {
        if err != nil {
            log.Fatal(err)
        }
        if text := update.String(); text != "" {
            fmt.Print(text)
        }
    }
}

تحذير

azidentity.NewDefaultAzureCredential مناسب للتنمية ولكنه يتطلب دراسة متأنية في الإنتاج. في الإنتاج، ضع في اعتبارك استخدام بيانات اعتماد معينة، مثل azidentity.NewManagedIdentityCredential، لتجنب مشكلات زمن الانتقال، وبحث بيانات الاعتماد غير المقصودة، والمخاطر الأمنية المحتملة من الآليات الاحتياطية.

Tip

راجع سير العمل كعينة عامل للحصول على مثال كامل قابل للتشغيل.

حالات الاستخدام

1. البنية الأساسية لبرنامج ربط العمليات التجارية المعقدة للعامل

التفاف سير عمل متعدد العوامل كعامل واحد للاستخدام في التطبيقات:

User Request --> [Workflow Agent] --> Final Response
                      |
                      +-- Researcher Agent
                      +-- Writer Agent  
                      +-- Reviewer Agent

2. تكوين العامل

استخدام عوامل سير العمل كمكونات في أنظمة أكبر:

• يمكن استخدام عامل سير عمل كأداة من قبل عامل آخر
• يمكن تنسيق عوامل سير عمل متعددة معا
• يمكن تداخل عوامل سير العمل ضمن مهام سير العمل الأخرى

3. تكامل واجهة برمجة التطبيقات

كشف مهام سير العمل المعقدة من خلال واجهات برمجة التطبيقات التي تتوقع واجهة العامل القياسية، مما يتيح:

• واجهات الدردشة التي تستخدم مهام سير عمل خلفية متطورة
• التكامل مع الأنظمة القائمة على الوكيل الحالية
• الترحيل التدريجي من العوامل البسيطة إلى مهام سير العمل المعقدة

الخطوات التالية

• تعرف على كيفية التعامل مع الطلبات والاستجابات في مهام سير العمل
• تعرف على كيفية إدارة الحالة في مهام سير العمل
• تعرف على كيفية إنشاء نقاط التحقق والاستئناف منها
• تعرف على كيفية مراقبة مهام سير العمل
• تعرف على عزل الحالة في مهام سير العمل
• تعرف على كيفية تصور مهام سير العمل