Поделиться через

Изучение семантического ядра AzureAIAgent

Это важно

Эта функция находится на экспериментальном этапе. Функции на этом этапе находятся в стадии разработки и могут измениться перед переходом к этапу предварительного просмотра или релиз-кандидата.

Подсказка

Подробная документация по API, связанная с этим обсуждением, доступна по адресу:

Подсказка

Подробная документация по API, связанная с этим обсуждением, доступна по адресу:

Функция в настоящее время недоступна в Java.

Что такое AzureAIAgent?

Это AzureAIAgent — специализированный агент в рамках фреймворка семантического ядра, предназначенный для обеспечения продвинутых возможностей общения с бесшовной интеграцией инструментов. Он автоматизирует вызовы инструментов, устраняя необходимость ручного анализа и вызова. Агент также безопасно управляет историей общения с помощью потоков, снижая затраты на управление состоянием. Кроме того, AzureAIAgent поддерживает различные встроенные средства, включая извлечение файлов, выполнение кода и взаимодействие с данными с помощью Bing, поиска ИИ Azure, функций Azure и OpenAPI.

Чтобы использовать AzureAIAgent, необходимо задействовать проект Azure AI Foundry. В следующих статьях представлен обзор Azure AI Foundry, как создать и настроить проект и службу агента:

Подготовка среды разработки

Чтобы продолжить разработку AzureAIAgent, настройте среду разработки с соответствующими пакетами.

Добавьте пакет Microsoft.SemanticKernel.Agents.AzureAI в проект:

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

Также может потребоваться включить пакет Azure.Identity:

dotnet add package Azure.Identity

Установите пакет semantic-kernel.

pip install semantic-kernel

Функция в настоящее время недоступна в Java.

Настройка клиента проекта ИИ

AzureAIAgent Для доступа к первому требуется создать клиент, настроенный для конкретного проекта Foundry, чаще всего предоставляя конечную точку проекта (пакет SDK для Azure AI Foundry: начало работы с проектами).

PersistentAgentsClient client = AzureAIAgent.CreateAgentsClient("<your endpoint>", new AzureCliCredential());

Измените .env файл в корневом каталоге, чтобы включить:

AZURE_AI_AGENT_ENDPOINT = "<example-endpoint>"
AZURE_AI_AGENT_MODEL_DEPLOYMENT_NAME = "<example-model-deployment-name>"

После определения конфигурации клиент может быть создан:

from semantic_kernel.agents import AzureAIAgent

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

Если настроено, Pydantic Settings подхватят базовые endpoint настройки. В противном случае вы можете явно передать его методу create_client() :

from semantic_kernel.agents import AzureAIAgent

async with (
    DefaultAzureCredential() as creds,
    AzureAIAgent.create_client(credential=creds, endpoint="<your-endpoint>") as client,
):
    # Your operational code here

Функция в настоящее время недоступна в Java.

Создание объекта AzureAIAgent

Чтобы создать AzureAIAgent, начните с настройки и инициализации проекта Foundry через службу агента Azure, а затем интегрируйте его с Semantic Kernel.

PersistentAgentsClient client = AzureAIAgent.CreateAgentsClient("<your endpoint>", new AzureCliCredential());

// 1. Define an agent on the Azure AI agent service
PersistentAgent definition = await agentsClient.Administration.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 import AzureAIAgent, AzureAIAgentSettings

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=AzureAIAgentSettings().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,
    )

Функция в настоящее время недоступна в Java.

Взаимодействие с приложением AzureAIAgent

Взаимодействие с AzureAIAgent несложное. Агент автоматически ведет историю разговоров с помощью потока.

Особенности потока агента ИИ Azure абстрагируются с помощью класса Microsoft.SemanticKernel.Agents.AzureAI.AzureAIAgentThread, который является реализацией Microsoft.SemanticKernel.Agents.AgentThread.

Это важно

Обратите внимание, что пакет SDK для агентов ИИ Azure имеет PersistentAgentThread класс. Это не следует путать с Microsoft.SemanticKernel.Agents.AgentThread, то, что является общей абстракцией агентов семантического ядра, для всех типов потоков.

В настоящее время AzureAIAgent поддерживает только потоки типа AzureAIAgentThread.

AzureAIAgentThread agentThread = new(agent.Client);
try
{
    ChatMessageContent message = new(AuthorRole.User, "<your user input>");
    await foreach (ChatMessageContent response in agent.InvokeAsync(message, agentThread))
    {
        Console.WriteLine(response.Content);
    }
}
finally
{
    await agentThread.DeleteAsync();
    await agent.Client.DeleteAgentAsync(agent.Id);
}

