عامل Harness

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

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

Architecture

يؤلف Harness كتل إنشاء إطار عمل العامل الموجودة بدلا من تحديد وقت تشغيل وكيل منفصل:

1. عميل الدردشة — يربط العامل بنموذج.
2. مسار الدردشة — يضيف استدعاء الدالة، وحقن الرسائل، واستمرار محفوظات استدعاء كل خدمة، والضغط الاختياري.
3. موفرو الوكيل والسياق — أضف إرشادات وأدوات وذاكرة وحالة المهام وأوضاع التشغيل والقدرات الاختيارية في نطاق الجلسة.
4. البرامج الوسيطة والمزخرفات — أضف معالجة الموافقة وإمكانية الملاحظة والتكرارات الحلقية الاختيارية المحددة.
5. تجربة المستخدم للتطبيق — يبث الاستجابات ويعرض التقدم ويجمع الإدخال مثل موافقات الأدوات.

يبقى الكائن الناتج عامل إطار عمل عامل عادي: HarnessAgent مشتق من AIAgent في .NET، Agent أو تم إرجاعه بواسطة create_harness_agent في Python، أو موفر مدعوم *agent.Agent تم تكوينه باستخدام harness.AgentConfig في Go. تستخدم جلسات العمل الخاصة به نفس تجريدات جلسة العملوموفر السياق مثل العوامل الأخرى.

مصفوفة قدرة Harness

Capability	سلوك Harness	إرشادات متعارف عليه
استدعاء الدالة	ممكن بحد تكرار قابل للتكوين لكل طلب. تمتلك منشئات موفر Go حلقة استدعاء الأدوات.	أدوات الدوال
استمرار محفوظات المكالمة لكل خدمة	تستمر المحفوظات بعد كل استدعاء نموذج في تشغيل استدعاء الأدوات.	جلسات العمل
الضغط	يتم تمكينه عند توفير حدود الرمز المميز أو استراتيجية مخصصة في .NET Python. يتطلب Go تكوين موفر صريح.	الضغط
تعقب المهام	ممكَّن بشكل افتراضي.	التخطيط و todos
أوضاع العامل	يتم تمكين أوضاع التخطيط والتنفيذ بشكل افتراضي.	التخطيط و todos
ذاكرة الملف والوصول إلى الملفات	يتم تمكين ذاكرة ملف جلسة العمل بشكل افتراضي؛ الوصول إلى الملفات المشتركة هو الاشتراك.	موفرو السياق
الموافقة على الأداة	يتم تمكين الموافقات الدائمة وقواعد الموافقة التلقائية بشكل افتراضي.	الموافقة على الأداة
التتبع المفتوح	يتم تمكين إمكانية مراقبة العامل بشكل افتراضي.	إمكانية المراقبة
البحث على الويب	تمت إضافته بشكل افتراضي حيث يدعمه عميل الدردشة المحدد.	البحث على الويب
مهارات الوكيل	ممكن افتراضيا في .NET وGo؛ الاشتراك من خلال موفر أو مسارات في Python.	مهارات العامل
وكلاء الخلفية	تفويض متوازي اختياري إلى عوامل تابعة مسماة في .NET Python. لم يتم حزم موفر وكيل الخلفية Go.	وكلاء الخلفية
تنفيذ Shell	مكون من حزمة shell؛ يمكن لمصنع Python توصيله تلقائيا.	أدوات Shell
التكرار الحلقي	إعادة استدعاء محددة اختيارية مدفوعة من قبل المقيمين أو المسندات.	التكرار الحلقي للعامل

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

Tip

للحصول على إرشادات وكيل الترميز التي تساعد على إنشاء تطبيق Python harness، قم بتثبيت agent-framework-builder-python. هذه المهارة الخارجية لعامل الترميز منفصلة عن إمكانية مهارات عامل وقت التشغيل المدرجة في المصفوفة.

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

