العوامل التعريفية

تسمح لك العوامل التعريفية بتعريف تكوين العامل باستخدام ملفات YAML أو JSON بدلا من كتابة التعليمات البرمجية. يجعل هذا النهج العوامل أسهل في تحديد وتعديل ومشاركتها عبر الفرق.

المتطلبات الأساسية

لاستخدام عوامل تعريفية في C#، أضف حزمة Microsoft.Agents.AI.Declarative NuGet إلى مشروعك، إلى جانب حزمة عميل الدردشة لموفر الخدمة (على سبيل المثال، Azure.AI.OpenAI):

dotnet add package Microsoft.Agents.AI.Declarative --prerelease
dotnet add package Azure.AI.OpenAI
dotnet add package Azure.Identity

Microsoft.Agents.AI.Declarative توفر الحزمة ChatClientPromptAgentFactory النوع وطريقة الامتداد CreateFromYamlAsync المستخدمة PromptAgentFactory في الأمثلة أدناه.

تعريف عامل مضمن مع YAML

يمكنك تعريف مواصفات YAML الكاملة كسلسلة مباشرة في التعليمات البرمجية AIAgent الخاصة بك، ثم إنشاء منها باستخدام ChatClientPromptAgentFactory:

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";

// Create the chat client
IChatClient chatClient = new AzureOpenAIClient(
    new Uri(endpoint),
    new DefaultAzureCredential())
        .GetChatClient(deploymentName)
        .AsIChatClient();

// Define the agent using a YAML definition.
var yamlDefinition =
    """
    kind: Prompt
    name: Assistant
    description: Helpful assistant
    instructions: You are a helpful assistant. You answer questions in the language specified by the user. You return your answers in a JSON format.
    model:
        options:
            temperature: 0.9
            topP: 0.95
    outputSchema:
        properties:
            language:
                type: string
                required: true
                description: The language of the answer.
            answer:
                type: string
                required: true
                description: The answer text.
    """;

// Create the agent from the YAML definition.
var agentFactory = new ChatClientPromptAgentFactory(chatClient);
var agent = await agentFactory.CreateFromYamlAsync(yamlDefinition);

// Invoke the agent and output the text result.
Console.WriteLine(await agent!.RunAsync("Tell me a joke about a pirate in English."));

// Invoke the agent with streaming support.
await foreach (var update in agent!.RunStreamingAsync("Tell me a joke about a pirate in French."))
{
    Console.WriteLine(update);
}

تحذير

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

تحميل عامل من ملف YAML

يمكنك أيضا تخزين تعريف YAML في ملف منفصل وتحميله في وقت التشغيل، ما يسهل مشاركة تكوين العامل وإصداره وتحريره بشكل مستقل عن التعليمات البرمجية الخاصة بك:

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-4o-mini";

// Create the chat client.
IChatClient chatClient = new AzureOpenAIClient(
    new Uri(endpoint),
    new DefaultAzureCredential())
        .GetChatClient(deploymentName)
        .AsIChatClient();

// Read the YAML agent definition from a file.
var yamlFilePath = "agent.yaml";
var yamlDefinition = await File.ReadAllTextAsync(yamlFilePath);

// Create the agent from the YAML definition.
var agentFactory = new ChatClientPromptAgentFactory(chatClient);
var agent = await agentFactory.CreateFromYamlAsync(yamlDefinition);

// Invoke the agent and output the text result.
Console.WriteLine(await agent!.RunAsync("Tell me a joke about a pirate in English."));

المتطلبات الأساسية

لاستخدام عوامل تعريفية في Python، قم بتثبيت agent-framework-declarative الحزمة جنبا إلى جنب مع حزمة الموفر لعميل الدردشة (على سبيل المثال، agent-framework-foundry Microsoft Foundry أو agent-framework-azure-ai منصة Azure للذكاء الاصطناعي):

pip install agent-framework-declarative agent-framework-foundry --pre

agent-framework-declarative توفر الحزمة AgentFactory الفئة والأساليب create_agent_from_yamlcreate_agent_from_yaml_path المستخدمة في الأمثلة أدناه.

تعريف عامل مضمن مع YAML

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

import asyncio

from agent_framework.declarative import AgentFactory
from azure.identity.aio import AzureCliCredential


async def main():
    """Create an agent from an inline YAML definition and run it."""
    yaml_definition = """kind: Prompt
name: DiagnosticAgent
displayName: Diagnostic Assistant
instructions: Specialized diagnostic and issue detection agent for systems with critical error protocol and automatic handoff capabilities
description: An agent that performs diagnostics on systems and can escalate issues when critical errors are detected.

model:
  id: =Env.AZURE_OPENAI_MODEL
  connection:
    kind: remote
    endpoint: =Env.FOUNDRY_PROJECT_ENDPOINT
"""
    async with (
        AzureCliCredential() as credential,
        AgentFactory(client_kwargs={"credential": credential}).create_agent_from_yaml(
            yaml_definition,
            safe_mode=False,
        ) as agent,
    ):
        response = await agent.run("What can you do for me?")
        print("Agent response:", response.text)


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

تحميل عامل من ملف YAML

يمكنك أيضا تحميل تعريف YAML من ملف:

import asyncio
from pathlib import Path

from agent_framework.declarative import AgentFactory
from azure.identity.aio import AzureCliCredential


async def main():
    """Create an agent from a declarative YAML file and run it."""
    yaml_path = Path(__file__).parent / "agent-config.yaml"

    async with (
        AzureCliCredential() as credential,
        AgentFactory(client_kwargs={"credential": credential}).create_agent_from_yaml_path(yaml_path) as agent,
    ):
        response = await agent.run("Why is the sky blue?")
        print("Agent response:", response.text)


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

Note

سيتوفر الدعم لهذه الميزة قريبا. راجع مستودع Agent Framework Go للحصول على أحدث حالة.

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

إمكانية المراقبة