빠른 시작 - 새 Azure AI 에이전트 서비스 프로젝트 만들기 - Azure AI services

필수 조건

Azure 구독 – 체험 구독을 만듭니다.
Azure AI 개발자 RBAC 역할이 할당되어 있는지 확인합니다.

기본 에이전트 설정 지원

시작하기 전에 기본 에이전트 설정 또는 표준 에이전트 설정을 수행할지 확인합니다. Azure AI Foundry는 기본 에이전트 설정만 지원합니다.

기본 설정: 에이전트는 Microsoft에서 완전히 관리되는 다중 테넌트 검색 및 스토리지 리소스를 사용합니다. 이러한 기본 Azure 리소스에 대한 가시성이나 제어 권한이 없습니다. Azure AI Foundry 포털 또는 자동화된 bicep 템플릿을 사용하여 기본 설정을 만들 수 있습니다.

표준 설정: 에이전트는 고객 소유의 단일 테넌트 검색 및 스토리지 리소스를 사용합니다. 이 설정을 사용하면 이러한 리소스에 대한 모든 권한과 가시성이 있지만 사용량에 따라 비용이 발생합니다. 표준 설정은 자동화된 bicep 템플릿을 사용하여 수행할 수 있습니다.

Important

Azure AI Foundry 포털은 현재 기본 설정만 지원합니다. 표준 에이전트 설정을 수행하려면 문서의 맨 위에 있는 다른 탭을 사용하여 표준 에이전트 구성에 대해 알아봅니다.

Azure AI Foundry 포털에서 허브 및 프로젝트 만들기

새 허브 및 프로젝트를 만들려면 리소스 그룹 또는 기존 허브에서 소유자 또는 기여자 역할이 필요합니다. 권한으로 인해 허브를 만들 수 없는 경우 관리자에게 문의하세요.

Azure AI Foundry에서 프로젝트를 만들려면 다음 단계를 수행합니다.

Azure AI Foundry로 이동합니다. 프로젝트에 있는 경우 페이지 왼쪽 위에 있는 Azure AI Foundry를 선택하여 홈 페이지로 이동합니다.
+프로젝트 만들기를 선택합니다.
프로젝트의 이름을 입력합니다.
허브가 있는 경우 가장 최근에 선택한 허브가 표시됩니다.
둘 이상의 허브에 액세스할 수 있는 경우 드롭다운에서 다른 허브를 선택할 수 있습니다.
새 허브를 만들려면 새 허브 만들기를 선택하고 이름을 제공합니다. 기본값을 사용자 지정하려면 Azure AI Foundry 설명서를 참조 하세요.
만들기를 실행합니다.

모델 배포

Azure AI Foundry에 로그인합니다.
프로젝트로 이동하거나 Azure AI Foundry 포털에서 새 프로젝트를 만듭니다.
프로젝트 개요에서 빌드 및 사용자 지정 아래에 있는 에이전트를 선택합니다.
Azure OpenAI 리소스를 선택합니다.
에이전트에서 사용할 모델 배포를 선택합니다. 모델이 없으면 새 모델을 배포하는 화면이 열립니다. 그렇지 않으면 모델 배포를 선택할 수 있습니다.

에이전트 플레이그라운드 사용

에이전트 플레이그라운드를 사용하면 코드를 실행할 필요 없이 에이전트를 탐색, 프로토타입 및 테스트할 수 있습니다. 이 페이지에서 새로운 아이디어를 빠르게 반복하고 실험할 수 있습니다.

에이전트 만들기 및 디버그 화면에서 에이전트를 선택하거나 새 에이전트를 사용하여 새 에이전트를 만듭니다. 오른쪽의 설정 창에서 해당 매개 변수 및 도구를 변경할 수 있습니다.

필요에 따라 에이전트에 대해 생성된 이름이 아닌 이름을 지정하고 성능을 향상시키는 데 도움이 되는 지침을 추가할 수 있습니다. 에이전트에게 수행할 작업 및 수행 방법에 대한 명확한 지침을 제공합니다. 특정 작업, 순서 및 톤 또는 참여 스타일과 같은 특별한 지침을 포함합니다.

팁

에이전트는 Bing을 사용하여 웹 검색, 코드 실행 등 기능을 확장하는 코드 인터프리터와 같은 여러 도구에 액세스할 수 있습니다. 설치 창에서 기술 자료 및 작업까지 아래로 스크롤하고 추가를 선택하여 사용할 수 있는 도구를 확인합니다.

참고 항목

에이전트와 함께 사용할 수 있는 모델을 확인합니다.

필수 조건

Azure 구독 – 체험 구독을 만듭니다.
최신 버전의 .NET
적절한 수준에서 Azure AI 개발자 RBAC 역할이 할당되었는지 확인합니다.
Azure CLI 및 기계 학습 확장을 설치 합니다. CLI가 이미 설치되어 있는 경우 최신 버전으로 업데이트되었는지 확인합니다.

Azure AI Hub 및 에이전트 프로젝트 설정

다음 섹션에서는 Azure AI 에이전트 서비스를 시작하는 데 필요한 리소스를 설정하는 방법을 보여 줍니다.

앱 환경 및 Azure 리소스를 설정하는 Azure AI Hub를 만듭니다.
허브에서 Azure AI 프로젝트를 만들면 앱이 호출할 엔드포인트가 만들어지고 테넌트에서 리소스에 액세스하도록 앱 서비스를 설정합니다.
Azure OpenAI 리소스 또는 Azure AI Services 리소스 연결

기본 또는 표준 에이전트 설정 선택

기본 설정: 에이전트는 Microsoft에서 완전히 관리되는 다중 테넌트 검색 및 스토리지 리소스를 사용합니다. 이러한 기본 Azure 리소스에 대한 가시성이나 제어 권한이 없습니다.

표준 설정: 에이전트는 고객 소유의 단일 테넌트 검색 및 스토리지 리소스를 사용합니다. 이 설정을 사용하면 이러한 리소스에 대한 모든 권한과 가시성이 있지만 사용량에 따라 비용이 발생합니다.

참고 항목

다음 자동화된 bicep 템플릿을 사용하여 표준 또는 기본 에이전트를 수행할 수 있습니다. Azure AI Foundry 포털을 사용하여 기본 에이전트를 만들 수도 있습니다. Azure AI Foundry는 현재 표준 에이전트 설정을 지원하지 않습니다.

설명 및 자동 배포	다이어그램(확대하려면 클릭)
인증에 관리 ID를 사용하는 기본 에이전트 설정을 배포합니다. AI 허브, AI 프로젝트, 스토리지 계정 및 AI 서비스에 대한 리소스가 만들어집니다. AI Services 계정은 프로젝트 및 허브에 연결되고 gpt-4o-mini 모델은 eastus 지역에 배포됩니다. Microsoft 관리형 키 자격 증명 모음은 기본적으로 사용됩니다.
인증에 관리 ID를 사용하는 표준 에이전트 설정을 배포합니다. AI 허브, AI 프로젝트, 키 자격 증명 모음, 스토리지 계정, AI 서비스 및 AI Search에 대한 리소스가 만들어집니다. AI 서비스, AI Search, 키 자격 증명 모음 및 스토리지 계정은 프로젝트 및 허브에 연결됩니다. gpt-4o-mini 모델은 eastus 지역에 배포됩니다.

설명 및 자동 배포

다이어그램(확대하려면 클릭)

인증에 관리 ID를 사용하는 기본 에이전트 설정을 배포합니다. AI 허브, AI 프로젝트, 스토리지 계정 및 AI 서비스에 대한 리소스가 만들어집니다.

AI Services 계정은 프로젝트 및 허브에 연결되고 gpt-4o-mini 모델은 eastus 지역에 배포됩니다. Microsoft 관리형 키 자격 증명 모음은 기본적으로 사용됩니다.

인증에 관리 ID를 사용하는 표준 에이전트 설정을 배포합니다.

AI 허브, AI 프로젝트, 키 자격 증명 모음, 스토리지 계정, AI 서비스 및 AI Search에 대한 리소스가 만들어집니다.

AI 서비스, AI Search, 키 자격 증명 모음 및 스토리지 계정은 프로젝트 및 허브에 연결됩니다. gpt-4o-mini 모델은 eastus 지역에 배포됩니다.

[선택 사항] 자동 배포 템플릿의 모델 선택

자동 배포 템플릿에서 모델 매개 변수를 편집하여 에이전트에서 사용하는 모델을 사용자 지정할 수 있습니다. 다른 모델을 배포하려면 최소한 및 modelVersion 매개 변수를 modelName 업데이트해야 합니다.

기본적으로 배포 템플릿은 다음 값으로 구성됩니다.

모델 매개 변수	기본값
modelName	gpt-4o-mini
modelFormat	OpenAI(Azure OpenAI의 경우)
모델 버전	2024-07-18
modelSkuName	GlobalStandard
modelLocation	eastus

Important

modelFormat 매개 변수를 변경하지 마세요.

템플릿은 Azure OpenAI 모델의 배포만 지원합니다. Azure AI 에이전트 서비스 모델 지원 설명서에서 지원되는 Azure OpenAI 모델을 확인합니다.

