Delen via

De Semantische kernel-AzureAIAgent verkennen

  • Artikel

Belangrijk

Deze functie bevindt zich in de experimentele fase. Functies in deze fase zijn nog in ontwikkeling en kunnen worden gewijzigd voordat u naar de preview- of releasekandidaatfase gaat.

Gedetailleerde API-documentatie met betrekking tot deze discussie is beschikbaar op:

Bijgewerkte Semantic Kernel Python API Docs zijn binnenkort beschikbaar.

Agents zijn momenteel niet beschikbaar in Java.

Wat is een AzureAIAgent?

Een AzureAIAgent is een gespecialiseerde agent binnen het Semantische Kernel-framework, ontworpen om geavanceerde gespreksmogelijkheden te bieden met naadloze integratie van hulpprogramma's. Het automatiseert het aanroepen van hulpprogramma's, waardoor handmatig parseren en aanroepen niet meer nodig is. De agent beheert ook de gespreksgeschiedenis veilig met behulp van threads, waardoor de overhead van het onderhouden van de status wordt verminderd. Daarnaast biedt de AzureAIAgent ondersteuning voor diverse ingebouwde hulpprogramma's, waaronder het ophalen van bestanden, het uitvoeren van code en gegevensinteractie via Bing, Azure AI Search, Azure Functions en OpenAPI.

Als u een AzureAIAgentwilt gebruiken, moet een Azure AI Foundry-project worden gebruikt. De volgende artikelen bevatten een overzicht van Azure AI Foundry, het maken en configureren van een project en de agentservice:

Uw ontwikkelomgeving voorbereiden

Als u wilt doorgaan met het ontwikkelen van een AzureAIAgent, configureert u uw ontwikkelomgeving met de juiste pakketten.

Voeg het Microsoft.SemanticKernel.Agents.AzureAI-pakket toe aan uw project:

dotnet add package Microsoft.SemanticKernel.Agents.AzureAI --prerelease

U kunt ook het Azure.Identity-pakket opnemen:

dotnet add package Azure.Identity

Installeer het semantic-kernel-pakket met de optionele Azure-afhankelijkheden:

pip install semantic-kernel[azure]

Agents zijn momenteel niet beschikbaar in Java.

De AI-projectclient configureren

Toegang tot een AzureAIAgent vereist eerst dat er een projectclient wordt gemaakt die is geconfigureerd voor een specifiek Foundry-project, meestal door het verstrekken van een verbindingsreeks (De Azure AI Foundry SDK: Aan de slag met projecten).

AIProjectClient client = AzureAIAgent.CreateAzureAIClient("<your connection-string>", new AzureCliCredential());

De AgentsClient is toegankelijk vanuit de AIProjectClient:

AgentsClient agentsClient = client.GetAgentsClient();

Wijzig uw .env-bestand in de root directory om het volgende op te nemen:

AZURE_AI_AGENT_PROJECT_CONNECTION_STRING = "<example-connection-string>"
AZURE_AI_AGENT_MODEL_DEPLOYMENT_NAME = "<example-model-deployment-name>"

of

AZURE_AI_AGENT_ENDPOINT = "<example-endpoint>"
AZURE_AI_AGENT_SUBSCRIPTION_ID = "<example-subscription-id>"
AZURE_AI_AGENT_RESOURCE_GROUP_NAME = "<example-resource-group-name>"
AZURE_AI_AGENT_PROJECT_NAME = "<example-project-name>"
AZURE_AI_AGENT_MODEL_DEPLOYMENT_NAME = "<example-model-deployment-name>"

Zodra de configuratie is gedefinieerd, kan de client worden gemaakt:

async with (
    DefaultAzureCredential() as creds,
    AzureAIAgent.create_client(credential=creds) as client,
):
    # Your operational code here

Agents zijn momenteel niet beschikbaar in Java.

Een AzureAIAgent maken

Als u een AzureAIAgentwilt maken, begint u met het configureren en initialiseren van het agentproject via de Azure AI-service en integreert u het vervolgens met Semantische kernel:

AIProjectClient client = AzureAIAgent.CreateAzureAIClient("<your connection-string>", new AzureCliCredential());
AgentsClient agentsClient = client.GetAgentsClient();

