사용자 지정 에이전트 등록 및 관리

Microsoft Foundry 컨트롤 플레인은 다양한 플랫폼 및 인프라에서 실행되는 에이전트에 대한 중앙 집중식 관리 및 관찰성을 제공합니다. Azure 컴퓨팅 서비스 또는 기타 클라우드 환경에서 실행되는 사용자 지정 에이전트를 등록하여 작업에 대한 가시성을 확보하고 동작을 제어할 수 있습니다.

이 문서에서는 Foundry 컨트롤 플레인에 사용자 지정 에이전트를 등록하는 방법을 보여줍니다. 등록을 위해 에이전트를 구성하고, 원격 분석 수집을 설정하고, 컨트롤 플레인의 관리 기능을 사용하는 방법을 알아봅니다.

필수 조건

시작하기 전에 다음을 갖고 있는지 확인하십시오.

• 활성 구독이 있는 Azure 계정. 계정이 없는 경우 평가판 구독을 포함하는 무료 Azure 계정을 만듭니다.

• Foundry 프로젝트입니다. 없으면 프로젝트를 만듭니다.

• Foundry는 Azure API Management를 사용하여 에이전트를 API로 등록합니다. Foundry 리소스에서 AI 게이트웨이를 구성합니다.

• 연결할 수 있는 엔드포인트(Foundry 리소스를 배포하는 네트워크에서 연결할 수 있는 공용 엔드포인트 또는 엔드포인트)를 통해 배포하고 노출하는 에이전트입니다.

사용자 지정 에이전트 추가

컨트롤 플레인에서 사용자 지정 에이전트를 등록할 수 있습니다. 플랫폼 및 인프라 솔루션 모두에서 선택한 기술로 에이전트를 개발합니다.

사용자 지정 에이전트를 등록할 때 Foundry는 Azure API Management를 사용하여 에이전트에 대한 통신의 프록시 역할을 하므로 액세스를 제어하고 활동을 모니터링할 수 있습니다.

사용자 지정 에이전트를 등록할 때 결과 아키텍처는 다음과 같습니다.

에이전트 확인

에이전트가 등록 요구 사항을 충족하는지 확인합니다.

Foundry 프로젝트 준비

사용자 지정 에이전트가 Foundry 프로젝트에 추가됩니다. 에이전트를 등록하기 전에 프로젝트를 올바르게 구성했는지 확인합니다.

1. Microsoft Foundry에 로그인합니다. New Foundry 토글이 설정되었는지 확인합니다. 이러한 단계는 Foundry(신규)를 참조합니다.

   

2. 프로젝트에서 AI 게이트웨이가 구성되었는지 확인합니다.

   1. 작동>관리 콘솔을 선택합니다.

   2. AI 게이트웨이 탭을 엽니다.

   3. 페이지에는 Foundry 리소스에 구성되고 매핑된 모든 AI 게이트웨이가 나열됩니다. 사용하려는 Foundry 리소스에 AI 게이트웨이가 연결되어 있는지 확인합니다.

      

   4. 사용하려는 Foundry 리소스에 AI 게이트웨이가 구성되어 있지 않은 경우(나열되지 않음) AI 게이트웨이 추가 옵션을 사용하여 추가합니다. AI 게이트웨이는 에이전트, 도구 및 모델에 대한 보안, 원격 분석 및 속도 제한과 같은 강력한 거버넌스 기능을 자유롭게 설정하고 잠금을 해제할 수 있습니다.

   5. AI 게이트웨이를 구성하는 방법에 대한 자세한 내용은 AI 게이트웨이 만들기를 참조하세요.

3. 프로젝트에서 가시성을 구성해야 합니다. 컨트롤 플레인은 선택한 프로젝트와 연결된 Azure Application Insights 리소스를 사용하여 원격 분석을 내보내 에이전트를 진단하는 데 도움이 됩니다.

   1. 작동>관리 콘솔을 선택합니다.

   2. 모든 프로젝트에서 검색 상자를 사용하여 프로젝트를 찾습니다.

   3. 프로젝트를 선택합니다.

   4. 연결된 리소스 탭을 선택합니다.

   5. Application Insights 범주 아래에 연결된 리소스가 있는지 확인합니다.

      

   6. 연결된 리소스가 없는 경우 연결 추가 를 선택하여 리소스를 추가하고 Application Insights를 선택합니다.

   7. 프로젝트는 관찰 가능성 및 추적을 위해 구성됩니다.