[선택 사항] 에이전트를 설정하는 동안 사용자 고유의 리소스 사용

참고 항목

기존 AI 서비스 또는 Azure OpenAI 리소스를 사용하는 경우 모델이 배포되지 않습니다. 에이전트 설정이 완료된 후 리소스에 모델을 배포할 수 있습니다.

매개 변수 파일에 전체 arm 리소스 ID를 제공하여 기존 AI 서비스, Azure OpenAI, AI Search 및/또는 Azure Blob Storage 리소스를 사용합니다.

aiServiceAccountResourceId
aiSearchServiceResourceId
aiStorageAccountResourceId

기존 Azure OpenAI 리소스를 사용하려면 매개 변수 파일의 aiServiceAccountResourceId 매개 변수와 매개 변수를 aiServiceKind 업데이트해야 합니다. 매개 변수는 aiServiceKind .로 AzureOpenAI설정해야 합니다.

자세한 내용은 사용자 고유의 리소스를 사용하는 방법을 참조 하세요.

에이전트 구성 및 실행

구성 요소	설명
에이전트	도구와 함께 AI 모델을 사용하는 사용자 지정 AI입니다.
도구	도구를 사용하면 대화 중에 안정적이고 정확하게 응답할 수 있는 에이전트의 기능을 확장할 수 있습니다. 예를 들어 모델을 접지하기 위해 사용자 정의 기술 자료 연결하거나 웹 검색을 사용하여 현재 정보를 제공할 수 있습니다.
스레드	에이전트와 사용자 간의 대화 세션입니다. 스레드는 메시지를 저장하고 자동으로 잘림을 처리하여 콘텐츠를 모델의 컨텍스트에 맞춥니다.
메시지	에이전트 또는 사용자가 만든 메시지입니다. 메시지에는 텍스트, 이미지 및 기타 파일이 포함될 수 있습니다. 메시지는 스레드에 목록으로 저장됩니다.
Run	스레드의 내용에 따라 실행을 시작할 에이전트의 활성화입니다. 에이전트는 해당 구성 및 스레드의 메시지를 사용하여 모델 및 도구를 호출하여 작업을 수행합니다. 실행의 일부로 에이전트는 스레드에 메시지를 추가합니다.
실행 단계	에이전트가 실행의 일부로 수행한 단계의 자세한 목록입니다. 에이전트는 실행하는 동안 도구를 호출하거나 메시지를 만들 수 있습니다. 실행 단계를 검사하면 에이전트가 결과를 얻는 방법을 이해할 수 있습니다.

프로젝트에 .NET 패키지를 설치합니다. 예를 들어 .NET CLI를 사용하는 경우 다음 명령을 실행합니다.

dotnet add package Azure.AI.Projects
dotnet add package Azure.Identity

다음으로, API 요청을 인증하고 프로그램을 실행하려면 az login 명령을 사용하여 Azure 구독에 로그인합니다.

az login

다음 코드를 사용하여 에이전트를 만들고 실행합니다. 이 코드를 실행하려면 프로젝트의 정보를 사용하여 연결 문자열 만들어야 합니다. 이 문자열의 형식은 다음과 같습니다.

<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>

팁

프로젝트 세부 정보>프로젝트 연결 문자열 Azure AI Foundry 포털의 프로젝트 개요에서 연결 문자열 찾을 수도 있습니다.

HostName 은 (을) 탐색하고 discovery_url 선행 https:// 및 후행을 제거하여 찾을 수 있습니다 /discovery. 찾으려면 다음 CLI 명령을 실행합니다 discovery_url.

az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url

예를 들어 연결 문자열 다음과 같이 표시할 수 있습니다.

eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name

이 연결 문자열 환경 PROJECT_CONNECTION_STRING변수로 설정합니다.

// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.

#nullable disable

using Azure.Identity;

namespace Azure.AI.Projects.Tests;

public class Sample_Agent
{
    static async Task Main()
    {
        var connectionString = Environment.GetEnvironmentVariable("PROJECT_CONNECTION_STRING");

        AgentsClient client = new AgentsClient(connectionString, new DefaultAzureCredential());

        // Step 1: Create an agent
        Response<Agent> agentResponse = await client.CreateAgentAsync(
            model: "gpt-4o-mini",
            name: "My Agent",
            instructions: "You are a helpful agent.",
            tools: new List<ToolDefinition> { new CodeInterpreterToolDefinition() });
        Agent agent = agentResponse.Value;

        // Intermission: agent should now be listed

        Response<PageableList<Agent>> agentListResponse = await client.GetAgentsAsync();

        //// Step 2: Create a thread
        Response<AgentThread> threadResponse = await client.CreateThreadAsync();
        AgentThread thread = threadResponse.Value;

        // Step 3: Add a message to a thread
        Response<ThreadMessage> messageResponse = await client.CreateMessageAsync(
            thread.Id,
            MessageRole.User,
            "I need to solve the equation `3x + 11 = 14`. Can you help me?");
        ThreadMessage message = messageResponse.Value;

        // Intermission: message is now correlated with thread
        // Intermission: listing messages will retrieve the message just added

        Response<PageableList<ThreadMessage>> messagesListResponse = await client.GetMessagesAsync(thread.Id);
        //Assert.That(messagesListResponse.Value.Data[0].Id == message.Id);

        // Step 4: Run the agent
        Response<ThreadRun> runResponse = await client.CreateRunAsync(
            thread.Id,
            agent.Id,
            additionalInstructions: "");
        ThreadRun run = runResponse.Value;

        do
        {
            await Task.Delay(TimeSpan.FromMilliseconds(500));
            runResponse = await client.GetRunAsync(thread.Id, runResponse.Value.Id);
        }
        while (runResponse.Value.Status == RunStatus.Queued
            || runResponse.Value.Status == RunStatus.InProgress);

        Response<PageableList<ThreadMessage>> afterRunMessagesResponse
            = await client.GetMessagesAsync(thread.Id);
        IReadOnlyList<ThreadMessage> messages = afterRunMessagesResponse.Value.Data;

        // Note: messages iterate from newest to oldest, with the messages[0] being the most recent
        foreach (ThreadMessage threadMessage in messages)
        {
            Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
            foreach (MessageContent contentItem in threadMessage.ContentItems)
            {
                if (contentItem is MessageTextContent textItem)
                {
                    Console.Write(textItem.Text);
                }
                else if (contentItem is MessageImageFileContent imageFileItem)
                {
                    Console.Write($"<image from ID: {imageFileItem.FileId}");
                }
                Console.WriteLine();
            }
        }
    }
}

필수 조건

Azure 구독 – 체험 구독을 만듭니다.
Python 3.8 이상
적절한 수준에서 Azure AI 개발자 RBAC 역할이 할당되었는지 확인합니다.
Azure CLI 및 기계 학습 확장을 설치 합니다. CLI가 이미 설치되어 있는 경우 최신 버전으로 업데이트되었는지 확인합니다.

Azure AI Hub 및 에이전트 프로젝트 설정

다음 섹션에서는 Azure AI 에이전트 서비스를 시작하는 데 필요한 리소스를 설정하는 방법을 보여 줍니다.

앱 환경 및 Azure 리소스를 설정하는 Azure AI Hub를 만듭니다.
허브에서 Azure AI 프로젝트를 만들면 앱이 호출할 엔드포인트가 만들어지고 테넌트에서 리소스에 액세스하도록 앱 서비스를 설정합니다.
Azure OpenAI 리소스 또는 Azure AI Services 리소스 연결

기본 또는 표준 에이전트 설정 선택

기본 설정: 에이전트는 Microsoft에서 완전히 관리되는 다중 테넌트 검색 및 스토리지 리소스를 사용합니다. 이러한 기본 Azure 리소스에 대한 가시성이나 제어 권한이 없습니다.

표준 설정: 에이전트는 고객 소유의 단일 테넌트 검색 및 스토리지 리소스를 사용합니다. 이 설정을 사용하면 이러한 리소스에 대한 모든 권한과 가시성이 있지만 사용량에 따라 비용이 발생합니다.

참고 항목

다음 자동화된 bicep 템플릿을 사용하여 표준 또는 기본 에이전트를 수행할 수 있습니다. Azure AI Foundry 포털을 사용하여 기본 에이전트를 만들 수도 있습니다. Azure AI Foundry는 현재 표준 에이전트 설정을 지원하지 않습니다.

설명 및 자동 배포	다이어그램(확대하려면 클릭)
인증에 관리 ID를 사용하는 기본 에이전트 설정을 배포합니다. AI 허브, AI 프로젝트, 스토리지 계정 및 AI 서비스에 대한 리소스가 만들어집니다. AI Services 계정은 프로젝트 및 허브에 연결되고 gpt-4o-mini 모델은 eastus 지역에 배포됩니다. Microsoft 관리형 키 자격 증명 모음은 기본적으로 사용됩니다.
인증에 관리 ID를 사용하는 표준 에이전트 설정을 배포합니다. AI 허브, AI 프로젝트, 키 자격 증명 모음, 스토리지 계정, AI 서비스 및 AI Search에 대한 리소스가 만들어집니다. AI 서비스, AI Search, 키 자격 증명 모음 및 스토리지 계정은 프로젝트 및 허브에 연결됩니다. gpt-4o-mini 모델은 eastus 지역에 배포됩니다.