تعرض Microsoft.Agents.AI.Harness الحزمة HarnessAgent في Microsoft.Agents.AI مساحة الاسم. إنشاء واحد من أي IChatClient باستخدام AsHarnessAgent، أو إنشاء HarnessAgent مباشرة:

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

AIAgent agent = chatClient.AsHarnessAgent();

AgentResponse response = await agent.RunAsync("Plan a weekend trip to Seattle.");
Console.WriteLine(response.Text);

يستخدم HarnessAgentOptions لتعيين إرشادات التشغيل على مستوى التسخير والتعليمات الخاصة بالوكيل وخيارات الميزات:

AIAgent agent = chatClient.AsHarnessAgent(new HarnessAgentOptions
{
    Name = "research-agent",
    HarnessInstructions = "Use tools deliberately and report verified results.",
    ChatOptions = new ChatOptions
    {
        Instructions = "You are a research assistant focused on academic sources.",
    },
    MaxContextWindowTokens = 128_000,
    MaxOutputTokens = 16_384,
});

HarnessAgent.DefaultInstructions يوفر إرشادات التسخير الافتراضية. HarnessInstructions يظهر قبل ChatOptions.Instructions.

تخصيص التكوين

تحتوي القدرات الافتراضية على خيارات مستهدفة، بما في ذلك DisableTodoProviderDisableAgentModeProviderDisableFileMemoryو و DisableAgentSkillsProviderو.DisableCompactionDisableWebSearchDisableToolAutoApprovalDisableOpenTelemetry

إضافة موفري سياق مخصصين باستخدام AIContextProviders. اشترك في الوصول إلى الملفات باستخدام FileAccessStore، وتفويض الخلفية مع BackgroundAgents، والتكرار الحلقي باستخدام LoopEvaluators.

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

يقوم create_harness_agent المصنع بإرجاع مكون Agentبالكامل :

from agent_framework import create_harness_agent
from agent_framework.openai import OpenAIChatClient

agent = create_harness_agent(
    client=OpenAIChatClient(model="gpt-4o"),
)

session = agent.create_session()
response = await agent.run("Plan a weekend trip to Seattle.", session=session)
print(response.text)

تعيين التعليمات الخاصة بمستوى التسخير والعامل بشكل منفصل:

agent = create_harness_agent(
    client=client,
    name="research-agent",
    harness_instructions="Use tools deliberately and report verified results.",
    agent_instructions="You are a research assistant focused on academic sources.",
    max_context_window_tokens=128_000,
    max_output_tokens=16_384,
)

DEFAULT_HARNESS_INSTRUCTIONS يوفر إرشادات التسخير الافتراضية. harness_instructions يظهر قبل agent_instructions.

تخصيص التكوين

تعطيل الإعدادات الافتراضية بخيارات مثل disable_todoو disable_modedisable_file_memoryوdisable_tool_auto_approvaldisable_web_search.disable_compaction

استبدل الموفرين المضمنين ب todo_provider أو mode_provider، وأضف موفرين ب context_providers. المهارات هي الاشتراك من خلال skills_provider أو skills_paths؛ الوصول إلى الملفات، وكلاء الخلفية، أدوات shell، والتكرار الحلقي هي أيضا الاشتراك.

يستخدم الوصول إلى الملفات المخزن الذي تم توفيره كمساحة عمل مشتركة واحدة بشكل افتراضي. لعزل الملفات بواسطة معرف جلسة العمل النشط، قم بتمكين الوصول إلى الملفات ذات نطاق جلسة العمل:

from agent_framework import FileSystemAgentFileStore, create_harness_agent

file_store = FileSystemAgentFileStore("agent-files")
agent = create_harness_agent(
    client=client,
    file_access_store=file_store,
    file_access_session_scoped=True,
)

للمشاركة المتعمدة عبر جلسات عمل محددة، أنشئها FileAccessProvider(store=file_store, scope="tenant-1") مباشرة وأضفها من خلال context_providers. النطاق هو مفتاح مبهم يعين إلى مجلد مدار من قبل الموفر، وليس مسارا. فشل الوصول المحدد النطاق مغلقا بدلا من استخدام جذر المخزن المشترك عندما لا يتوفر معرف جلسة نشط ولا نطاق صريح.