에이전트 등록

에이전트를 등록하려면 다음 단계를 수행합니다.

1. 오른쪽 위 탐색에서 [작동 ]을 선택합니다.

2. 개요 창을 선택합니다.

3. 에이전트 등록을 선택합니다.

   

4. 등록 마법사가 나타납니다. 먼저 등록하려는 에이전트에 대한 세부 정보를 완료합니다. 다음 속성은 해당 플랫폼에서 실행되는 에이전트를 설명합니다.

   재산	Description	필수
   에이전트 URL	에이전트가 실행되고 요청을 수신하는 엔드포인트(URL)를 나타냅니다. 일반적으로 프로토콜에 따라 클라이언트에서 사용하는 기본 URL을 나타냅니다. 예를 들어, 에이전트가 OpenAI 채팅 완료 API에 대해 말할 때는 일반적으로 클라이언트가 추가하는 https://<host>/v1/ 없이 /chat/completions을 표시합니다.	Yes
   프로토콜	에이전트에서 지원하는 통신 프로토콜입니다. 일반적으로 HTTP를 사용하거나 에이전트가 보다 구체적으로 A2A를 지원하는 경우 HTTP를 지정합니다.	Yes
   A2A 에이전트 카드 URL	에이전트 카드 JSON 사양의 경로입니다. 지정하지 않으면 시스템에서 기본값 /.well-known/agent-card.json을 사용합니다.	아니오
   OpenTelemetry 에이전트 ID	OpenTelemetry 생성형 AI 의미 체계 규칙에 따라 추적을 내보내는 데 에이전트가 사용하는 에이전트 ID. 해당 작업 이름 gen_ai.agents.id을 가진 범위에서 속성 create_agent에 추적이 나타납니다. 이를 지정하지 않으면 시스템에서 에이전트 이름 값을 사용하여 이 새 에이전트가 보고하는 추적 및 로그를 찾습니다.	아니오
   관리 포털 URL	이 에이전트에 대한 추가 관리 작업을 수행할 수 있는 관리 포털 URL입니다. Foundry는 손쉬운 액세스 편의를 위해 이 값을 저장할 수 있습니다. Foundry는 이러한 관리 포털에 직접 작업을 수행할 수 있는 액세스 권한이 없습니다.	아니오

5. 그런 다음 에이전트가 컨트롤 플레인에 표시되도록 하는 방법을 구성합니다.

   재산	Description	필수
   프로젝트	에이전트를 등록하는 프로젝트입니다. Foundry는 프로젝트가 있는 리소스에 구성된 AI 게이트웨이를 사용하여 에이전트에 대한 인바운드 엔드포인트를 구성합니다. 리소스에서 AI Gateway를 사용하도록 설정된 프로젝트만 선택할 수 있습니다. 표시되지 않으면 Foundry 리소스 내에서 AI Gateway를 구성하세요. 선택한 프로젝트에서 Azure Application Insights를 구성하는 것도 좋습니다. Foundry는 프로젝트의 Azure Application Insights 리소스를 사용하여 추적 및 로그를 싱크합니다.	Yes
   에이전트 이름	Foundry에 나타나길 원하는 에이전트의 이름입니다. OpenTelemetry 에이전트 ID 필드에 다른 값을 지정하지 않으면 시스템에서 이 이름을 사용하여 Azure Application Insights에서 관련 추적 및 로그를 찾을 수도 있습니다.	Yes
   설명	이 에이전트에 대한 명확한 설명입니다.	아니오

6. 변경 내용을 저장합니다.

7. Foundry는 새 에이전트를 추가합니다. 왼쪽 창에서 자산 탭을 선택하여 에이전트 목록을 확인합니다.

8. 사용자 지정 에이전트만 표시하려면 원본 필터를 사용하고 사용자 지정을 선택합니다.

   

에이전트에 클라이언트 연결