// 1. Define an agent on the Azure AI agent service
Agent definition = agentsClient.CreateAgentAsync(
    "<name of the the model used by the agent>",
    name: "<agent name>",
    description: "<agent description>",
    instructions: "<agent instructions>");

// 2. Create a Semantic Kernel agent based on the agent definition
AzureAIAgent agent = new(definition, agentsClient);

from azure.identity.aio import DefaultAzureCredential
from semantic_kernel.agents.azure_ai import AzureAIAgent, AzureAIAgentSettings

ai_agent_settings = AzureAIAgentSettings.create()

async with (
    DefaultAzureCredential() as creds,
    AzureAIAgent.create_client(credential=creds) as client,
):
    # 1. Define an agent on the Azure AI agent service
    agent_definition = await client.agents.create_agent(
        model=ai_agent_settings.model_deployment_name,
        name="<name>",
        instructions="<instructions>",
    )

    # 2. Create a Semantic Kernel agent based on the agent definition
    agent = AzureAIAgent(
        client=client,
        definition=agent_definition,
    )

Agents zijn momenteel niet beschikbaar in Java.

Interactie met een AzureAIAgent

Interactie met de AzureAIAgent is eenvoudig. De agent onderhoudt automatisch de gespreksgeschiedenis met behulp van een thread:

AgentThread thread = await agentsClient.CreateThreadAsync();
try
{
    ChatMessageContent message = new(AuthorRole.User, "<your user input>");
    await agent.AddChatMessageAsync(threadId, message);
    await foreach (ChatMessageContent response in agent.InvokeAsync(thread.Id))
    {
        Console.WriteLine(response.Content);
    }
}
finally
{
    await this.AgentsClient.DeleteThreadAsync(thread.Id);
    await this.AgentsClient.DeleteAgentAsync(agent.Id);
}

USER_INPUTS = ["Hello", "What's your name?"]

thread = await client.agents.create_thread()

try:
    for user_input in USER_INPUTS:
        await agent.add_chat_message(thread_id=thread.id, message=user_input)
        response = await agent.get_response(thread_id=thread.id)
        print(response)
finally:
    await client.agents.delete_thread(thread.id)

Optioneel kan een agent worden aangeroepen als:

for user_input in USER_INPUTS:
    await agent.add_chat_message(thread_id=thread.id, message=user_input)
    async for content in agent.invoke(thread_id=thread.id):
        print(content.content)

Een agent kan ook een gestreamd antwoord produceren:

ChatMessageContent message = new(AuthorRole.User, "<your user input>");
await agent.AddChatMessageAsync(threadId, message);
await foreach (StreamingChatMessageContent response in agent.InvokeStreamingAsync(thread.Id))
{
    Console.Write(response.Content);
}

for user_input in USER_INPUTS:
    await agent.add_chat_message(thread_id=thread.id, message=user_input)
    async for content in agent.invoke_stream(thread_id=thread.id):
        print(content.content, end="", flush=True)

Agents zijn momenteel niet beschikbaar in Java.

Invoegtoepassingen gebruiken met een AzureAIAgent

Semantische Kernel ondersteunt het uitbreiden van een AzureAIAgent met aangepaste plug-ins voor verbeterde functionaliteit.

Plugin plugin = KernelPluginFactory.CreateFromType<YourPlugin>();
AIProjectClient client = AzureAIAgent.CreateAzureAIClient("<your connection-string>", new AzureCliCredential());
AgentsClient agentsClient = client.GetAgentsClient();

Agent definition = agentsClient.CreateAgentAsync(
    "<name of the the model used by the agent>",
    name: "<agent name>",
    description: "<agent description>",
    instructions: "<agent instructions>");

AzureAIAgent agent = new(definition, agentsClient, plugins: [plugin]);

from semantic_kernel.functions import kernel_function

class SamplePlugin:
    @kernel_function(description="Provides sample data.")
    def get_data(self) -> str:
        return "Sample data"

ai_agent_settings = AzureAIAgentSettings.create()

async with (
        DefaultAzureCredential() as creds,
        AzureAIAgent.create_client(credential=creds) as client,
    ):
        agent_definition = await client.agents.create_agent(
            model=ai_agent_settings.model_deployment_name,
        )

        agent = AzureAIAgent(
            client=client,
            definition=agent_definition,
            plugins=[SamplePlugin()]
        )