Особенности потока агента ИИ Azure абстрагируются с помощью класса AzureAIAgentThread, который является реализацией AgentThread.

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

thread: AzureAIAgentThread = AzureAIAgentThread()

try:
    for user_input in USER_INPUTS:
        response = await agent.get_response(messages=user_inputs, thread=thread)
        print(response)
        thread = response.thread
finally:
    await thread.delete() if thread else None

При необходимости агент может вызываться как:

for user_input in USER_INPUTS:
    async for content in agent.invoke(messages=user_input, thread=thread):
        print(content.content)
        thread = response.thread

Вы также можете передать список сообщений в методы get_response(...), invoke(...) или invoke_stream(...).

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

thread: AzureAIAgentThread = AzureAIAgentThread()

try:
    for user_input in USER_INPUTS:
        response = await agent.get_response(messages=USER_INPUTS, thread=thread)
        print(response)
        thread = response.thread
finally:
    await thread.delete() if thread else None

Агент также может создать потокованный ответ:

ChatMessageContent message = new(AuthorRole.User, "<your user input>");
await foreach (StreamingChatMessageContent response in agent.InvokeStreamingAsync(message, agentThread))
{
    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)

Функция в настоящее время недоступна в Java.

Использование подключаемых модулей с помощью AzureAIAgent

Семантическое ядро поддерживает расширение AzureAIAgent пользовательскими плагинами для улучшения функциональности.

KernelPlugin plugin = KernelPluginFactory.CreateFromType<YourPlugin>();
PersistentAgentsClient client = AzureAIAgent.CreateAgentsClient("<your endpoint>", new AzureCliCredential());

PersistentAgent definition = await agentsClient.Administration.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"

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

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

Функция в настоящее время недоступна в Java.

Дополнительные функции

AzureAIAgent может использовать передовые инструменты, такие как:

Интерпретатор кода

Интерпретатор кода позволяет агентам записывать и запускать код Python в изолированной среде выполнения (интерпретатор службы агента ИИ Azure).

PersistentAgentsClient client = AzureAIAgent.CreateAgentsClient("<your endpoint>", new AzureCliCredential());

PersistentAgent definition = await 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.agents.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,
        )

Функция в настоящее время недоступна в Java.

Поиск по файлам расширяет агентов за счет знаний, находящихся за пределами их модели («средство поиска файлов службы агента ИИ Azure»).

PersistentAgentsClient client = AzureAIAgent.CreateAgentsClient("<your endpoint>", new AzureCliCredential());

PersistentAgent definition = await 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.agents.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,
        )

Функция в настоящее время недоступна в Java.

Интеграция OpenAPI

Подключает агент к внешнему API (как использовать службу агента ИИ Azure с указанными средствами OpenAPI).

PersistentAgentsClient client = AzureAIAgent.CreateAgentsClient("<your endpoint>", new AzureCliCredential());

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

PersistentAgent definition = await 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.agents.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,
    )

Функция в настоящее время недоступна в Java.

Интеграция поиска AzureAI

Используйте существующий индекс поиска ИИ Azure с агентом (используйте существующий индекс поиска ИИ).

PersistentAgentsClient client = AzureAIAgent.CreateAgentsClient("<your endpoint>", new AzureCliCredential());

PersistentAgent definition = await agentsClient.CreateAgentAsync(
    "<name of the the model used by the agent>",
    name: "<agent name>",
    description: "<agent description>",
    instructions: "<agent instructions>",
    tools: [new AzureAISearchToolDefinition()],
    toolResources: new()
    {
        AzureAISearch = new()
        {
            IndexList = { new AISearchIndexResource("<your connection id>", "<your index name>") }
        }
    });

AzureAIAgent agent = new(definition, agentsClient);

from azure.ai.agents.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"},
    )

Функция в настоящее время недоступна в Java.

Заземление Bing

Пример в ближайшее время.

from azure.ai.agents.models import BingGroundingTool
from azure.identity.aio import DefaultAzureCredential

from semantic_kernel.agents import AzureAIAgent, AzureAIAgentSettings

async with (
    DefaultAzureCredential() as creds,
    AzureAIAgent.create_client(credential=creds) as client,
):
    # 1. Enter your Bing Grounding Connection Name
    bing_connection = await client.connections.get(connection_name="<your-bing-grounding-connection-name>")
    conn_id = bing_connection.id

    # 2. Initialize agent bing tool and add the connection id
    bing_grounding = BingGroundingTool(connection_id=conn_id)

    # 3. Create an agent with Bing grounding on the Azure AI agent service
    agent_definition = await client.agents.create_agent(
        name="BingGroundingAgent",
        instructions="Use the Bing grounding tool to answer the user's question.",
        model=AzureAIAgentSettings().model_deployment_name,
        tools=bing_grounding.definitions,
    )

    # 4. Create a Semantic Kernel agent for the Azure AI agent
    agent = AzureAIAgent(
        client=client,
        definition=agent_definition,
    )

