빠른 시작: 호스트된 에이전트로 사용자 고유의 코드 배포

첫 번째 호스팅 에이전트 배포에서 샘플을 배포했습니다. 이 빠른 시작에서는 자체 Python 또는 .NET(C#) 에이전트 코드를 Foundry 에이전트 서비스에 배포합니다. 코드는 Microsoft 에이전트 프레임워크, LangGraph, GitHub Copilot SDK 또는 OpenAI 에이전트 SDK와 같은 모든 에이전트 프레임워크 또는 모델을 직접 호출하는 일반 코드를 사용할 수 있습니다.

각 코드 단계에는 언어 및 프로토콜에 대한 탭이 있습니다. 모든 단계에서 C#(응답)과 같은 동일한 조합을 선택합니다.

GitHub Copilot 같은 코딩 에이전트를 사용하는 경우 Microsoft Foundry Skill은 빠른 시작을 사용자 고유의 코드베이스에 맞게 조정하고 올바른 azd 배포 단계를 실행하는 데 도움이 될 수 있습니다.

사전 요구 사항

이 작업을 시작하려면 다음이 필요합니다.

Azure 구독--무료로 하나 만들기.
기존 Foundry 프로젝트가 있는 경우 프로젝트 범위에 Foundry Project Manager이(가) 필요합니다. 새 Foundry 프로젝트를 만들어야 하는 경우 리소스 그룹 범위에서 역할이 필요합니다 Owner . 전체 역할 매트릭스는 호스트된 에이전트 권한 참조를 참조하세요.
Azure 개발자 CLI(azd) 1.27.1 이상.
azd microsoft.foundry 해당 확장:
```
azd ext install microsoft.foundry
```
인증된 azd 세션:
```
azd auth login
```
로컬 디렉터리의 기존 에이전트 코드입니다.
Python 경로의 경우 Python 3.13 이상.
C# 경로의 경우 .NET 10 SDK 이상입니다.
(선택 사항) Visual Studio Code 샘플에서 시작하려면 Visual Studio Code 및 Visual Studio Code Microsoft Foundry 도구 키트를 설치합니다.

프로젝트 디렉터리에는 Python의 경우 최소한 다음이 포함되어 있어야 합니다:

my-agent/
├── main.py              # Your agent entry point
└── requirements.txt     # Python dependencies

또는 C#의 경우 .NET 웹 프로젝트:

my-agent/
├── Program.cs           # Your agent entry point
└── my-agent.csproj      # Project file (web SDK)

프레임워크 선택

1단계에서 추가하는 호스팅 라이브러리는 프로토콜(HTTP 서버, 상태 검사, 요청 및 응답 스키마)을 처리합니다. 특정 에이전트 프레임워크에 종속되지 않으므로 에이전트 논리는 Python 또는 C#에서 원하는 패키지를 사용할 수 있습니다.

프레임워크를 사용하려면 호스팅 라이브러리 옆에 해당 패키지를 추가한 다음 처리기에서 프레임워크를 호출합니다. 다음 표에는 공통 선택 항목과 각각에 대한 Python 샘플이 나와 있습니다.

Framework	`requirements.txt`에 추가할 패키지	Sample
일반 Python(모델 직접 호출)	`azure-ai-projects`	hello-world
LangGraph	`langgraph`, `langchain-azure-ai`	langgraph-chat
GitHub Copilot SDK	`github-copilot-sdk`	github-copilot
OpenAI 에이전트 SDK	`openai-agents`	openai-agents-sdk

각 샘플에는 requirements.txt 정확한 패키지 버전이 나열됩니다. 사용자 고유의 샘플 가져오기의 전체 집합은 Python 샘플 폴더를 참조하세요.

C#의 경우 호스팅 패키지 옆에 있는 프로젝트 파일에 프레임워크 패키지를 추가한 다음, 처리기 Program.cs에서 프레임워크를 호출합니다. 전체 C# 예제 집합은 C# 사용자 고유의 샘플 폴더를 참조하세요.

참고

Microsoft Agent Framework에는 자체 패키지를 사용하는 기본 제공 호스팅 통합이 있습니다. Microsoft 에이전트 프레임워크 에이전트를 배포하려면 첫 번째 호스트된 에이전트 배포를 참조하세요.

Visual Studio Code 샘플에서 시작

고유한 코드 대신 작업 프레임워크 템플릿에서 시작하려면 Microsoft Foundry Toolkit for Visual Studio Code 샘플 갤러리를 사용합니다.

Visual Studio Code 작업 모음에서 파운드리 도구 키트 아이콘을 선택합니다.
개발자 도구>에이전트 개발 도구에서 에이전트 만들기를 선택합니다.
모든 권한이 있는 코드에서 만들기 아래에서 샘플 사용을 선택합니다.
샘플에서 호스트된 에이전트 만들기에서 필터를 사용하여 갤러리의 범위를 좁힐 수 있습니다.
- 프레임워크의 경우 에이전트 프레임워크, Bring Your Own, LangGraph 또는 Copilot SDK를 선택합니다.
- 프로토콜 형식의 경우 응답 API 또는 호출 API를 선택합니다.
샘플을 선택한 다음, 다음을 선택합니다.
에이전트 이름을 입력하고 Foundry 프로젝트를 선택한 다음 만들기를 선택합니다.

도구 키트는 샘플을 새 작업 영역으로 스캐폴드하고 원클릭 F5 디버그 환경을 설정합니다. 종속성을 설치하고, 로컬로 테스트하고, Visual Studio Code 배포하려면 첫 번째 호스팅 에이전트 배포의 Visual Studio Code 단계를 수행합니다.

프로토콜 선택

각 코드 단계에는 언어와 프로토콜의 모든 조합에 대한 탭이 있습니다. 응답 은 대화 기록을 관리하며 OpenAI와 호환됩니다. 호출을 사용하면 요청 및 응답 스키마를 완전히 제어할 수 있습니다. 모든 단계에서 동일한 언어 및 프로토콜 조합을 선택합니다.

Tip

어떤 프로토콜을 사용해야 할지 잘 모르겠습니까? 응답으로 시작 합니다.

1단계: 호스팅 라이브러리 추가

프로토콜 라이브러리를 프로젝트에 추가합니다. 라이브러리는 사용하는 에이전트 프레임워크와 관계없이 HTTP 서버, 상태 검사 및 프로토콜 준수를 처리합니다. 프레임워크를 사용하는 경우 호스팅 라이브러리와 함께 해당 패키지를 추가합니다. 프레임워크 선택을 참조하세요.

프로토콜 라이브러리를 requirements.txt에 추가하세요:

azure-ai-agentserver-responses>=1.0.0b7

프로토콜 라이브러리를 requirements.txt에 추가하세요:

azure-ai-agentserver-invocations>=1.0.0b5

.NET 웹 프로젝트를 만들고 프로토콜 패키지를 추가합니다.

dotnet new web --name my-agent
cd my-agent
dotnet add package Azure.AI.AgentServer.Responses --prerelease

.NET 웹 프로젝트를 만들고 프로토콜 패키지를 추가합니다.

dotnet new web --name my-agent
cd my-agent
dotnet add package Azure.AI.AgentServer.Invocations --prerelease

2단계: 호스팅 래퍼 추가

호스팅 래퍼를 사용하여 에이전트 진입점을 만들거나 업데이트합니다. 다음 예제에서는 최소 패턴을 보여 줍니다. 표시된 블록을 기존 에이전트 논리로 바꿉다.

생성 또는 업데이트 main.py:

import asyncio
from azure.ai.agentserver.responses import (
    CreateResponse,
    ResponseContext,
    ResponsesAgentServerHost,
    TextResponse,
)

app = ResponsesAgentServerHost()


@app.response_handler
async def handler(
    request: CreateResponse,
    context: ResponseContext,
    _cancellation_signal: asyncio.Event,
):
    user_input = await context.get_input_text() or ""

    # ─── YOUR AGENT LOGIC HERE ───
    reply = f"Hello! You said: {user_input}"
    # ─────────────────────────────

    return TextResponse(context, request, text=reply)


app.run()

생성 또는 업데이트 main.py:

import json
from starlette.requests import Request
from starlette.responses import JSONResponse
from azure.ai.agentserver.invocations import InvocationAgentServerHost

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle_invoke(request: Request):
    raw = (await request.body()).decode("utf-8").strip()
    try:
        body = json.loads(raw)
        user_message = (
            body.get("message") or body.get("input") or raw
        )
    except json.JSONDecodeError:
        user_message = raw

    # ─── YOUR AGENT LOGIC HERE ───
    reply = f"Hello! You said: {user_message}"
    # ─────────────────────────────

    return JSONResponse({"reply": reply})


if __name__ == "__main__":
    app.run()

Program.cs를 바꿉니다:

using Azure.AI.AgentServer.Responses;
using Azure.AI.AgentServer.Responses.Models;

ResponsesServer.Run<EchoHandler>();

public sealed class EchoHandler : ResponseHandler
{
    public override IAsyncEnumerable<ResponseStreamEvent> CreateAsync(
        CreateResponse request,
        ResponseContext context,
        CancellationToken cancellationToken)
    {
        return new TextResponse(context, request, createText: async ct =>
        {
            var userInput = await context.GetInputTextAsync(cancellationToken: ct) ?? "";

            // ─── YOUR AGENT LOGIC HERE ───
            var reply = $"Hello! You said: {userInput}";
            // ──────────────────────────────

            return reply;
        });
    }
}

Program.cs를 바꿉니다:

using System.Text.Json;
using Azure.AI.AgentServer.Invocations;
using Microsoft.AspNetCore.Http;

InvocationsServer.Run<EchoHandler>();

public sealed class EchoHandler : InvocationHandler
{
    public override async Task HandleAsync(
        HttpRequest request,
        HttpResponse response,
        InvocationContext context,
        CancellationToken cancellationToken)
    {
        var raw = (await new StreamReader(request.Body).ReadToEndAsync(cancellationToken)).Trim();

        string userMessage;
        try
        {
            var body = JsonDocument.Parse(raw).RootElement;
            userMessage =
                (body.TryGetProperty("message", out var m) ? m.GetString() : null)
                ?? (body.TryGetProperty("input", out var input) ? input.GetString() : null)
                ?? raw;
        }
        catch (JsonException)
        {
            userMessage = raw;
        }

        // ─── YOUR AGENT LOGIC HERE ───
        var reply = $"Hello! You said: {userMessage}";
        // ──────────────────────────────

        await response.WriteAsJsonAsync(new { reply }, cancellationToken);
    }
}

참고

다음 예제는 호스팅 래퍼를 시연하기 위해 사용자 입력을 그대로 출력합니다. 표시된 블록을 사용자 고유의 에이전트 논리(모델 호출, RAG 또는 LangGraph 또는 GitHub Copilot SDK와 같은 프레임워크)로 대체합니다. 전체 예제는 Python 샘플 및 C# 샘플을 참조하세요.

3단계: 프로젝트 초기화

에이전트 소스 디렉터리에서 azd ai agent init를 실행하세요. Azure 개발자 CLI는 프로젝트 파일에서 언어를 검색합니다.

azd ai agent init --protocol responses --deploy-mode code

azd ai agent init --protocol invocations --deploy-mode code

azd ai agent init --protocol responses --deploy-mode code

azd ai agent init --protocol invocations --deploy-mode code

대화형 흐름은 다음을 입력하라는 메시지를 표시합니다.

에이전트 이름: 이름을 사용자 지정하거나 기본값을 적용합니다.
Foundry Project: 기존 Foundry project 사용 또는 새 Foundry project 만들기를 선택합니다.
구독: Azure 구독을 선택합니다.
위치: Azure 지역을 선택합니다.

완료되면 다음이 표시됩니다. AI 에이전트 정의가 azd 프로젝트에 성공적으로 추가되었습니다.

4단계: Azure 리소스 프로비전

azd provision

그러면 Application Insights와 같은 필요한 Azure 리소스가 만들어집니다.

5단계: 에이전트를 로컬로 테스트

azd ai agent run

이 명령은 가상 환경(Python)을 만들거나 프로젝트(C#)를 복원 및 빌드하고, 종속성을 설치하고, 에이전트를 시작합니다. 또한 에이전트와 채팅할 수 있도록 브라우저에서 에이전트 검사기를 엽니다.

별도의 터미널에서 CLI에서 호출할 수도 있습니다.

azd ai agent invoke --local "Hello from my hosted agent"

6단계: Foundry 에이전트 서비스에 배포

azd deploy

명령이 완료되면 출력에 에이전트 플레이그라운드 및 에이전트 엔드포인트에 대한 링크가 표시됩니다.

Deploying services (azd deploy)

  Done: Deploying service my-agent
  - Agent playground (portal): https://ai.azure.com/.../build/agents/my-agent/build?version=1
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/my-agent/versions/1

7단계: 배포된 에이전트 호출

azd ai agent invoke "Hello from my hosted agent"

몇 초 내에 응답이 표시됩니다.

자원을 정리하세요

Warning

현재 azd 환경에서 Foundry 프로젝트를 만든 경우 프로젝트의 azd down 리소스 그룹 및 해당 프로젝트의 모든 항목을 영구적으로 삭제합니다. 초기화 중에 기존 프로젝트를 선택한 경우 프로젝트, azd down 해당 리소스 그룹, 호스트된 에이전트 및 기타 빠른 시작 리소스를 제자리에 둡니다. 기존 프로젝트에서 더 이상 필요하지 않은 리소스를 별도로 삭제합니다.

azd down

Troubleshooting

Issue	해결 방법
`ModuleNotFoundError: azure.ai.agentserver`	프로토콜 라이브러리가 `requirements.txt`에 있는지 확인하고 `pip install -r requirements.txt`을(를) 다시 설치하세요.
C#: `The type or namespace name 'AgentServer' could not be found`	프로토콜 패키지가 참조되는지(`dotnet add package Azure.AI.AgentServer.Responses --prerelease` 또는 `Azure.AI.AgentServer.Invocations`) 프로젝트에서 웹 SDK(`dotnet new web`)를 사용하는지 확인합니다.
C#: `dotnet run`에서의 `Cannot resolve scoped service ... Handler from root provider`	기본 `dotnet new web` 시작 프로필은 `ASPNETCORE_ENVIRONMENT=Development`을 설정하며, 이로 인해 엄격한 범위 유효성 검사가 사용됩니다. 테스트하려면 `dotnet run`를 사용하세요(호스팅 모드에서 실행됨). 또는 `azd ai agent run` 전에 `ASPNETCORE_ENVIRONMENT=Production`을 설정하세요.
`FOUNDRY_PROJECT_ENDPOINT not set`	앱을 직접 실행하는 대신 `azd ai agent run`를 사용하세요(자동으로 설정해 줍니다). 또는 이를 `.env` 파일에 추가하세요.
`Connection refused` 로컬 실행 시	포트 8088을 사용하는 다른 프로세스가 없는지 확인합니다.
`AuthorizationFailed` 배포 중	프로젝트 수준에서 `Foundry Project Manager`이 필요합니다.
에이전트가 `provisioning`에 멈춤	실행 `azd ai agent show` 하여 상태를 확인합니다. 첫 번째 배포는 종속성이 설치되는 동안 2~3분이 걸릴 수 있습니다.
`azd ai agent init` 실패	실행 `azd version` 하여 1.27.1 이상을 확인합니다. 1.0.0-beta.4 이상인지 확인하려면 `azd ext show azure.ai.agents`를 실행합니다. `azd ext upgrade azure.ai.agents`로 업그레이드하세요.

전체 권한 및 역할 할당 매트릭스는 호스트된 에이전트 권한 참조를 참조하세요.

배운 내용

이 빠른 시작에서 당신은 다음을 수행합니다.

기존 에이전트 코드에 하나의 호스팅 라이브러리가 추가되었습니다.
소스 디렉터리에서 azd 프로젝트를 초기화했습니다.
azd ai agent run 및 azd ai agent invoke --local에서 로컬로 테스트되었습니다.
azd deploy를 사용하여 Foundry 에이전트 서비스에 배포되었습니다.

다음 단계

호스트된 에이전트 수명 주기 관리

도구 상자를 빌드하고 호스트된 에이전트와 함께 사용하여 하나의 관리형 엔드포인트 뒤에 도구를 결합합니다.

피드백

이 페이지가 도움이 되었나요?

2026-09-11 에 마지막으로 업데이트됨