Agents zijn momenteel niet beschikbaar in Java.

Geavanceerde functies

Een AzureAIAgent kan gebruikmaken van geavanceerde hulpprogramma's zoals:

Code-interpreter

Met code-interpreter kunnen de agents Python-code schrijven en uitvoeren in een omgeving met sandboxuitvoering (Azure AI Agent Service Code Interpreter).

AIProjectClient client = AzureAIAgent.CreateAzureAIClient("<your connection-string>", new AzureCliCredential());
AgentsClient agentsClient = client.GetAgentsClient();

Agent definition = agentsClient.CreateAgentAsync(
    "<name of the the model used by the agent>",
    name: "<agent name>",
    description: "<agent description>",
    instructions: "<agent instructions>",
    tools: [new CodeInterpreterToolDefinition()],
    toolResources:
        new()
        {
            CodeInterpreter = new()
            {
                FileIds = { ... },
            }
        }));

AzureAIAgent agent = new(definition, agentsClient);

from azure.ai.projects.models import CodeInterpreterTool

async with (
        DefaultAzureCredential() as creds,
        AzureAIAgent.create_client(credential=creds) as client,
    ):
        code_interpreter = CodeInterpreterTool()
        agent_definition = await client.agents.create_agent(
            model=ai_agent_settings.model_deployment_name,
            tools=code_interpreter.definitions,
            tool_resources=code_interpreter.resources,
        )

Agents zijn momenteel niet beschikbaar in Java.

Bestandszoek verrijkt agents door kennis van buiten het model (Azure AI Agent Service File Search Tool).

AIProjectClient client = AzureAIAgent.CreateAzureAIClient("<your connection-string>", new AzureCliCredential());
AgentsClient agentsClient = client.GetAgentsClient();

Agent definition = agentsClient.CreateAgentAsync(
    "<name of the the model used by the agent>",
    name: "<agent name>",
    description: "<agent description>",
    instructions: "<agent instructions>",
    tools: [new FileSearchToolDefinition()],
    toolResources:
        new()
        {
            FileSearch = new()
            {
                VectorStoreIds = { ... },
            }
        }));

AzureAIAgent agent = new(definition, agentsClient);

from azure.ai.projects.models import FileSearchTool

async with (
        DefaultAzureCredential() as creds,
        AzureAIAgent.create_client(credential=creds) as client,
    ):
        file_search = FileSearchTool(vector_store_ids=[vector_store.id])
        agent_definition = await client.agents.create_agent(
            model=ai_agent_settings.model_deployment_name,
            tools=file_search.definitions,
            tool_resources=file_search.resources,
        )

Agents zijn momenteel niet beschikbaar in Java.

OpenAPI-integratie

Verbindt uw agent met een externe API (Azure AI Agent Service gebruiken met OpenAPI Specified Tools).

AIProjectClient client = AzureAIAgent.CreateAzureAIClient("<your connection-string>", new AzureCliCredential());
AgentsClient agentsClient = client.GetAgentsClient();

string apiJsonSpecification = ...; // An Open API JSON specification

Agent definition = agentsClient.CreateAgentAsync(
    "<name of the the model used by the agent>",
    name: "<agent name>",
    description: "<agent description>",
    instructions: "<agent instructions>",
    tools: [
        new OpenApiToolDefinition(
            "<api name>", 
            "<api description>", 
            BinaryData.FromString(apiJsonSpecification), 
            new OpenApiAnonymousAuthDetails())
    ],
);

AzureAIAgent agent = new(definition, agentsClient);

from azure.ai.projects.models import OpenApiTool, OpenApiAnonymousAuthDetails

async with (
        DefaultAzureCredential() as creds,
        AzureAIAgent.create_client(credential=creds) as client,
    ):
        openapi_spec_file_path = "sample/filepath/..."
        with open(os.path.join(openapi_spec_file_path, "spec_one.json")) as file_one:
            openapi_spec_one = json.loads(file_one.read())
        with open(os.path.join(openapi_spec_file_path, "spec_two.json")) as file_two:
            openapi_spec_two = json.loads(file_two.read())

        # Note that connection or managed identity auth setup requires additional setup in Azure
        auth = OpenApiAnonymousAuthDetails()
        openapi_tool_one = OpenApiTool(
            name="<name>",
            spec=openapi_spec_one,
            description="<description>",
            auth=auth,
        )
        openapi_tool_two = OpenApiTool(
            name="<name>",
            spec=openapi_spec_two,
            description="<description>",
            auth=auth,
        )

        agent_definition = await client.agents.create_agent(
            model=ai_agent_settings.model_deployment_name,
            tools=openapi_tool_one.definitions + openapi_tool_two.definitions,
        )

