Bildirim Temelli Aracılar

Bildirim temelli aracılar, programlı kod yazmak yerine YAML veya JSON dosyalarını kullanarak aracı yapılandırmasını tanımlamanızı sağlar. Bu yaklaşım aracıların ekipler arasında tanımlanmasını, değiştirilmesini ve paylaşılacağını kolaylaştırır.

Prerequisites

C# dilinde bildirim temelli aracıları kullanmak için Microsoft.Agents.AI.Declarative NuGet paketini, sağlayıcınızın sohbet istemci paketine (örneğin, Azure.AI.OpenAI) ekleyin:

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

Microsoft.Agents.AI.Declarative paketi, aşağıdaki örneklerde kullanılan ChatClientPromptAgentFactory türünü ve PromptAgentFactory üzerinde CreateFromYamlAsync uzantısı yöntemini sağlar.

YAML ile satır içi aracı tanımlama

Tam YAML belirtimini doğrudan kodunuz içinde bir dize olarak tanımlayabilir ve ardından ile ChatClientPromptAgentFactorybu dizeden bir AIAgent oluşturabilirsiniz:

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);
}

Uyarı

DefaultAzureCredential geliştirme için uygundur ancak üretimde dikkatli bir şekilde dikkate alınması gerekir. Üretimde gecikme sorunları, istenmeyen kimlik bilgisi yoklama ve geri dönüş mekanizmalarından kaynaklanan olası güvenlik risklerini önlemek için belirli bir kimlik bilgisi (ör ManagedIdentityCredential. ) kullanmayı göz önünde bulundurun.

YAML dosyasından aracı yükleme

YAML tanımını ayrı bir dosyada depolayabilir ve çalışma zamanında yükleyebilirsiniz; bu da aracı yapılandırmasını kodunuzdan bağımsız olarak paylaşmayı, sürümü oluşturmayı ve düzenlemeyi kolaylaştırır:

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."));

Prerequisites

Python bildirim temelli aracıları kullanmak için agent-framework-declarative paketini sohbet istemcinizin sağlayıcı paketiyle birlikte yükleyin (örneğin, Microsoft Foundry için agent-framework-foundry veya Azure Yapay Zeka Atölyesi için agent-framework-azure-ai):

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

agent-framework-declarative paketi, aşağıdaki örneklerde AgentFactory kullanılan sınıfını create_agent_from_yaml ve ve create_agent_from_yaml_path yöntemlerini sağlar.

YAML ile satır içi aracı tanımlama

Tam YAML belirtimini doğrudan kodunuzda bir dize olarak tanımlayabilirsiniz:

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) as agent,
    ):
        response = await agent.run("What can you do for me?")
        print("Agent response:", response.text)


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

YAML dosyasından aracı yükleme

YAML tanımını bir dosyadan da yükleyebilirsiniz:

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())

Sonraki Adımlar

Gözlemlenebilirlik