설명 및 자동 배포

다이어그램(확대하려면 클릭)

인증에 관리 ID를 사용하는 기본 에이전트 설정을 배포합니다. AI 허브, AI 프로젝트, 스토리지 계정 및 AI 서비스에 대한 리소스가 만들어집니다.

AI Services 계정은 프로젝트 및 허브에 연결되고 gpt-4o-mini 모델은 eastus 지역에 배포됩니다. Microsoft 관리형 키 자격 증명 모음은 기본적으로 사용됩니다.

인증에 관리 ID를 사용하는 표준 에이전트 설정을 배포합니다.

AI 허브, AI 프로젝트, 키 자격 증명 모음, 스토리지 계정, AI 서비스 및 AI Search에 대한 리소스가 만들어집니다.

AI 서비스, AI Search, 키 자격 증명 모음 및 스토리지 계정은 프로젝트 및 허브에 연결됩니다. gpt-4o-mini 모델은 eastus 지역에 배포됩니다.

[선택 사항] 자동 배포 템플릿의 모델 선택

자동 배포 템플릿에서 모델 매개 변수를 편집하여 에이전트에서 사용하는 모델을 사용자 지정할 수 있습니다. 다른 모델을 배포하려면 최소한 및 modelVersion 매개 변수를 modelName 업데이트해야 합니다.

기본적으로 배포 템플릿은 다음 값으로 구성됩니다.

모델 매개 변수	기본값
modelName	gpt-4o-mini
modelFormat	OpenAI(Azure OpenAI의 경우)
모델 버전	2024-07-18
modelSkuName	GlobalStandard
modelLocation	eastus

Important

modelFormat 매개 변수를 변경하지 마세요.

템플릿은 Azure OpenAI 모델의 배포만 지원합니다. Azure AI 에이전트 서비스 모델 지원 설명서에서 지원되는 Azure OpenAI 모델을 확인합니다.

[선택 사항] 에이전트를 설정하는 동안 사용자 고유의 리소스 사용

참고 항목

기존 AI 서비스 또는 Azure OpenAI 리소스를 사용하는 경우 모델이 배포되지 않습니다. 에이전트 설정이 완료된 후 리소스에 모델을 배포할 수 있습니다.

매개 변수 파일에 전체 arm 리소스 ID를 제공하여 기존 AI 서비스, Azure OpenAI, AI Search 및/또는 Azure Blob Storage 리소스를 사용합니다.

aiServiceAccountResourceId
aiSearchServiceResourceId
aiStorageAccountResourceId

기존 Azure OpenAI 리소스를 사용하려면 매개 변수 파일의 aiServiceAccountResourceId 매개 변수와 매개 변수를 aiServiceKind 업데이트해야 합니다. 매개 변수는 aiServiceKind .로 AzureOpenAI설정해야 합니다.

자세한 내용은 사용자 고유의 리소스를 사용하는 방법을 참조 하세요.

에이전트 구성 및 실행

구성 요소	설명
에이전트	도구와 함께 AI 모델을 사용하는 사용자 지정 AI입니다.
도구	도구를 사용하면 대화 중에 안정적이고 정확하게 응답할 수 있는 에이전트의 기능을 확장할 수 있습니다. 예를 들어 모델을 접지하기 위해 사용자 정의 기술 자료 연결하거나 웹 검색을 사용하여 현재 정보를 제공할 수 있습니다.
스레드	에이전트와 사용자 간의 대화 세션입니다. 스레드는 메시지를 저장하고 자동으로 잘림을 처리하여 콘텐츠를 모델의 컨텍스트에 맞춥니다.
메시지	에이전트 또는 사용자가 만든 메시지입니다. 메시지에는 텍스트, 이미지 및 기타 파일이 포함될 수 있습니다. 메시지는 스레드에 목록으로 저장됩니다.
Run	스레드의 내용에 따라 실행을 시작할 에이전트의 활성화입니다. 에이전트는 해당 구성 및 스레드의 메시지를 사용하여 모델 및 도구를 호출하여 작업을 수행합니다. 실행의 일부로 에이전트는 스레드에 메시지를 추가합니다.
실행 단계	에이전트가 실행의 일부로 수행한 단계의 자세한 목록입니다. 에이전트는 실행하는 동안 도구를 호출하거나 메시지를 만들 수 있습니다. 실행 단계를 검사하면 에이전트가 결과를 얻는 방법을 이해할 수 있습니다.

다음 명령을 실행하여 Python 패키지를 설치합니다.

pip install azure-ai-projects
pip install azure-identity

다음으로, API 요청을 인증하고 프로그램을 실행하려면 az login 명령을 사용하여 Azure 구독에 로그인합니다.

az login

다음 코드를 사용하여 에이전트를 만들고 실행합니다. 이 코드를 실행하려면 프로젝트의 정보를 사용하여 연결 문자열 만들어야 합니다. 이 문자열의 형식은 다음과 같습니다.

<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>

팁

프로젝트 세부 정보>프로젝트 연결 문자열 Azure AI Foundry 포털의 프로젝트 개요에서 연결 문자열 찾을 수도 있습니다.

HostName 은 (을) 탐색하고 discovery_url 선행 https:// 및 후행을 제거하여 찾을 수 있습니다 /discovery. 찾으려면 다음 CLI 명령을 실행합니다 discovery_url.

az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url

예를 들어 연결 문자열 다음과 같이 표시할 수 있습니다.

eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name

이 연결 문자열 환경 PROJECT_CONNECTION_STRING변수로 설정합니다.

import os
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import CodeInterpreterTool
from azure.identity import DefaultAzureCredential
from typing import Any
from pathlib import Path

# Create an Azure AI Client from a connection string, copied from your Azure AI Foundry project.
# At the moment, it should be in the format "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>"
# HostName can be found by navigating to your discovery_url and removing the leading "https://" and trailing "/discovery"
# To find your discovery_url, run the CLI command: az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url
# Project Connection example: eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name
# Customer needs to login to Azure subscription via Azure CLI and set the environment variables

project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(), conn_str=os.environ["PROJECT_CONNECTION_STRING"]
)

with project_client:
    # Create an instance of the CodeInterpreterTool
    code_interpreter = CodeInterpreterTool()

    # The CodeInterpreterTool needs to be included in creation of the agent
    agent = project_client.agents.create_agent(
        model="gpt-4o-mini",
        name="my-agent",
        instructions="You are helpful agent",
        tools=code_interpreter.definitions,
        tool_resources=code_interpreter.resources,
    )
    print(f"Created agent, agent ID: {agent.id}")

    # Create a thread
    thread = project_client.agents.create_thread()
    print(f"Created thread, thread ID: {thread.id}")

    # Create a message
    message = project_client.agents.create_message(
        thread_id=thread.id,
        role="user",
        content="Could you please create a bar chart for the operating profit using the following data and provide the file to me? Company A: $1.2 million, Company B: $2.5 million, Company C: $3.0 million, Company D: $1.8 million",
    )
    print(f"Created message, message ID: {message.id}")

    # Run the agent
    run = project_client.agents.create_and_process_run(thread_id=thread.id, assistant_id=agent.id)
    print(f"Run finished with status: {run.status}")

    if run.status == "failed":
        # Check if you got "Rate limit is exceeded.", then you want to get more quota
        print(f"Run failed: {run.last_error}")

    # Get messages from the thread
    messages = project_client.agents.list_messages(thread_id=thread.id)
    print(f"Messages: {messages}")

    # Get the last message from the sender
    last_msg = messages.get_last_text_message_by_role("assistant")
    if last_msg:
        print(f"Last Message: {last_msg.text.value}")

    # Generate an image file for the bar chart
    for image_content in messages.image_contents:
        print(f"Image File ID: {image_content.image_file.file_id}")
        file_name = f"{image_content.image_file.file_id}_image_file.png"
        project_client.agents.save_file(file_id=image_content.image_file.file_id, file_name=file_name)
        print(f"Saved image file to: {Path.cwd() / file_name}")

    # Print the file path(s) from the messages
    for file_path_annotation in messages.file_path_annotations:
        print(f"File Paths:")
        print(f"Type: {file_path_annotation.type}")
        print(f"Text: {file_path_annotation.text}")
        print(f"File ID: {file_path_annotation.file_path.file_id}")
        print(f"Start Index: {file_path_annotation.start_index}")
        print(f"End Index: {file_path_annotation.end_index}")
        project_client.agents.save_file(file_id=file_path_annotation.file_path.file_id, file_name=Path(file_path_annotation.text).name)

    # Delete the agent once done
    project_client.agents.delete_agent(agent.id)
    print("Deleted agent")

| 참조 설명서 | 라이브러리 소스 코드 | 패키지(PyPi) |

필수 조건