Agents zijn momenteel niet beschikbaar in Java.

Integratie van AzureAI Search

Gebruik een bestaande Azure AI Search-index met uw agent (Een bestaande AI Search-index gebruiken).

AIProjectClient client = AzureAIAgent.CreateAzureAIClient("<your connection-string>", new AzureCliCredential());
AgentsClient agentsClient = client.GetAgentsClient();

ConnectionsClient cxnClient = client.GetConnectionsClient();
ListConnectionsResponse searchConnections = await cxnClient.GetConnectionsAsync(AzureAIP.ConnectionType.AzureAISearch);
ConnectionResponse searchConnection = searchConnections.Value[0];

Agent definition = agentsClient.CreateAgentAsync(
    "<name of the the model used by the agent>",
    name: "<agent name>",
    description: "<agent description>",
    instructions: "<agent instructions>",
    tools: [new AzureAIP.AzureAISearchToolDefinition()],
    toolResources: new()
    {
        AzureAISearch = new()
        {
            IndexList = { new AzureAIP.IndexResource(searchConnection.Id, "<your index name>") }
        }
    });

AzureAIAgent agent = new(definition, agentsClient);

from azure.ai.projects.models import AzureAISearchTool, ConnectionType

async with (
        DefaultAzureCredential() as creds,
        AzureAIAgent.create_client(credential=creds) as client,
    ):
        conn_list = await client.connections.list()

        ai_search_conn_id = ""
        for conn in conn_list:
            if conn.connection_type == ConnectionType.AZURE_AI_SEARCH:
                ai_search_conn_id = conn.id
                break

        ai_search = AzureAISearchTool(
            index_connection_id=ai_search_conn_id, 
            index_name=AZURE_AI_SEARCH_INDEX_NAME,
        )

        agent_definition = await client.agents.create_agent(
            model=ai_agent_settings.model_deployment_name,
            instructions="Answer questions using your index.",
            tools=ai_search.definitions,
            tool_resources=ai_search.resources,
            headers={"x-ms-enable-preview": "true"},
        )

Agents zijn momenteel niet beschikbaar in Java.

Een bestaande AzureAIAgent ophalen

Een bestaande agent kan worden opgehaald en opnieuw worden gebruikt door de bijbehorende assistent-id op te geven:

Agent definition = agentsClient.GetAgentAsync("<your agent id>");
AzureAIAgent agent = new(definition, agentsClient);

agent_definition = await client.agents.get_agent(assistant_id="your-agent-id")
agent = AzureAIAgent(client=client, definition=agent_definition)

Agents zijn momenteel niet beschikbaar in Java.

Een AzureAIAgent verwijderen

Agents en de bijbehorende threads kunnen worden verwijderd wanneer ze niet meer nodig zijn:

await agentsClient.DeleteThreadAsync(thread.Id);
await agentsClient.DeleteAgentAsync(agent.Id);

await client.agents.delete_thread(thread.id)
await client.agents.delete_agent(agent.id)

Als u werkt met een vectorarchief of bestanden, kunnen ze ook worden verwijderd:

await agentsClient.DeleteVectorStoreAsync("<your store id>");
await agentsClient.DeleteFileAsync("<your file id>");

await client.agents.delete_file(file_id=file.id)
await client.agents.delete_vector_store(vector_store_id=vector_store.id)

Agents zijn momenteel niet beschikbaar in Java.

Meer informatie over het -hulpprogramma voor bestandszoekopdrachten wordt beschreven in het artikel over het Azure AI Agent Service-hulpprogramma voor bestandszoekopdrachten.

How-To

Zie onze codevoorbeelden op GitHub voor praktische voorbeelden van het gebruik van een AzureAIAgent:

Agents zijn momenteel niet beschikbaar in Java.

Agentensamenwerking in Agentchat