При использовании средства Bing Grounding переданная в FunctionCallContent обратный вызов функция будет иметь имя, установленное в on_intermediate_message. После завершения выполнения список будет включать ChatMessageContent.items, либо AnnotationContent или StreamingAnnotationContent, в зависимости от того, является ли вызов стандартным или стримингом. Эти элементы заметок содержат сведения о ссылках, которые агент посетил во время ответа, как и сведения, присутствующие в нем FunctionCallContent.

Дополнительные сведения см. в следующих примерах концепции:

Функция в настоящее время недоступна в Java.

Получение существующего AzureAIAgent

Существующего агента можно получить и использовать повторно, указав идентификатор его помощника.

PersistentAgent definition = await agentsClient.Administration.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)

Функция в настоящее время недоступна в Java.

Удаление AzureAIAgent

Агенты и связанные с ними потоки можно удалить, если больше не требуется:

await agentThread.DeleteAsync();
await agentsClient.Administration.DeleteAgentAsync(agent.Id);

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

При работе с векторным хранилищем или файлами их также можно удалить:

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

await client.agents.files.delete(file_id=file.id)
await client.agents.vector_stores.delete(vector_store_id=vector_store.id)

Функция в настоящее время недоступна в Java.

Дополнительные сведения о средстве поиска файлов описаны в статье службы поиска файлов агента ИИ Azure .

Инструкции

Практические примеры использования AzureAIAgentкода см. в примерах кода на GitHub:

Функция в настоящее время недоступна в Java.

Обработка промежуточных сообщений с помощью AzureAIAgent

Семантические ядра AzureAIAgent предназначены для вызова агента, выполняющего запросы пользователей или вопросы. Во время вызова агент может использовать инструменты для получения окончательного ответа. Чтобы получить доступ к промежуточным сообщениям, созданным во время этого процесса, вызывающие могут предоставить функцию обратного вызова, которая обрабатывает экземпляры FunctionCallContent или FunctionResultContent.

Документация по обратному вызову для AzureAIAgent будет доступна в ближайшее время.

Настройка обратного вызова on_intermediate_message в agent.invoke(...) или agent.invoke_stream(...) позволяет вызывающему объекту получать промежуточные сообщения, создаваемые в процессе формирования окончательного ответа агента.

import asyncio
from typing import Annotated

from azure.identity.aio import DefaultAzureCredential

from semantic_kernel.agents import AzureAIAgent, AzureAIAgentSettings, AzureAIAgentThread
from semantic_kernel.contents import FunctionCallContent, FunctionResultContent
from semantic_kernel.contents.chat_message_content import ChatMessageContent
from semantic_kernel.functions import kernel_function


# Define a sample plugin for the sample
class MenuPlugin:
    """A sample Menu Plugin used for the concept sample."""

    @kernel_function(description="Provides a list of specials from the menu.")
    def get_specials(self) -> Annotated[str, "Returns the specials from the menu."]:
        return """
        Special Soup: Clam Chowder
        Special Salad: Cobb Salad
        Special Drink: Chai Tea
        """

    @kernel_function(description="Provides the price of the requested menu item.")
    def get_item_price(
        self, menu_item: Annotated[str, "The name of the menu item."]
    ) -> Annotated[str, "Returns the price of the menu item."]:
        return "$9.99"


# This callback function will be called for each intermediate message,
# which will allow one to handle FunctionCallContent and FunctionResultContent.
# If the callback is not provided, the agent will return the final response
# with no intermediate tool call steps.
async def handle_intermediate_steps(message: ChatMessageContent) -> None:
    for item in message.items or []:
        if isinstance(item, FunctionResultContent):
            print(f"Function Result:> {item.result} for function: {item.name}")
        elif isinstance(item, FunctionCallContent):
            print(f"Function Call:> {item.name} with arguments: {item.arguments}")
        else:
            print(f"{item}")