Azure 구독 – 체험 구독을 만듭니다.
Python 3.8 이상
적절한 수준에서 Azure AI 개발자 RBAC 역할이 할당되었는지 확인합니다.
Azure AI Services 리소스를 사용하려면 Cognitive Services OpenAI 사용자 역할이 할당되어야 합니다.
Azure CLI 및 기계 학습 확장을 설치 합니다. CLI가 이미 설치되어 있는 경우 최신 버전으로 업데이트되었는지 확인합니다.

Azure AI Hub 및 에이전트 프로젝트 설정

다음 섹션에서는 Azure AI 에이전트 서비스를 시작하는 데 필요한 리소스를 설정하는 방법을 보여 줍니다.

앱 환경 및 Azure 리소스를 설정하는 Azure AI Hub를 만듭니다.
허브에서 Azure AI 프로젝트를 만들면 앱이 호출할 엔드포인트가 만들어지고 테넌트에서 리소스에 액세스하도록 앱 서비스를 설정합니다.
Azure OpenAI 리소스 또는 Azure AI Services 리소스 연결

기본 또는 표준 에이전트 설정 선택

기본 설정: 에이전트는 Microsoft에서 완전히 관리되는 다중 테넌트 검색 및 스토리지 리소스를 사용합니다. 이러한 기본 Azure 리소스에 대한 가시성이나 제어 권한이 없습니다.

표준 설정: 에이전트는 고객 소유의 단일 테넌트 검색 및 스토리지 리소스를 사용합니다. 이 설정을 사용하면 이러한 리소스에 대한 모든 권한과 가시성이 있지만 사용량에 따라 비용이 발생합니다.

참고 항목

다음 자동화된 bicep 템플릿을 사용하여 표준 또는 기본 에이전트를 수행할 수 있습니다. Azure AI Foundry 포털을 사용하여 기본 에이전트를 만들 수도 있습니다. Azure AI Foundry는 현재 표준 에이전트 설정을 지원하지 않습니다.

설명 및 자동 배포	다이어그램(확대하려면 클릭)
인증에 관리 ID를 사용하는 기본 에이전트 설정을 배포합니다. AI 허브, AI 프로젝트, 스토리지 계정 및 AI 서비스에 대한 리소스가 만들어집니다. AI Services 계정은 프로젝트 및 허브에 연결되고 gpt-4o-mini 모델은 eastus 지역에 배포됩니다. Microsoft 관리형 키 자격 증명 모음은 기본적으로 사용됩니다.
인증에 관리 ID를 사용하는 표준 에이전트 설정을 배포합니다. AI 허브, AI 프로젝트, 키 자격 증명 모음, 스토리지 계정, AI 서비스 및 AI Search에 대한 리소스가 만들어집니다. AI 서비스, AI Search, 키 자격 증명 모음 및 스토리지 계정은 프로젝트 및 허브에 연결됩니다. gpt-4o-mini 모델은 eastus 지역에 배포됩니다.

설명 및 자동 배포

다이어그램(확대하려면 클릭)

인증에 관리 ID를 사용하는 기본 에이전트 설정을 배포합니다. AI 허브, AI 프로젝트, 스토리지 계정 및 AI 서비스에 대한 리소스가 만들어집니다.

AI Services 계정은 프로젝트 및 허브에 연결되고 gpt-4o-mini 모델은 eastus 지역에 배포됩니다. Microsoft 관리형 키 자격 증명 모음은 기본적으로 사용됩니다.

인증에 관리 ID를 사용하는 표준 에이전트 설정을 배포합니다.

AI 허브, AI 프로젝트, 키 자격 증명 모음, 스토리지 계정, AI 서비스 및 AI Search에 대한 리소스가 만들어집니다.

AI 서비스, AI Search, 키 자격 증명 모음 및 스토리지 계정은 프로젝트 및 허브에 연결됩니다. gpt-4o-mini 모델은 eastus 지역에 배포됩니다.

[선택 사항] 자동 배포 템플릿의 모델 선택

자동 배포 템플릿에서 모델 매개 변수를 편집하여 에이전트에서 사용하는 모델을 사용자 지정할 수 있습니다. 다른 모델을 배포하려면 최소한 및 modelVersion 매개 변수를 modelName 업데이트해야 합니다.

기본적으로 배포 템플릿은 다음 값으로 구성됩니다.

모델 매개 변수	기본값
modelName	gpt-4o-mini
modelFormat	OpenAI(Azure OpenAI의 경우)
모델 버전	2024-07-18
modelSkuName	GlobalStandard
modelLocation	eastus

Important

modelFormat 매개 변수를 변경하지 마세요.

템플릿은 Azure OpenAI 모델의 배포만 지원합니다. Azure AI 에이전트 서비스 모델 지원 설명서에서 지원되는 Azure OpenAI 모델을 확인합니다.

[선택 사항] 에이전트를 설정하는 동안 사용자 고유의 리소스 사용

참고 항목

기존 AI 서비스 또는 Azure OpenAI 리소스를 사용하는 경우 모델이 배포되지 않습니다. 에이전트 설정이 완료된 후 리소스에 모델을 배포할 수 있습니다.

매개 변수 파일에 전체 arm 리소스 ID를 제공하여 기존 AI 서비스, Azure OpenAI, AI Search 및/또는 Azure Blob Storage 리소스를 사용합니다.

aiServiceAccountResourceId
aiSearchServiceResourceId
aiStorageAccountResourceId

기존 Azure OpenAI 리소스를 사용하려면 매개 변수 파일의 aiServiceAccountResourceId 매개 변수와 매개 변수를 aiServiceKind 업데이트해야 합니다. 매개 변수는 aiServiceKind .로 AzureOpenAI설정해야 합니다.

자세한 내용은 사용자 고유의 리소스를 사용하는 방법을 참조 하세요.

에이전트 구성 및 실행

구성 요소	설명
에이전트	도구와 함께 AI 모델을 사용하는 사용자 지정 AI입니다.
도구	도구를 사용하면 대화 중에 안정적이고 정확하게 응답할 수 있는 에이전트의 기능을 확장할 수 있습니다. 예를 들어 모델을 접지하기 위해 사용자 정의 기술 자료 연결하거나 웹 검색을 사용하여 현재 정보를 제공할 수 있습니다.
스레드	에이전트와 사용자 간의 대화 세션입니다. 스레드는 메시지를 저장하고 자동으로 잘림을 처리하여 콘텐츠를 모델의 컨텍스트에 맞춥니다.
메시지	에이전트 또는 사용자가 만든 메시지입니다. 메시지에는 텍스트, 이미지 및 기타 파일이 포함될 수 있습니다. 메시지는 스레드에 목록으로 저장됩니다.
Run	스레드의 내용에 따라 실행을 시작할 에이전트의 활성화입니다. 에이전트는 해당 구성 및 스레드의 메시지를 사용하여 모델 및 도구를 호출하여 작업을 수행합니다. 실행의 일부로 에이전트는 스레드에 메시지를 추가합니다.
실행 단계	에이전트가 실행의 일부로 수행한 단계의 자세한 목록입니다. 에이전트는 실행하는 동안 도구를 호출하거나 메시지를 만들 수 있습니다. 실행 단계를 검사하면 에이전트가 결과를 얻는 방법을 이해할 수 있습니다.

다음 명령을 실행하여 Python 패키지를 설치합니다.

pip install azure-ai-projects
pip install azure-identity
pip install openai

다음으로, API 요청을 인증하고 프로그램을 실행하려면 az login 명령을 사용하여 Azure 구독에 로그인합니다.

az login

다음 코드를 사용하여 에이전트를 만들고 실행합니다. 이 코드를 실행하려면 프로젝트의 정보를 사용하여 연결 문자열 만들어야 합니다. 이 문자열의 형식은 다음과 같습니다.

<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>

팁

프로젝트 세부 정보>프로젝트 연결 문자열 Azure AI Foundry 포털의 프로젝트 개요에서 연결 문자열 찾을 수도 있습니다.

HostName 은 (을) 탐색하고 discovery_url 선행 https:// 및 후행을 제거하여 찾을 수 있습니다 /discovery. 찾으려면 다음 CLI 명령을 실행합니다 discovery_url.

az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url

예를 들어 연결 문자열 다음과 같이 표시할 수 있습니다.

eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name

이 연결 문자열 환경 PROJECT_CONNECTION_STRING변수로 설정합니다.

import os, time
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from openai import AzureOpenAI


with AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str=os.environ["PROJECT_CONNECTION_STRING"],
) as project_client:

    # Explicit type hinting for IntelliSense
    client: AzureOpenAI = project_client.inference.get_azure_openai_client(
        # The latest API version is 2024-10-01-preview
        api_version = os.environ.get("AZURE_OPENAI_API_VERSION"),
    )

    with client:
        agent = client.beta.assistants.create(
            model="gpt-4o-mini", name="my-agent", instructions="You are a helpful agent"
        )
        print(f"Created agent, agent ID: {agent.id}")

        thread = client.beta.threads.create()
        print(f"Created thread, thread ID: {thread.id}")

        message = client.beta.threads.messages.create(thread_id=thread.id, role="user", content="Hello, tell me a joke")
        print(f"Created message, message ID: {message.id}")

        run = client.beta.threads.runs.create(thread_id=thread.id, assistant_id=agent.id)

        # Poll the run while run status is queued or in progress
        while run.status in ["queued", "in_progress", "requires_action"]:
            time.sleep(1)  # Wait for a second
            run = client.beta.threads.runs.retrieve(thread_id=thread.id, run_id=run.id)
            print(f"Run status: {run.status}")

        client.beta.assistants.delete(agent.id)
        print("Deleted agent")

        messages = client.beta.threads.messages.list(thread_id=thread.id)
        print(f"Messages: {messages}")

필수 조건

Azure 구독 – 체험 구독을 만듭니다.
Node.js LTS
적절한 수준에서 Azure AI 개발자 RBAC 역할이 할당되었는지 확인합니다.
Azure CLI 및 기계 학습 확장을 설치 합니다. CLI가 이미 설치되어 있는 경우 최신 버전으로 업데이트되었는지 확인합니다.

Azure AI Hub 및 에이전트 프로젝트 설정

다음 섹션에서는 Azure AI 에이전트 서비스를 시작하는 데 필요한 리소스를 설정하는 방법을 보여 줍니다.

앱 환경 및 Azure 리소스를 설정하는 Azure AI Hub를 만듭니다.
허브에서 Azure AI 프로젝트를 만들면 앱이 호출할 엔드포인트가 만들어지고 테넌트에서 리소스에 액세스하도록 앱 서비스를 설정합니다.
Azure OpenAI 리소스 또는 Azure AI Services 리소스 연결

기본 또는 표준 에이전트 설정 선택

기본 설정: 에이전트는 Microsoft에서 완전히 관리되는 다중 테넌트 검색 및 스토리지 리소스를 사용합니다. 이러한 기본 Azure 리소스에 대한 가시성이나 제어 권한이 없습니다.

표준 설정: 에이전트는 고객 소유의 단일 테넌트 검색 및 스토리지 리소스를 사용합니다. 이 설정을 사용하면 이러한 리소스에 대한 모든 권한과 가시성이 있지만 사용량에 따라 비용이 발생합니다.

참고 항목

다음 자동화된 bicep 템플릿을 사용하여 표준 또는 기본 에이전트를 수행할 수 있습니다. Azure AI Foundry 포털을 사용하여 기본 에이전트를 만들 수도 있습니다. Azure AI Foundry는 현재 표준 에이전트 설정을 지원하지 않습니다.

설명 및 자동 배포	다이어그램(확대하려면 클릭)
인증에 관리 ID를 사용하는 기본 에이전트 설정을 배포합니다. AI 허브, AI 프로젝트, 스토리지 계정 및 AI 서비스에 대한 리소스가 만들어집니다. AI Services 계정은 프로젝트 및 허브에 연결되고 gpt-4o-mini 모델은 eastus 지역에 배포됩니다. Microsoft 관리형 키 자격 증명 모음은 기본적으로 사용됩니다.
인증에 관리 ID를 사용하는 표준 에이전트 설정을 배포합니다. AI 허브, AI 프로젝트, 키 자격 증명 모음, 스토리지 계정, AI 서비스 및 AI Search에 대한 리소스가 만들어집니다. AI 서비스, AI Search, 키 자격 증명 모음 및 스토리지 계정은 프로젝트 및 허브에 연결됩니다. gpt-4o-mini 모델은 eastus 지역에 배포됩니다.

설명 및 자동 배포

다이어그램(확대하려면 클릭)

인증에 관리 ID를 사용하는 기본 에이전트 설정을 배포합니다. AI 허브, AI 프로젝트, 스토리지 계정 및 AI 서비스에 대한 리소스가 만들어집니다.

AI Services 계정은 프로젝트 및 허브에 연결되고 gpt-4o-mini 모델은 eastus 지역에 배포됩니다. Microsoft 관리형 키 자격 증명 모음은 기본적으로 사용됩니다.

인증에 관리 ID를 사용하는 표준 에이전트 설정을 배포합니다.

AI 허브, AI 프로젝트, 키 자격 증명 모음, 스토리지 계정, AI 서비스 및 AI Search에 대한 리소스가 만들어집니다.

AI 서비스, AI Search, 키 자격 증명 모음 및 스토리지 계정은 프로젝트 및 허브에 연결됩니다. gpt-4o-mini 모델은 eastus 지역에 배포됩니다.

[선택 사항] 자동 배포 템플릿의 모델 선택

자동 배포 템플릿에서 모델 매개 변수를 편집하여 에이전트에서 사용하는 모델을 사용자 지정할 수 있습니다. 다른 모델을 배포하려면 최소한 및 modelVersion 매개 변수를 modelName 업데이트해야 합니다.

기본적으로 배포 템플릿은 다음 값으로 구성됩니다.

모델 매개 변수	기본값
modelName	gpt-4o-mini
modelFormat	OpenAI(Azure OpenAI의 경우)
모델 버전	2024-07-18
modelSkuName	GlobalStandard
modelLocation	eastus

Important

modelFormat 매개 변수를 변경하지 마세요.

템플릿은 Azure OpenAI 모델의 배포만 지원합니다. Azure AI 에이전트 서비스 모델 지원 설명서에서 지원되는 Azure OpenAI 모델을 확인합니다.

[선택 사항] 에이전트를 설정하는 동안 사용자 고유의 리소스 사용

참고 항목

기존 AI 서비스 또는 Azure OpenAI 리소스를 사용하는 경우 모델이 배포되지 않습니다. 에이전트 설정이 완료된 후 리소스에 모델을 배포할 수 있습니다.

매개 변수 파일에 전체 arm 리소스 ID를 제공하여 기존 AI 서비스, Azure OpenAI, AI Search 및/또는 Azure Blob Storage 리소스를 사용합니다.

aiServiceAccountResourceId
aiSearchServiceResourceId
aiStorageAccountResourceId

기존 Azure OpenAI 리소스를 사용하려면 매개 변수 파일의 aiServiceAccountResourceId 매개 변수와 매개 변수를 aiServiceKind 업데이트해야 합니다. 매개 변수는 aiServiceKind .로 AzureOpenAI설정해야 합니다.

자세한 내용은 사용자 고유의 리소스를 사용하는 방법을 참조 하세요.

에이전트 구성 및 실행

구성 요소	설명
에이전트	도구와 함께 AI 모델을 사용하는 사용자 지정 AI입니다.
도구	도구를 사용하면 대화 중에 안정적이고 정확하게 응답할 수 있는 에이전트의 기능을 확장할 수 있습니다. 예를 들어 모델을 접지하기 위해 사용자 정의 기술 자료 연결하거나 웹 검색을 사용하여 현재 정보를 제공할 수 있습니다.
스레드	에이전트와 사용자 간의 대화 세션입니다. 스레드는 메시지를 저장하고 자동으로 잘림을 처리하여 콘텐츠를 모델의 컨텍스트에 맞춥니다.
메시지	에이전트 또는 사용자가 만든 메시지입니다. 메시지에는 텍스트, 이미지 및 기타 파일이 포함될 수 있습니다. 메시지는 스레드에 목록으로 저장됩니다.
Run	스레드의 내용에 따라 실행을 시작할 에이전트의 활성화입니다. 에이전트는 해당 구성 및 스레드의 메시지를 사용하여 모델 및 도구를 호출하여 작업을 수행합니다. 실행의 일부로 에이전트는 스레드에 메시지를 추가합니다.
실행 단계	에이전트가 실행의 일부로 수행한 단계의 자세한 목록입니다. 에이전트는 실행하는 동안 도구를 호출하거나 메시지를 만들 수 있습니다. 실행 단계를 검사하면 에이전트가 결과를 얻는 방법을 이해할 수 있습니다.

다음 명령을 실행하여 npm 패키지를 설치합니다.

npm install @azure/ai-projects
npm install @azure/identity

다음으로, API 요청을 인증하고 프로그램을 실행하려면 az login 명령을 사용하여 Azure 구독에 로그인합니다.

az login

다음 코드를 사용하여 에이전트를 만들고 실행합니다. 이 코드를 실행하려면 프로젝트의 정보를 사용하여 연결 문자열 만들어야 합니다. 이 문자열의 형식은 다음과 같습니다.

<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>

팁

프로젝트 세부 정보>프로젝트 연결 문자열 Azure AI Foundry 포털의 프로젝트 개요에서 연결 문자열 찾을 수도 있습니다.

HostName 은 (을) 탐색하고 discovery_url 선행 https:// 및 후행을 제거하여 찾을 수 있습니다 /discovery. 찾으려면 다음 CLI 명령을 실행합니다 discovery_url.

az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url

예를 들어 연결 문자열 다음과 같이 표시할 수 있습니다.

eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name

이 연결 문자열 환경 PROJECT_CONNECTION_STRING변수로 설정합니다.

// index.js

import {
  AIProjectsClient,
  DoneEvent,
  ErrorEvent,
  isOutputOfType,
  MessageStreamEvent,
  RunStreamEvent,
  ToolUtility,
} from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