استخدم tool_name_prefix عندما يكون لدى عامل واحد العديد من موفري الوصول إلى الملفات. تنتج البادئة أسماء مثل workspace_file_access_read وتمنع تضارب اسم الأداة. بالنسبة للموفرين البادئين، استخدم مصانع قواعد الموافقة الخاصة بالموفر بحيث تتطابق كل قاعدة مع أسماء الموفر التي تم إنشاؤها:

from agent_framework import FileAccessProvider, create_harness_agent

workspace = FileAccessProvider(
    store=file_store,
    tool_name_prefix="workspace",
)

agent = create_harness_agent(
    client=client,
    context_providers=[workspace],
    auto_approval_rules=[workspace.get_read_only_tools_auto_approval_rule()],
)

get_all_tools_auto_approval_rule() ينشئ قاعدة مكافئة لكل من أدوات القراءة والكتابة. حافظ على تمكين الموافقة على الكتابة ما لم تكن حدود التخزين وإدخالات الأدوات موثوقة.

عند تمكين الوصول إلى الملفات، استخدم file_access_grep للبحث عن أرقام أسطر مستندة إلى 1، file_access_read_lines ولفحص نطاق شامل، ولتحرير file_access_replace_lines أسطر كاملة. file_access_read_lines بادئة كل سطر برقمه وعلامة تبويب؛ احذف هذه البادئة عند تمرير نص السطر ك expected_line. يمنع النص المتوقع رقم سطر قديم أو غير متطابق من تحرير السطر الخطأ.

file_access_grep يستخدم تعبيرات عادية غير حساسة لحالة الأحرف، ويقبل أنماطا تصل إلى 256 حرفا، ويطبق ميزانية 10 ثوان على البحث بأكمله. ترجع الأنماط وعمليات البحث غير الصالحة أو التي تتجاوز الموازنة خطأ. تضييق الدليل أو النمط قبل إعادة المحاولة.

Important

file_access_grep إرجاع نص سطر مطابق مع فاصل الأسطر الخاص به. يجب أن يرجع التنفيذ المخصص AgentFileStore.search() أرقام أسطر مستندة إلى 1 تعالج نفس الأسطر كما هو الحال AgentFileStore.split_lines() عبر النص الذي تم إرجاعه بواسطة read().

Note

create_harness_agent تم إصداره. يظل وكلاء الخلفية والوصول إلى الملفات والتكرارات الحلقية تجريبية، وتأتي أدوات shell من حزمة ما قبل الإصدار agent-framework-tools .

تجمع حزمة Go agent/harness البرامج الوسيطة وموفري السياق والمحفوظات الافتراضية لعامل عادي مدعوم من الموفر. استدعاء harness.AgentConfig(harness.Config{}, agent.Config{...})، ومعالجة الخطأ الخاص به، وتمرير التكوين الذي تم إرجاعه إلى منشئ الموفر. لا يقدم نوع وكيل منفصل أو حلقة تنفيذ أداة.

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

تقوم العينة المركبة بتكوين عامل تسخير مدعوم من Foundry:

import (
    "context"
    "fmt"
    "os"
    "path/filepath"

    "github.com/microsoft/agent-framework-go/agent"
    "github.com/microsoft/agent-framework-go/agent/harness"
    "github.com/microsoft/agent-framework-go/examples/internal/demo"
    "github.com/microsoft/agent-framework-go/message"
    "github.com/microsoft/agent-framework-go/provider/foundryprovider"
)
    workingDirectory, err := os.Getwd()
    if err != nil {
        return fmt.Errorf("get working directory: %w", err)
    }
    cfg, err := harness.AgentConfig(harness.Config{WorkingDirectory: workingDirectory}, agent.Config{
        Name:        "HarnessAssistant",
        Middlewares: []agent.Middleware{logger},
    })
    if err != nil {
        return err
    }
    a := foundryprovider.NewAgent(
        demo.FoundryProjectEndpoint,
        demo.FoundryTokenCredential(),
        foundryprovider.ModelDeployment(demo.FoundryModel),
        foundryprovider.AgentConfig{
            Config:             cfg,
            DisableStoreOutput: true,
            Instructions:       "Help with software engineering tasks. Use memory and todos to track the current session's work.",
        },
    )

