Bagikan melalui

Menjelajahi Kernel Semantik AzureAIAgent

  • Artikel

Penting

Fitur ini dalam tahap eksperimental. Fitur pada tahap ini masih dalam pengembangan dan dapat berubah sebelum maju ke tahap pratinjau atau kandidat rilis.

Dokumentasi API terperinci yang terkait dengan diskusi ini tersedia di:

Dokumen API Python Kernel Semantik yang diperbarui akan segera hadir.

Agen saat ini tidak tersedia di Java.

Apa itu AzureAIAgent?

AzureAIAgent adalah agen khusus dalam kerangka kerja Kernel Semantik, yang dirancang untuk menyediakan kemampuan percakapan tingkat lanjut dengan integrasi alat yang mulus. Ini mengotomatiskan pemanggilan alat, sehingga tidak memerlukan penguraian dan pemanggilan secara manual. Agen juga mengelola riwayat percakapan dengan cara yang aman menggunakan utas, mengurangi beban tambahan dalam menjaga keberlangsungan percakapan. Selain itu, AzureAIAgent mendukung berbagai alat bawaan, termasuk pengambilan file, eksekusi kode, dan interaksi data melalui Bing, Azure AI Search, Azure Functions, dan OpenAPI.

Untuk menggunakan AzureAIAgent, perlu memanfaatkan Proyek Azure AI Foundry. Artikel berikut ini memberikan gambaran umum tentang Azure AI Foundry, cara membuat dan mengonfigurasi proyek, dan layanan agen:

Menyiapkan lingkungan pengembangan Anda

Untuk melanjutkan pengembangan AzureAIAgent, konfigurasikan lingkungan pengembangan Anda dengan paket yang sesuai.

Tambahkan paket Microsoft.SemanticKernel.Agents.AzureAI ke proyek Anda:

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

Anda mungkin juga ingin menyertakan paket Azure.Identity:

dotnet add package Azure.Identity

Instal paket semantic-kernel dengan dependensi Azure opsional:

pip install semantic-kernel[azure]

Agen saat ini tidak tersedia di Java.

Mengonfigurasi Antarmuka Pengguna Proyek AI

Mengakses AzureAIAgent terlebih dahulu memerlukan pembuatan klien proyek yang dikonfigurasi untuk Proyek Foundry tertentu, paling umum dengan menyediakan string koneksi (Azure AI Foundry SDK: Memulai Proyek).

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

AgentsClient dapat diakses dari AIProjectClient:

AgentsClient agentsClient = client.GetAgentsClient();

Ubah file .env di direktori akar agar menyertakan:

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

atau

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>"

Setelah konfigurasi ditentukan, klien dapat dibuat:

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

Agen saat ini tidak tersedia di Java.

Membuat AzureAIAgent

Untuk membuat AzureAIAgent, Anda mulai dengan mengonfigurasi dan menginisialisasi proyek agen melalui layanan Azure AI lalu mengintegrasikannya dengan Semantic 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,
    )

Agen saat ini tidak tersedia di Java.

Berinteraksi dengan AzureAIAgent

Interaksi dengan AzureAIAgent itu mudah. Agen mempertahankan riwayat percakapan secara otomatis menggunakan utas:

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)

Secara opsional, agen dapat dipanggil sebagai:

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)

Agen juga dapat menghasilkan respons streaming.

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)

Agen saat ini tidak tersedia di Java.

Menggunakan Plugin dengan AzureAIAgent

Semantic Kernel mendukung perluasan AzureAIAgent dengan plugin kustom untuk fungsionalitas yang ditingkatkan:

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

Agen saat ini tidak tersedia di Java.

Fitur Tingkat Lanjut

AzureAIAgent dapat memanfaatkan alat canggih seperti:

Penerjemah Kode

Penerjemah Kode memungkinkan agen untuk menulis dan menjalankan kode Python di lingkungan eksekusi yang terisolasi dengan aman (Penerjemah Kode Layanan Agen Azure AI).

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

Agen saat ini tidak tersedia di Java.

Pencarian file meningkatkan agen dengan pengetahuan dari luar modelnya (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,
        )

Agen saat ini tidak tersedia di Java.

Integrasi OpenAPI

Menyambungkan agen Anda ke API eksternal (Cara menggunakan Azure AI Agent Service dengan 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,
        )

Agen saat ini tidak tersedia di Java.

Integrasi Pencarian AzureAI

Gunakan indeks Pencarian Azure AI yang sudah ada dengan agen Anda (Gunakan indeks Pencarian AI yang sudah ada).

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"},
        )

Agen saat ini tidak tersedia di Java.

Mengambil AzureAIAgent yang Sudah Ada

Agen yang ada dapat diambil dan digunakan kembali dengan menentukan ID asistennya:

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)

Agen saat ini tidak tersedia di Java.

Menghapus AzureAIAgent

Agen dan utas terkaitnya dapat dihapus ketika tidak lagi diperlukan:

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

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

Jika bekerja dengan penyimpanan vektor atau file, mereka juga dapat dihapus:

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)

Agen saat ini tidak tersedia di Java.

Informasi selengkapnya tentang alat pencarian file dijelaskan dalam artikel alat pencarian file Azure AI Agent Service.

How-To

Untuk contoh praktis menggunakan AzureAIAgent, lihat sampel kode kami di GitHub:

Agen saat ini tidak tersedia di Java.

Kolaborasi Agen di Obrolan Agen