const connectionString =
  process.env["AZURE_AI_PROJECTS_CONNECTION_STRING"] || "<project connection string>";

if (!connectionString) {
  throw new Error("AZURE_AI_PROJECTS_CONNECTION_STRING must be set in the environment variables");
}

export async function main() {
  const client = AIProjectsClient.fromConnectionString(
    connectionString || "",
    new DefaultAzureCredential(),
  );

  // Step 1 code interpreter tool
  const codeInterpreterTool = ToolUtility.createCodeInterpreterTool();

  // Step 2 an agent
  const agent = await client.agents.createAgent("gpt-4o-mini", {
    name: "my-agent",
    instructions: "You are a helpful agent",
    tools: [codeInterpreterTool.definition],
    toolResources: codeInterpreterTool.resources,
  });

  // Step 3 a thread
  const thread = await client.agents.createThread();

  // Step 4 a message to thread
  await client.agents.createMessage(
    thread.id, {
    role: "user",
    content: "I need to solve the equation `3x + 11 = 14`. Can you help me?",
  });

  // Intermission is now correlated with thread
  // Intermission messages will retrieve the message just added

  // Step 5 the agent
  const streamEventMessages = await client.agents.createRun(thread.id, agent.id).stream();

  for await (const eventMessage of streamEventMessages) {
    switch (eventMessage.event) {
      case RunStreamEvent.ThreadRunCreated:
        break;
      case MessageStreamEvent.ThreadMessageDelta:
        {
          const messageDelta = eventMessage.data;
          messageDelta.delta.content.forEach((contentPart) => {
            if (contentPart.type === "text") {
              const textContent = contentPart;
              const textValue = textContent.text?.value || "No text";
            }
          });
        }
        break;

      case RunStreamEvent.ThreadRunCompleted:
        break;
      case ErrorEvent.Error:
        console.log(`An error occurred. Data ${eventMessage.data}`);
        break;
      case DoneEvent.Done:
        break;
    }
  }

  // 6. Print the messages from the agent
  const messages = await client.agents.listMessages(thread.id);

  // Messages iterate from oldest to newest
  // messages[0] is the most recent
  for (let i = messages.data.length - 1; i >= 0; i--) {
    const m = messages.data[i];
    if (isOutputOfType(m.content[0], "text")) {
      const textContent = m.content[0];
      console.log(`${textContent.text.value}`);
      console.log(`---------------------------------`);
    }
  }

  // 7. Delete the agent once done
  await client.agents.deleteAgent(agent.id);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

출력에는 프롬프트와 답변이 포함됩니다.

I need to solve the equation `3x + 11 = 14`. Can you help me?
---------------------------------
Sure! I can help you solve the equation \(3x + 11 = 14\).

To solve this equation, we need to isolate the variable \(x\). Let's go ahead and solve it.
---------------------------------
The solution to the equation \(3x + 11 = 14\) is \(x = 1\). 

Therefore, the value of \(x\) that satisfies the equation is 1. 

Let me know if you need help with anything else!
---------------------------------

필수 조건

Azure 구독 – 체험 구독을 만듭니다.
Node.js LTS
TypeScript 5.x
적절한 수준에서 Azure AI 개발자 RBAC 역할이 할당되었는지 확인합니다.
Azure CLI 및 기계 학습 확장을 설치 합니다. CLI가 이미 설치되어 있는 경우 최신 버전으로 업데이트되었는지 확인합니다.

Azure AI Hub 및 에이전트 프로젝트 설정

다음 섹션에서는 Azure AI 에이전트 서비스를 시작하는 데 필요한 리소스를 설정하는 방법을 보여 줍니다.

앱 환경 및 Azure 리소스를 설정하는 Azure AI Hub를 만듭니다.
허브에서 Azure AI 프로젝트를 만들면 앱이 호출할 엔드포인트가 만들어지고 테넌트에서 리소스에 액세스하도록 앱 서비스를 설정합니다.
Azure OpenAI 리소스 또는 Azure AI Services 리소스 연결

기본 또는 표준 에이전트 설정 선택

기본 설정: 에이전트는 Microsoft에서 완전히 관리되는 다중 테넌트 검색 및 스토리지 리소스를 사용합니다. 이러한 기본 Azure 리소스에 대한 가시성이나 제어 권한이 없습니다.

표준 설정: 에이전트는 고객 소유의 단일 테넌트 검색 및 스토리지 리소스를 사용합니다. 이 설정을 사용하면 이러한 리소스에 대한 모든 권한과 가시성이 있지만 사용량에 따라 비용이 발생합니다.

참고 항목

다음 자동화된 bicep 템플릿을 사용하여 표준 또는 기본 에이전트를 수행할 수 있습니다. Azure AI Foundry 포털을 사용하여 기본 에이전트를 만들 수도 있습니다. Azure AI Foundry는 현재 표준 에이전트 설정을 지원하지 않습니다.

설명 및 자동 배포	다이어그램(확대하려면 클릭)
인증에 관리 ID를 사용하는 기본 에이전트 설정을 배포합니다. AI 허브, AI 프로젝트, 스토리지 계정 및 AI 서비스에 대한 리소스가 만들어집니다. AI Services 계정은 프로젝트 및 허브에 연결되고 gpt-4o-mini 모델은 eastus 지역에 배포됩니다. Microsoft 관리형 키 자격 증명 모음은 기본적으로 사용됩니다.
인증에 관리 ID를 사용하는 표준 에이전트 설정을 배포합니다. AI 허브, AI 프로젝트, 키 자격 증명 모음, 스토리지 계정, AI 서비스 및 AI Search에 대한 리소스가 만들어집니다. AI 서비스, AI Search, 키 자격 증명 모음 및 스토리지 계정은 프로젝트 및 허브에 연결됩니다. gpt-4o-mini 모델은 eastus 지역에 배포됩니다.

설명 및 자동 배포

다이어그램(확대하려면 클릭)

인증에 관리 ID를 사용하는 기본 에이전트 설정을 배포합니다. AI 허브, AI 프로젝트, 스토리지 계정 및 AI 서비스에 대한 리소스가 만들어집니다.

AI Services 계정은 프로젝트 및 허브에 연결되고 gpt-4o-mini 모델은 eastus 지역에 배포됩니다. Microsoft 관리형 키 자격 증명 모음은 기본적으로 사용됩니다.

인증에 관리 ID를 사용하는 표준 에이전트 설정을 배포합니다.

AI 허브, AI 프로젝트, 키 자격 증명 모음, 스토리지 계정, AI 서비스 및 AI Search에 대한 리소스가 만들어집니다.

AI 서비스, AI Search, 키 자격 증명 모음 및 스토리지 계정은 프로젝트 및 허브에 연결됩니다. gpt-4o-mini 모델은 eastus 지역에 배포됩니다.

[선택 사항] 자동 배포 템플릿의 모델 선택

자동 배포 템플릿에서 모델 매개 변수를 편집하여 에이전트에서 사용하는 모델을 사용자 지정할 수 있습니다. 다른 모델을 배포하려면 최소한 및 modelVersion 매개 변수를 modelName 업데이트해야 합니다.

기본적으로 배포 템플릿은 다음 값으로 구성됩니다.

모델 매개 변수	기본값
modelName	gpt-4o-mini
modelFormat	OpenAI(Azure OpenAI의 경우)
모델 버전	2024-07-18
modelSkuName	GlobalStandard
modelLocation	eastus

Important

modelFormat 매개 변수를 변경하지 마세요.

템플릿은 Azure OpenAI 모델의 배포만 지원합니다. Azure AI 에이전트 서비스 모델 지원 설명서에서 지원되는 Azure OpenAI 모델을 확인합니다.

[선택 사항] 에이전트를 설정하는 동안 사용자 고유의 리소스 사용

참고 항목

기존 AI 서비스 또는 Azure OpenAI 리소스를 사용하는 경우 모델이 배포되지 않습니다. 에이전트 설정이 완료된 후 리소스에 모델을 배포할 수 있습니다.

매개 변수 파일에 전체 arm 리소스 ID를 제공하여 기존 AI 서비스, Azure OpenAI, AI Search 및/또는 Azure Blob Storage 리소스를 사용합니다.

aiServiceAccountResourceId
aiSearchServiceResourceId
aiStorageAccountResourceId

기존 Azure OpenAI 리소스를 사용하려면 매개 변수 파일의 aiServiceAccountResourceId 매개 변수와 매개 변수를 aiServiceKind 업데이트해야 합니다. 매개 변수는 aiServiceKind .로 AzureOpenAI설정해야 합니다.

자세한 내용은 사용자 고유의 리소스를 사용하는 방법을 참조 하세요.

에이전트 구성 및 실행

구성 요소	설명
에이전트	도구와 함께 AI 모델을 사용하는 사용자 지정 AI입니다.
도구	도구를 사용하면 대화 중에 안정적이고 정확하게 응답할 수 있는 에이전트의 기능을 확장할 수 있습니다. 예를 들어 모델을 접지하기 위해 사용자 정의 기술 자료 연결하거나 웹 검색을 사용하여 현재 정보를 제공할 수 있습니다.
스레드	에이전트와 사용자 간의 대화 세션입니다. 스레드는 메시지를 저장하고 자동으로 잘림을 처리하여 콘텐츠를 모델의 컨텍스트에 맞춥니다.
메시지	에이전트 또는 사용자가 만든 메시지입니다. 메시지에는 텍스트, 이미지 및 기타 파일이 포함될 수 있습니다. 메시지는 스레드에 목록으로 저장됩니다.
Run	스레드의 내용에 따라 실행을 시작할 에이전트의 활성화입니다. 에이전트는 해당 구성 및 스레드의 메시지를 사용하여 모델 및 도구를 호출하여 작업을 수행합니다. 실행의 일부로 에이전트는 스레드에 메시지를 추가합니다.
실행 단계	에이전트가 실행의 일부로 수행한 단계의 자세한 목록입니다. 에이전트는 실행하는 동안 도구를 호출하거나 메시지를 만들 수 있습니다. 실행 단계를 검사하면 에이전트가 결과를 얻는 방법을 이해할 수 있습니다.

다음 명령을 실행하여 npm 패키지를 설치합니다.

npm install @azure/ai-projects
npm install @azure/identity

다음으로, API 요청을 인증하고 프로그램을 실행하려면 az login 명령을 사용하여 Azure 구독에 로그인합니다.

az login

다음 코드를 사용하여 에이전트를 만들고 실행합니다. 이 코드를 실행하려면 프로젝트의 정보를 사용하여 연결 문자열 만들어야 합니다. 이 문자열의 형식은 다음과 같습니다.

<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<ProjectName>

팁

프로젝트 세부 정보>프로젝트 연결 문자열 Azure AI Foundry 포털의 프로젝트 개요에서 연결 문자열 찾을 수도 있습니다.

HostName 은 (을) 탐색하고 discovery_url 선행 https:// 및 후행을 제거하여 찾을 수 있습니다 /discovery. 찾으려면 다음 CLI 명령을 실행합니다 discovery_url.

az ml workspace show -n {project_name} --resource-group {resource_group_name} --query discovery_url

예를 들어 연결 문자열 다음과 같이 표시할 수 있습니다.

eastus.api.azureml.ms;12345678-abcd-1234-9fc6-62780b3d3e05;my-resource-group;my-project-name

이 연결 문자열 환경 PROJECT_CONNECTION_STRING변수로 설정합니다.

// index.ts

import type {
  MessageDeltaChunk,
  MessageDeltaTextContent,
  MessageTextContentOutput,
} from "@azure/ai-projects";
import {
  AIProjectsClient,
  DoneEvent,
  ErrorEvent,
  isOutputOfType,
  MessageStreamEvent,
  RunStreamEvent,
  ToolUtility,
} from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

const connectionString =
  process.env["AZURE_AI_PROJECTS_CONNECTION_STRING"] || "<project connection string>";

if (!connectionString) {
  throw new Error("AZURE_AI_PROJECTS_CONNECTION_STRING must be set in the environment variables");
}

export async function main(): Promise<void> {
  const client = AIProjectsClient.fromConnectionString(
    connectionString || "",
    new DefaultAzureCredential(),
  );

  // Step 1: Create code interpreter tool
  const codeInterpreterTool = ToolUtility.createCodeInterpreterTool();

  // Step 2: Create an agent
  const agent = await client.agents.createAgent("gpt-4o-mini", {
    name: "my-agent",
    instructions: "You are a helpful agent",
    tools: [codeInterpreterTool.definition],
    toolResources: codeInterpreterTool.resources,
  });

  // Step 3: Create a thread
  const thread = await client.agents.createThread();

  // Step 4: Add a message to thread
  await client.agents.createMessage(
    thread.id, {
    role: "user",
    content: "I need to solve the equation `3x + 11 = 14`. Can you help me?",
  });

  // Intermission: message is now correlated with thread
  // Intermission: listing messages will retrieve the message just added

  // Step 5: Run the agent
  const streamEventMessages = await client.agents.createRun(thread.id, agent.id).stream();

  for await (const eventMessage of streamEventMessages) {
    switch (eventMessage.event) {
      case RunStreamEvent.ThreadRunCreated:
        break;
      case MessageStreamEvent.ThreadMessageDelta:
        {
          const messageDelta = eventMessage.data as MessageDeltaChunk;
          messageDelta.delta.content.forEach((contentPart) => {
            if (contentPart.type === "text") {
              const textContent = contentPart as MessageDeltaTextContent;
              const textValue = textContent.text?.value || "No text";
            }
          });
        }
        break;

      case RunStreamEvent.ThreadRunCompleted:
        break;
      case ErrorEvent.Error:
        console.log(`An error occurred. Data ${eventMessage.data}`);
        break;
      case DoneEvent.Done:
        break;
    }
  }

  // 6. Print the messages from the agent
  const messages = await client.agents.listMessages(thread.id);

  // Messages iterate from oldest to newest
  // messages[0] is the most recent
  for (let i = messages.data.length - 1; i >= 0; i--) {
    const m = messages.data[i];
    if (isOutputOfType<MessageTextContentOutput>(m.content[0], "text")) {
      const textContent = m.content[0] as MessageTextContentOutput;
      console.log(`${textContent.text.value}`);
      console.log(`---------------------------------`);
    }
  }

  // 7. Delete the agent once done
  await client.agents.deleteAgent(agent.id);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

출력에는 프롬프트와 답변이 포함됩니다.

I need to solve the equation `3x + 11 = 14`. Can you help me?
---------------------------------
Sure! I can help you solve the equation \(3x + 11 = 14\).

To solve this equation, we need to isolate the variable \(x\). Let's go ahead and solve it.
---------------------------------
The solution to the equation \(3x + 11 = 14\) is \(x = 1\). 

Therefore, the value of \(x\) that satisfies the equation is 1. 

Let me know if you need help with anything else!
---------------------------------

| 참조 설명서 |

필수 조건

Azure 구독 – 체험 구독을 만듭니다.
적절한 수준에서 Azure AI 개발자 RBAC 역할이 할당되었는지 확인합니다.
Azure AI Services 리소스를 사용하려면 Cognitive Services OpenAI 사용자 역할이 할당되어야 합니다.
Azure CLI 및 기계 학습 확장을 설치 합니다. CLI가 이미 설치되어 있는 경우 최신 버전으로 업데이트되었는지 확인합니다.

Azure AI Hub 및 에이전트 프로젝트 설정

다음 섹션에서는 Azure AI 에이전트 서비스를 시작하는 데 필요한 리소스를 설정하는 방법을 보여 줍니다.

앱 환경 및 Azure 리소스를 설정하는 Azure AI Hub를 만듭니다.
허브에서 Azure AI 프로젝트를 만들면 앱이 호출할 엔드포인트가 만들어지고 테넌트에서 리소스에 액세스하도록 앱 서비스를 설정합니다.
Azure OpenAI 리소스 또는 Azure AI Services 리소스 연결

기본 또는 표준 에이전트 설정 선택

기본 설정: 에이전트는 Microsoft에서 완전히 관리되는 다중 테넌트 검색 및 스토리지 리소스를 사용합니다. 이러한 기본 Azure 리소스에 대한 가시성이나 제어 권한이 없습니다.

표준 설정: 에이전트는 고객 소유의 단일 테넌트 검색 및 스토리지 리소스를 사용합니다. 이 설정을 사용하면 이러한 리소스에 대한 모든 권한과 가시성이 있지만 사용량에 따라 비용이 발생합니다.

참고 항목

다음 자동화된 bicep 템플릿을 사용하여 표준 또는 기본 에이전트를 수행할 수 있습니다. Azure AI Foundry 포털을 사용하여 기본 에이전트를 만들 수도 있습니다. Azure AI Foundry는 현재 표준 에이전트 설정을 지원하지 않습니다.

설명 및 자동 배포	다이어그램(확대하려면 클릭)
인증에 관리 ID를 사용하는 기본 에이전트 설정을 배포합니다. AI 허브, AI 프로젝트, 스토리지 계정 및 AI 서비스에 대한 리소스가 만들어집니다. AI Services 계정은 프로젝트 및 허브에 연결되고 gpt-4o-mini 모델은 eastus 지역에 배포됩니다. Microsoft 관리형 키 자격 증명 모음은 기본적으로 사용됩니다.
인증에 관리 ID를 사용하는 표준 에이전트 설정을 배포합니다. AI 허브, AI 프로젝트, 키 자격 증명 모음, 스토리지 계정, AI 서비스 및 AI Search에 대한 리소스가 만들어집니다. AI 서비스, AI Search, 키 자격 증명 모음 및 스토리지 계정은 프로젝트 및 허브에 연결됩니다. gpt-4o-mini 모델은 eastus 지역에 배포됩니다.

설명 및 자동 배포

다이어그램(확대하려면 클릭)

인증에 관리 ID를 사용하는 기본 에이전트 설정을 배포합니다. AI 허브, AI 프로젝트, 스토리지 계정 및 AI 서비스에 대한 리소스가 만들어집니다.

AI Services 계정은 프로젝트 및 허브에 연결되고 gpt-4o-mini 모델은 eastus 지역에 배포됩니다. Microsoft 관리형 키 자격 증명 모음은 기본적으로 사용됩니다.

인증에 관리 ID를 사용하는 표준 에이전트 설정을 배포합니다.

AI 허브, AI 프로젝트, 키 자격 증명 모음, 스토리지 계정, AI 서비스 및 AI Search에 대한 리소스가 만들어집니다.

AI 서비스, AI Search, 키 자격 증명 모음 및 스토리지 계정은 프로젝트 및 허브에 연결됩니다. gpt-4o-mini 모델은 eastus 지역에 배포됩니다.

[선택 사항] 자동 배포 템플릿의 모델 선택

자동 배포 템플릿에서 모델 매개 변수를 편집하여 에이전트에서 사용하는 모델을 사용자 지정할 수 있습니다. 다른 모델을 배포하려면 최소한 및 modelVersion 매개 변수를 modelName 업데이트해야 합니다.

기본적으로 배포 템플릿은 다음 값으로 구성됩니다.

모델 매개 변수	기본값
modelName	gpt-4o-mini
modelFormat	OpenAI(Azure OpenAI의 경우)
모델 버전	2024-07-18
modelSkuName	GlobalStandard
modelLocation	eastus

Important

modelFormat 매개 변수를 변경하지 마세요.

템플릿은 Azure OpenAI 모델의 배포만 지원합니다. Azure AI 에이전트 서비스 모델 지원 설명서에서 지원되는 Azure OpenAI 모델을 확인합니다.

[선택 사항] 에이전트를 설정하는 동안 사용자 고유의 리소스 사용

참고 항목

기존 AI 서비스 또는 Azure OpenAI 리소스를 사용하는 경우 모델이 배포되지 않습니다. 에이전트 설정이 완료된 후 리소스에 모델을 배포할 수 있습니다.

매개 변수 파일에 전체 arm 리소스 ID를 제공하여 기존 AI 서비스, Azure OpenAI, AI Search 및/또는 Azure Blob Storage 리소스를 사용합니다.

aiServiceAccountResourceId
aiSearchServiceResourceId
aiStorageAccountResourceId

기존 Azure OpenAI 리소스를 사용하려면 매개 변수 파일의 aiServiceAccountResourceId 매개 변수와 매개 변수를 aiServiceKind 업데이트해야 합니다. 매개 변수는 aiServiceKind .로 AzureOpenAI설정해야 합니다.

자세한 내용은 사용자 고유의 리소스를 사용하는 방법을 참조 하세요.

에이전트 구성 및 실행

구성 요소	설명
에이전트	도구와 함께 AI 모델을 사용하는 사용자 지정 AI입니다.
도구	도구를 사용하면 대화 중에 안정적이고 정확하게 응답할 수 있는 에이전트의 기능을 확장할 수 있습니다. 예를 들어 모델을 접지하기 위해 사용자 정의 기술 자료 연결하거나 웹 검색을 사용하여 현재 정보를 제공할 수 있습니다.
스레드	에이전트와 사용자 간의 대화 세션입니다. 스레드는 메시지를 저장하고 자동으로 잘림을 처리하여 콘텐츠를 모델의 컨텍스트에 맞춥니다.
메시지	에이전트 또는 사용자가 만든 메시지입니다. 메시지에는 텍스트, 이미지 및 기타 파일이 포함될 수 있습니다. 메시지는 스레드에 목록으로 저장됩니다.
Run	스레드의 내용에 따라 실행을 시작할 에이전트의 활성화입니다. 에이전트는 해당 구성 및 스레드의 메시지를 사용하여 모델 및 도구를 호출하여 작업을 수행합니다. 실행의 일부로 에이전트는 스레드에 메시지를 추가합니다.
실행 단계	에이전트가 실행의 일부로 수행한 단계의 자세한 목록입니다. 에이전트는 실행하는 동안 도구를 호출하거나 메시지를 만들 수 있습니다. 실행 단계를 검사하면 에이전트가 결과를 얻는 방법을 이해할 수 있습니다.

API 요청을 인증하려면 az login 명령을 사용하여 Azure 구독에 로그인합니다.

az login

다음으로, API 호출에 대한 권한 부여로 제공하려면 Entra ID 토큰을 가져와야 합니다. CLI 명령을 사용하여 토큰을 가져옵니다.

az account get-access-token --resource 'https://ml.azure.com/' | jq -r .accessToken | tr -d '"'

액세스 토큰을 명명 AZURE_AI_AGENTS_TOKEN된 환경 변수로 설정합니다.

Azure AI Agents Service에 대한 REST API 호출을 성공적으로 수행하려면 아래와 같이 엔드포인트를 사용해야 합니다.

https://<HostName>/agents/v1.0/subscriptions/<AzureSubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.MachineLearningServices/workspaces/<ProjectName>

HostName 은 (을) 탐색하고 discovery_url 선행 https:// 및 후행을 제거하여 찾을 수 있습니다 /discovery. 찾으려면 다음 CLI 명령을 실행합니다 discovery_url.

az ml workspace show -n {project_name} --subscription {subscription_name} --resource-group {resource_group_name} --query discovery_url

예를 들어 엔드포인트는 다음과 같이 표시할 수 있습니다.

https://eastus.api.azureml.ms/agents/v1.0/subscriptions/12345678-abcd-1234-abcd-123456789000/resourceGroups/my-resource-group/providers/Microsoft.MachineLearningServices/workspaces/my-project-name

이 엔드포인트를 명명 AZURE_AI_AGENTS_ENDPOINT된 환경 변수로 설정합니다.

에이전트 만들기

참고 항목

Azure AI Agents Service를 사용하려면 매개 변수에 model 모델 배포 이름이 필요합니다. 모델 배포 이름이 기본 모델 이름과 다른 경우 코드를 "model": "{your-custom-model-deployment-name}"(으)로 조정합니다.

curl $AZURE_AI_AGENTS_ENDPOINT/assistants?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "You are a helpful agent.",
    "name": "my-agent",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4o-mini"
  }'

스레드 만들기

curl $AZURE_AI_AGENTS_ENDPOINT/threads?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d ''

스레드에 사용자 질문 추가

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/messages?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
      "role": "user",
      "content": "I need to solve the equation `3x + 11 = 14`. Can you help me?"
    }'