async def main() -> None:
    ai_agent_settings = AzureAIAgentSettings()

    async with (
        DefaultAzureCredential() as creds,
        AzureAIAgent.create_client(credential=creds, endpoint=ai_agent_settings.endpoint) as client,
    ):
        AGENT_NAME = "Host"
        AGENT_INSTRUCTIONS = "Answer questions about the menu."

        # Create agent definition
        agent_definition = await client.agents.create_agent(
            model=ai_agent_settings.deployment_name,
            name=AGENT_NAME,
            instructions=AGENT_INSTRUCTIONS,
        )

        # Create the AzureAI Agent
        agent = AzureAIAgent(
            client=client,
            definition=agent_definition,
            plugins=[MenuPlugin()],  # add the sample plugin to the agent
        )

        # Create a thread for the agent
        # If no thread is provided, a new thread will be
        # created and returned with the initial response
        thread: AzureAIAgentThread = None

        user_inputs = [
            "Hello",
            "What is the special soup?",
            "How much does that cost?",
            "Thank you",
        ]

        try:
            for user_input in user_inputs:
                print(f"# User: '{user_input}'")
                async for response in agent.invoke(
                    messages=user_input,
                    thread=thread,
                    on_intermediate_message=handle_intermediate_steps,
                ):
                    print(f"# Agent: {response}")
                    thread = response.thread
        finally:
            # Cleanup: Delete the thread and agent
            await thread.delete() if thread else None
            await client.agents.delete_agent(agent.id)


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

Ниже приведен пример выходных данных из процесса вызова агента:

User: 'Hello'
Agent: Hi there! How can I assist you today?
User: 'What is the special soup?'
Function Call:> MenuPlugin-get_specials with arguments: {}
Function Result:> 
        Special Soup: Clam Chowder
        Special Salad: Cobb Salad
        Special Drink: Chai Tea
        for function: MenuPlugin-get_specials
Agent: The special soup is Clam Chowder. Would you like to know anything else about the menu?
User: 'How much does that cost?'
Function Call:> MenuPlugin-get_item_price with arguments: {"menu_item":"Clam Chowder"}
Function Result:> $9.99 for function: MenuPlugin-get_item_price
Agent: The Clam Chowder costs $9.99. Let me know if you would like assistance with anything else!
User: 'Thank you'
Agent: You're welcome! Enjoy your meal! 😊

Функция в настоящее время недоступна в Java.

Декларативная спецификация

В ближайшее время будет представлена документация по использованию декларативных спецификаций.

Это важно

Эта функция находится на экспериментальном этапе. Функции на этом этапе находятся в стадии разработки и могут измениться перед переходом к этапу предварительного просмотра или релиз-кандидата.

Элемент AzureAIAgent поддерживает создание экземпляров из декларативной спецификации YAML. Декларативный подход позволяет определить свойства агента, инструкции, конфигурацию модели, средства и другие параметры в одном, проверяемом документе. Это делает состав агента переносимым и легко управляемым в разных средах.

Замечание

Все средства, функции или подключаемые модули, перечисленные в декларативном YAML, должны быть доступны агенту во время строительства. Для плагинов на основе ядра это означает, что они должны быть зарегистрированы в ядре. Для встроенных инструментов, таких как Bing Grounding, Поиск файлов или OpenAPI, необходимо указать правильную конфигурацию и учетные данные. Загрузчик агента не создаст функции с нуля. Если обязательный компонент отсутствует, создание агента не удастся.

Как использовать декларативную спецификацию

Вместо перечисления каждой возможной конфигурации YAML в этом разделе описываются основные принципы и приводятся ссылки на примеры концепций, показывающие полный код для каждого типа инструмента. Ознакомьтесь с этими примерами концепции для комплексных реализаций AzureAIAgent декларативных спецификаций:

Пример. Создание AzureAIAgent из YAML

Минимальное декларативное представление YAML может выглядеть следующим образом:

type: foundry_agent
name: MyAgent
instructions: Respond politely to the user's questions.
model:
  id: ${AzureAI:ChatModelId}
tools:
  - id: MenuPlugin.get_specials
    type: function
  - id: MenuPlugin.get_item_price
    type: function

Дополнительные сведения о подключении агента можно найти в приведённых выше полных образцах кода.

Основные моменты

  • Декларативные спецификации позволяют определять структуру агента, средства и поведение в YAML.
  • Все указанные средства и подключаемые модули должны быть зарегистрированы или доступны во время выполнения.
  • Встроенные средства, такие как Bing, поиск файлов и интерпретатор кода, требуют надлежащей настройки и учетных данных (часто через переменные среды или явные аргументы).
  • Полные примеры см. в приведенных примерах ссылок, демонстрирующих практические сценарии, включая регистрацию подключаемых модулей, конфигурацию удостоверений Azure и расширенное использование средств.

Эта функция недоступна.

Дальнейшие шаги

Исследуйте агента Bedrock

  • Last updated on