Foundry에 에이전트를 등록하면 클라이언트에서 사용할 새 URL이 표시됩니다. Foundry는 에이전트에 대한 통신의 프록시 역할을 하므로 액세스를 제어하고 활동을 모니터링할 수 있습니다.

클라이언트가 에이전트를 호출할 새 URL을 배포하려면 다음을 수행합니다.

1. 라디오 선택기를 사용하여 사용자 지정 에이전트를 선택합니다.

2. 오른쪽의 세부 정보 패널에서 에이전트 URL 아래에서 복사 옵션을 선택합니다.

   

3. 새 URL을 사용하여 원래 엔드포인트 대신 에이전트를 호출합니다.

이 예제에서는 LangGraph 에이전트를 배포하고 클라이언트는 LangGraph SDK를 사용하여 사용합니다. 클라이언트는 새 에이전트 URL 값을 사용합니다. 이 코드는 스레드를 만들고 날씨에 대해 묻는 메시지를 보내고 응답을 다시 스트리밍합니다.

from langgraph_sdk import get_client

client = get_client(url="https://apim-my-foundry-resource.azure-api.net/my-custom-agent/") 

async def stream_run():
   thread = await client.threads.create()
   input_data = {"messages": [{"role": "human", "content": "What's the weather in LA?"}]}
   
   async for chunk in client.runs.stream(thread['thread_id'], assistant_id="your_assistant_id", input=input_data):
       print(chunk)

예상 출력: 에이전트가 메시지를 처리하고 응답을 청크로 다시 스트리밍합니다. 각 청크에는 에이전트 실행의 일부 결과가 포함되며, 여기에는 날씨 함수에 대한 도구 호출과 로스앤젤레스 날씨에 대한 최종 응답이 포함될 수 있습니다.

에이전트 차단 및 차단 해제

사용자 지정 에이전트의 경우 Foundry는 에이전트가 실행되는 기본 인프라에 액세스할 수 없으므로 시작 및 중지 작업을 사용할 수 없습니다. 그러나 Foundry는 에이전트에 들어오는 요청을 차단하여 클라이언트가 에이전트를 사용하지 못하게 할 수 있습니다. 이 기능을 사용하면 관리자가 잘못 동작하는 경우 에이전트를 사용하지 않도록 설정할 수 있습니다.

에이전트에 들어오는 요청을 차단하려면 다음을 수행합니다.

1. 오른쪽 위 탐색에서 [작동 ]을 선택합니다.

2. 왼쪽 창에서 자산을 선택합니다.

3. 차단하려는 에이전트를 선택합니다. 정보 패널이 나타납니다.

4. 업데이트 상태를 선택한 다음 차단을 선택합니다.

   

5. 작업을 확인합니다.

에이전트를 차단하면 Foundry의 에이전트 상태가차단됨으로 표시됩니다. 차단된 상태의 에이전트는 연결된 인프라에서 실행되지만 들어오는 요청을 받을 수는 없습니다. Foundry는 에이전트와 인터페이스하려는 모든 시도를 차단합니다.

에이전트 차단을 해제하려면 다음을 수행합니다.

1. 업데이트 상태를 선택한 다음 차단 해제를 선택합니다.

2. 작업을 확인합니다.

에이전트의 원격 분석 활성화

Foundry는 OpenTelemetry 개방형 표준을 사용하여 에이전트가 수행하는 작업을 이해합니다. 프로젝트에 Azure Application Insights가 구성된 경우 Foundry는 기본적으로 요청을 Azure Application Insights에 기록합니다. 이 원격 분석은 다음을 계산하는 데도 사용됩니다.

• Runs
• 오류율
• 사용량(사용 가능한 경우)

최고 수준의 충실도를 얻기 위해 Foundry는 사용자 지정 에이전트가 OpenTelemetry 표준의 생성 AI 솔루션에 대한 의미 체계 규칙을 준수해야 합니다.

실행 및 추적 보기

Foundry로 전송된 추적 및 로그를 볼 수 있습니다. 이 내용을 확인하려면 다음을 수행하십시오.

1. 오른쪽 위 탐색에서 [작동 ]을 선택합니다.