스레드 실행

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/runs?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "assistant_id": "asst_abc123",
  }'

실행 상태 검색

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/runs/run_abc123?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN"

에이전트 응답 검색

curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/messages?api-version=2024-12-01-preview \
  -H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN"

다음을 통해 공유

빠른 시작: 새 에이전트 만들기(미리 보기)

필수 조건

기본 에이전트 설정 지원

Azure AI Foundry 포털에서 허브 및 프로젝트 만들기

모델 배포

에이전트 플레이그라운드 사용

참고 항목

필수 조건

Azure AI Hub 및 에이전트 프로젝트 설정

기본 또는 표준 에이전트 설정 선택

[선택 사항] 자동 배포 템플릿의 모델 선택

[선택 사항] 에이전트를 설정하는 동안 사용자 고유의 리소스 사용

에이전트 구성 및 실행

필수 조건

Azure AI Hub 및 에이전트 프로젝트 설정

기본 또는 표준 에이전트 설정 선택

[선택 사항] 자동 배포 템플릿의 모델 선택

[선택 사항] 에이전트를 설정하는 동안 사용자 고유의 리소스 사용

에이전트 구성 및 실행

필수 조건

Azure AI Hub 및 에이전트 프로젝트 설정

기본 또는 표준 에이전트 설정 선택

