만약 .NET 개발자로서 AI 엔지니어링 분야에 진출하고 싶다면, 에이전트가 가장 좋은 시작점입니다. 에이전트는 단순히 'LLM API 호출'을 넘어 '추론하고, 도구를 사용하며, 행동하는 시스템을 구축하는 지점'이며, Azure AI Foundry Agent Service와 .NET을 결합하면 놀라울 정도로 접근하기 쉽습니다.

본 포스트에서는 Azure 측 설정부터 실제 C# 코드까지 첫 에이전트를 엔드투엔드로 구축하는 방법을 자세히 안내하고, 전체 과정을 영상으로도 공유합니다.

🎥 전체 실습 영상은 여기에서 시청하세요: [

에이전트가 필요한 이유, 그리고 지금 필요한 이유

우리 대부분은 간단한 채팅 완성 호출(chat completion call)로 AI 여정을 시작했습니다. 프롬프트를 보내고 텍스트를 받는 식이죠. 이는 Q&A에는 적합하지만, 모델에게 무언가를 _수행_해야 할 때—코드를 실행하거나, 문서를 검색하거나, API를 호출하거나, 실제 상태(state)를 가진 다중 턴 대화를 유지해야 할 때—는 한계가 드러납니다.

이것이 바로 Foundry Agent Service가 해결하는 간극입니다. Foundry의 에이전트는 다음과 같습니다:

• 내구성(Durable) — 애플리케이션 메모리가 아닌, Foundry 프로젝트 내의 리소스로 존재합니다.
• 도구 인식(Tool-aware) — 내장된 도구(예: 코드 인터프리터)나 사용자가 정의한 사용자 지정 함수를 호출할 수 있습니다.
• 상태 유지(Stateful) — 대화가 지속되며 턴을 거치며 컨텍스트를 유지합니다.

그리고 .NET 개발자에게 가장 좋은 점은, 전체 과정이 깔끔하고 타입이 지정된 C#에서 호출 가능하다는 것입니다. 원시 REST 페이로드와 씨름할 필요가 없습니다.

준비물

코드를 작성하기 전에 Azure 측 설정을 완료해야 합니다:

1. 채팅 모델(예: gpt-4o-mini)을 배포한 Azure AI Foundry 프로젝트
2. Foundry User RBAC 역할을 리소스/리소스 그룹 범위에서 계정에 할당해야 합니다. 이것은 사람들이 가장 흔하게 겪는 장애물입니다 (SDK 호출 시 발생하는 조용한 403 오류) 따라서 건너뛰지 마세요.
3. 로컬에서 **az login**을 실행하여, 코드가 키를 하드코딩하지 않고 인증할 수 있도록 합니다.

이전에 Cognitive Services 역할을 다뤄본 적이 있다면, 에이전트 관리가 이 별도의 Foundry 전용 역할이 필요하다는 점에 유의하세요. 이는 일반적인 Azure OpenAI 사용 경험을 가진 많은 분들이 놓치기 쉬운 부분입니다.

.NET 프로젝트 설정

dotnet new console -n FoundryAgentLab -f net10.0
cd FoundryAgentLab
dotnet add package Azure.AI.Projects
...

환경 변수를 설정하세요:

export PROJECT_ENDPOINT="https://<your-resource>.services.ai.azure.com/api/projects/<your-project>"
export MODEL_DEPLOYMENT_NAME="gpt-4o-mini"
export AGENT_NAME="my-dotnet-agent"

에이전트 생성

using Azure.AI.Projects;
using Azure.AI.Projects.OpenAI;
using Azure.Identity;
...

여기서 주목할 몇 가지 사항이 있습니다:

• **AIProjectClient**는 프로젝트로 들어가는 단일 진입점입니다. 에이전트, 대화(conversations), 응답(responses) 모두 이 클라이언트와 연결됩니다.
• **PromptAgentDefinition**은 선언적(declarative) 에이전트입니다. 모델과 지침을 설명하면 Foundry가 실행 메커니즘을 처리합니다.
• 에이전트에 **버전(version)**이 있다는 점에 주목하세요. 업데이트할 때마다 Foundry는 버전 기록을 유지하므로, 프롬프트를 반복적으로 개선하며 이전 상태로 되돌리고 싶을 때 유용합니다.

에이전트와 대화하기

에이전트 생성은 절반의 과정입니다. 이제 컨텍스트를 여러 턴(turns)에 걸쳐 유지하면서 실제 대화를 나눠보겠습니다:

using OpenAI.Responses;

// 턴 간 컨텍스트 유지를 위해 대화를 생성합니다.
...

실행하면, 두 번째 답변이

• 내장 도구(built-in tools) (코드 인터프리터, 파일 검색, Bing 접지 기능)를 연결하면 모델이 언제 이를 호출할지 스스로 결정합니다.
• **사용자 정의 함수 도구(your own function tools)**를 연결하면 에이전트가 대화 중간에 사용자 애플리케이션 코드를 호출합니다.
• 에이전트는 팀 전체에서 참조할 수 있는 이름 지정 및 버전 관리되는 리소스로 영속됩니다. (누군가의 스크립트에 묻힌 프롬프트가 아님)

본 실습은 이 기능들의 가장 작은 부분만을 의도적으로 구현한 것입니다. 오늘 실제로 작동하는 무언가를 얻기에 충분하며, 다음 단계로 도구 호출(tool-calling) 및 다중 에이전트 패턴으로 확장할 여지가 있습니다.

마무리하기 (Wrapping Up)

만약 .NET 개발자로서 AI 엔지니어링 쪽으로의 전환을 고려하고 있다면, 이것은 진정으로 좋은 입문점입니다. SDK는 깔끔하며, 개념들은 이미 알고 있는 것들(클라이언트, DI 친화적 패턴, 타입 지정 모델)에 잘 매핑됩니다. 그리고 Foundry가 그렇지 않았다면 직접 구현해야 했을 인프라까지 처리해 줍니다.

아래 비디오에서 Azure Portal 단계, RBAC 문제점, 실제 오류 몇 가지 디버깅 과정을 포함하여 이 전체 설정을 진행합니다. 만약 Hindi/Hinglish로 따라하고 있다면, 이것이 당신을 위한 것입니다:

🎥

즐거운 코딩 되세요! 🚀