2. 왼쪽 창에서 자산을 선택합니다.

3. 에이전트를 선택합니다.

4. 추적 섹션이 표시됩니다.

5. 에이전트의 엔드포인트에 대한 각 HTTP 호출에 대해 하나의 항목이 표시됩니다.

6. 세부 정보를 보려면 항목을 선택합니다.

   

   팁 (조언)

   이 예제에서는 클라이언트가 새 에이전트의 엔드포인트를 사용하여 에이전트와 통신하는 방법을 확인할 수 있습니다. 이 예제에서는 LangChain의 에이전트 프로토콜과 함께 제공되는 에이전트를 보여줍니다. 클라이언트는 경로를 /runs/stream사용합니다.

7. 이 예제에서는 HTTP 게시물 외에 추가 세부 정보가 추적에 없음을 확인합니다. 에이전트의 코드에 추가된 계측이 더 이상 없기 때문입니다. 코드를 계측하고 도구 호출, LLM 호출 등과 같은 추가 세부 정보를 얻는 방법을 알아보려면 다음 섹션을 참조하세요.

사용자 지정 코드 에이전트 계측

사용자 지정 코드를 사용하여 에이전트를 빌드하는 경우 OpenTelemetry 표준에 따라 추적을 내보내고 Azure Application Insights에 싱크하는 솔루션을 계측해야 합니다. 계측을 통해 Foundry는 에이전트가 수행하는 일에 대해 더 높은 수준의 세부 정보를 액세스할 수 있습니다.

계측 키를 사용하여 프로젝트의 Azure Application Insights 리소스에 추적을 보냅니다. 프로젝트와 연결된 계측 키를 얻으려면 프로젝트에서 추적 사용의 지침을 따릅니다.

이 예제에서는 OpenTelemetry 표준에서 추적을 내보내도록 LangGraph로 개발된 에이전트를 구성합니다. 추적 프로그램은 도구 호출 및 모델 상호 작용을 포함한 모든 에이전트 작업을 캡처하고 모니터링을 위해 Azure Application Insights로 보냅니다.

이 코드는 langchain-azure-ai 패키지를 사용합니다. 언어 API 및 SDK에서 솔루션에 사용되는 프로그래밍 언어 및 프레임워크에 따라 OpenTelemetry를 사용하여 특정 솔루션을 계측하는 방법을 알아봅니다.

pip install -U langchain-azure-ai[opentelemetry]

그런 다음 에이전트를 계측합니다.

from langchain.agents import create_agent
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

application_insights_connection_string = 'InstrumentationKey="12345678...'

tracer = AzureAIOpenTelemetryTracer(
    connection_string=application_insights_connection_string,
    enable_content_recording=True,
)

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

agent = create_agent(
    model="openai:gpt-5.1",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
).with_config({ "callbacks": [tracer] })

예상 출력: 에이전트는 OpenTelemetry 추적을 Azure Application Insights에 자동으로 내보내는 동안 정상적으로 실행됩니다. 추적에는 작업 이름, 기간, 모델 호출, 도구 호출 및 토큰 사용량이 포함됩니다. 추적 섹션 아래의 Foundry 포털에서 이러한 추적을 볼 수 있습니다.

계측 플랫폼 솔루션

에이전트가 OpenTelemetry를 지원하지만 Azure Application Insights를 지원하지 않는 플랫폼 솔루션에서 실행되는 경우 OpenTelemetry Collector를 배포하고 OTLP 데이터를 Collector(표준 OpenTelemetry 구성)로 보내도록 소프트웨어를 구성해야 합니다.

연결 문자열을 사용하여 Azure Monitor 내보내기 도구 기능으로 수집기를 구성하여 Application Insights로 데이터를 전달합니다. 구현 방법에 대한 자세한 내용은 Azure Monitor OpenTelemetry 구성을 참조하세요.

추적 문제 해결

추적이 표시되지 않으면 다음을 확인합니다.

관련 콘텐츠

• Microsoft Foundry 컨트롤 플레인이란?
• 플릿 전체에서 에이전트 모니터링
• 에이전트 플릿 전체에서 비용 및 성능 최적화