[선택 사항] 자동 배포 템플릿의 모델 선택

[선택 사항] 에이전트를 설정하는 동안 사용자 고유의 리소스 사용

에이전트 구성 및 실행

필수 조건

Azure AI Hub 및 에이전트 프로젝트 설정

기본 또는 표준 에이전트 설정 선택

[선택 사항] 자동 배포 템플릿의 모델 선택

[선택 사항] 에이전트를 설정하는 동안 사용자 고유의 리소스 사용

에이전트 구성 및 실행

필수 조건

Azure AI Hub 및 에이전트 프로젝트 설정

기본 또는 표준 에이전트 설정 선택

[선택 사항] 자동 배포 템플릿의 모델 선택

[선택 사항] 에이전트를 설정하는 동안 사용자 고유의 리소스 사용

에이전트 구성 및 실행

필수 조건

Azure AI Hub 및 에이전트 프로젝트 설정

기본 또는 표준 에이전트 설정 선택

[선택 사항] 자동 배포 템플릿의 모델 선택

[선택 사항] 에이전트를 설정하는 동안 사용자 고유의 리소스 사용

에이전트 구성 및 실행

에이전트 만들기

스레드 만들기

스레드에 사용자 질문 추가

스레드 실행

실행 상태 검색

에이전트 응답 검색

피드백

추가 리소스