تخصيص التكوين

يمكن المساعد الإعدادات الافتراضية التالية:

المكون	Go harness default
التخطيط	أدوات المهام المدعومة بجلسة العمل وأوضاع الخطة/التنفيذ، بدءا من وضع الخطة
ذاكرة الملف	الملفات الثابتة ضمن agent-file-memory، مع مجلد عمل معزول لكل جلسة عمل
المهارات	الاكتشاف المدعوم بالملفات من دليل العمل، باستثناء شجرة الذاكرة الفرعية
البحث على الويب	إعلان بحث ويب مستضاف، ما لم يكن المتصل قد قام بالفعل بتوفير واحد
استحسان	برنامج وسيط للموافقة الدائمة والموافقة التلقائية للأدوات التي تتطلب الموافقة
التاريخ	محفوظات في الذاكرة مع استمرار لكل استدعاء خدمة
إدخال الرسائل	لكل عامل agent.MessageInjector
Tracing	الوكيل والأداة وأجهزة استدعاء النموذج المدعومة

يستخدم harness.Config لتعطيل المكونات أو تجاوز التكوين الخاص بها. قم بتعطيل بحث الويب المستضاف عندما لا تدعمه الخدمة أو النشر المحدد. تتطلب البرامج النصية للمهارة المدعومة بالملفات مشغل برنامج نصي تم تكوينه بشكل صريح.

يحتفظ المساعد بأدوات المتصل والبرامج الوسيطة وموفري السياق وموفر المحفوظات المكون بشكل صريح. مع نشر نموذج Foundry، استخدم DisableStoreOutput: true عندما تمتلك المحفوظات المحلية المحادثة.

لا تتم إضافة أدوات الضغط والتكرارات الحلقية وأدوات shell بواسطة مساعد Go. قم بتكوينها بشكل صريح عند الحاجة. موفر تفويض وكيل الخلفية المحزم الموضح في حزم SDK الأخرى غير متوفر في Go.

راجع إنشاء عامل تسخير Go للإعداد ودليل تكوين تسخير Go للإعدادات الافتراضية والتجاوزات.

نموذج UX الطرفي

لا يصف Harness واجهة تطبيق. يتضمن المستودع نماذج من التطبيقات الطرفية التي تقوم ببث الإخراج وعرض المهام ووضعها الحالي ومطالبات الموافقة على أداة surface وتوفير أوامر مثل /todosو /modeو /exit.

Important

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

نقطة إدخال عينة .NET هي HarnessConsole.RunAgentAsync:

using Harness.Shared.Console;

await HarnessConsole.RunAgentAsync(
    agent,
    userPrompt: "Ask me anything to get started.");

تخصيص العينة مع المراقبين ومنسقات الأدوات ومعالجات الأوامر و HarnessConsoleOptions. راجع عينات .NET Harness.

يستخدم نموذج Python الحزمة المستندة إلى console Textual بجانب عينات Harness:

from console import run_agent_async

await run_agent_async(agent)

تخصيص العينة مع المراقبين والمنسقين والأوامر ومكونات واجهة المستخدم. راجع عينات Python Harness.

يتضمن مستودع Go عينة تسخير مركب مع معالجة الموافقة وعرض توضيحي منفصل لواجهة سطر الأوامر للدردشة التفاعلية. يستخدم CLI الدردشة وكيلا عاديا؛ إنه ليس مكافئا لوحدة تحكم C# أو Python Harness.

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

تخطيط العمل وتتبع المهام

التعمق أكثر

• حلقات
• وكلاء الخلفية
• الضغط
• أدوات Shell