AI Agents

.NET에서 AI 에이전트를 구축하는 깊이 있는 워크스루입니다. 여기에는 에이전트 아키텍처와 제어 루프, 툴 호출(tool calling) 및 함수 호출(function calling), 계획 전략(planning strategies), 에이전트 메모리(agent memory), 자율 에이전트(autonomous agents)와 자율성 수준(levels of autonomy), 다중 에이전트 시스템(multi-agent systems), 오케스트레이션(orchestration), 인간 개입형 설계(human-in-the-loop design), 에이전트 보안(prompt injection, excessive agency, data exfiltration, sandboxing), 그리고 '내가 시도했을 때 작동했는가'를 넘어 에이전트를 평가하는 방법 등이 다루어집니다.

목차 (Table of Contents)

1. 서론 (Introduction)
2. 에이전트 아키텍처 (Agent Architecture)
3. 툴 호출 (Tool Calling)
4. 함수 호출 (Function Calling)
5. 계획 (Planning)
6. 에이전트 메모리 (Agent Memory)
7. 자율 에이전트 (Autonomous Agents)
8. 다중 에이전트 시스템 (Multi-Agent Systems)
9. 에이전트 오케스트레이션 (Agent Orchestration)
10. 인간 개입형 (Human-in-the-Loop)
11. 에이전트 보안 (Agent Security)
12. 에이전트 평가 (Agent Evaluation)
13. 에이전트를 구축하지 말아야 할 때 (When Not to Build an Agent)
14. 일반적인 함정 (Common Pitfalls)
15. 빠른 참조표 (Quick Reference Table)
16. 결론 (Conclusion)

서론 (Introduction)

챗봇은 답변합니다. 에이전트는 행동합니다(acts). 목표가 주어지면, 에이전트는 다음에 무엇을 할지 결정하고, 툴을 사용하여 실행합니다—데이터베이스를 조회하거나, API를 호출하거나, 코드를 실행하거나, 메시지를 보내는 등의 작업을 합니다—결과를 관찰하고, 목표가 달성되거나 포기할 때까지 계속 진행합니다. 이 루프야말로 에이전트를 강력하게 만드는 요소이자 동시에 위험하게 만드는 요소입니다. 에이전트는 모델의 간헐적인 실수(wrong text)를 기계 속도로 수행되는 (잘못된 행동, wrong actions)으로 바꾸어 놓으며, 심지어 실제 자격 증명(real credentials)을 사용하여 그럴 수 있습니다.

Chatbot:   질문 (question)  ->  모델 (model)  ->  답변 (answer)
Workflow:  단계 1 -> 단계 2 -> 단계 3   (사용자가 순서를 고쳤고, 모델이 개별 단계를 채웁니다)
Agent:     목표 (goal) -> [ 생각 -> 행동 (툴) -> 관찰 ] -> 반복 -> 완료 (done)     (모델이 순서를 선택합니다)

이 가이드는 이 시리즈의 이전 가이드들(LLM Application Development, 섹션 11 및 Semantic Kernel, 섹션 8~10)에 있는 에이전트 부분에 대한 심층 분석입니다. 이전 가이드들이 '어떻게 에이전트를 연결할지'를 보여주었다면, 이 글은 더 어려운 엔지니어링 질문들을 다룹니다: 어떻게 구조화할지, 어느 정도의 자율성을 부여할지, 여러 개를 어떻게 조정할지, 인간을 통제권 안에 어떻게 둘지, 공격으로부터 어떻게 보호할지, 그리고 실제로 작동하는지 어떻게 알 수 있는지 등입니다.

이 코드는 Microsoft.Extensions.AI(IChatClient, AIFunction)을 사용하므로 아키텍처가 프레임워크 내부에 숨겨지지 않고 가시적으로 유지됩니다. 따라서 이 개념들은 Semantic Kernel, Microsoft Agent Framework, 호스팅 에이전트 서비스 및 다른 생태계에 직접 적용할 수 있습니다.

프레임워크 및 버전에 대한 참고 사항. 에이전트 프레임워크는 .NET AI 스택 중 변화가 가장 빠른 부분 중 하나입니다 (Semantic Kernel의 에이전트 API, Microsoft Agent Framework, 호스팅 에이전트 서비스, Python 우선 도구들이 모두 빠르게 진화합니다). 이 가이드에 제시된 _아키텍처, 안전성 및 평가 원칙_은 지속 가능한 부분이므로, 어떤 코드를 컴파일하든 설치하는 버전에 맞추고, 하나를 확정하기 전에 최신 프레임워크 문서를 확인하십시오.

1. 에이전트 아키텍처

에이전트는 모델에 제어 루프와 도구, 그리고 가드레일이 더해진 것입니다

                  ┌──────────────────────────── AGENT RUNTIME (당신의 코드) ────────────────────────────┐
                  │                                                                                    │
   목표 /         │   ┌──────────────┐   결정한다   ┌──────────────┐  실행한다   ┌──────────────┐      │
...             │   (생각/계획) │ (다음 행동 선택) │ (도구 호출) │ (결과 처리) │      │

구성 요소들

모델 (MODEL)            추론 엔진. 주어진 컨텍스트에서 다음 행동을 선택합니다.
지침 (INSTRUCTIONS)     시스템 프롬프트: 역할, 목표, 규칙, 제약 조건, 도구 사용 방법, 언제 멈추거나 질문할지 등.
도구 (TOOLS)            에이전트의 '손' — 호출할 수 있는 함수들 (섹션 2~3).
...```

**모델은 제안하고; 코드가 폐기합니다.** 모델 자체는 아무것도 실행하지 않습니다. 사용자의 런타임(runtime)이 실행하며, 모든 안전 속성(safety property)은 이 런타임에 존재해야 합니다.

### 제어 루프 작성하기

using Microsoft.Extensions.AI;

public record AgentBudget(int MaxSteps = 8, int MaxTokens = 50_000, TimeSpan? MaxDuration = null);
...

에이전트 프레임워크가 하는 모든 것은 이 과정을 상세화한 것입니다: 컨텍스트를 구축하고, 모델을 호출하며, 모델이 요청하는 것을 실행합니다(게이트를 통해). 그 결과를 피드백으로 공급하고, 조건에 따라 멈춥니다. 이때 무한정 실행되지 않도록 예산(budget)이 설정됩니다.

### 제어 흐름 패턴

REACT 스타일 루프 위의 루프: 다음 단계에 대해 추론하고, 행동하며, 관찰하고, 반복합니다. 간단하고 유연하여 도구 사용 에이전트의 기본값입니다.

...

### 컨텍스트 엔지니어링: 에이전트의 실제 작업 기억 공간

루프가 반복될 때마다 증가하는 기록(transcript) 전체가 다시 전송됩니다. 따라서 에이전트는 컨텍스트 안에 무엇이 포함되어 있느냐에 따라 생존하거나 죽습니다:

• 도구 결과(TOOL RESULTS)는 토큰 사용량을 지배합니다. 작고 관련성 높은 결과를 반환하고, 크기가 큰 결과는 잘라내거나 요약하세요.
• 간결하게 유지하세요: 완료된 하위 작업은 요약하고, 에이전트가 더 이상 필요로 하지 않는 원시 도구 출력(raw tool output)은 제거하세요.
  ...

### 워크플로우에서 에이전트로의 스펙트럼

고정된 워크플로우(FIXED WORKFLOW) 단계가 하드코딩됩니다; 모델은 단계 내부에서 사용됩니다. 예측 가능하고, 테스트 가능하며, 저렴합니다.
라우팅된 워크플로우(ROUTED WORKFLOW) 모델이 실행할 어떤 고정된 워크플로우를 선택합니다. 여전히 각 분기 내에서는 예측 가능합니다.
제한된 에이전트(BOUNDED AGENT) 모델이 엄격한 한계 내에서 단계를 선택합니다. 유연하지만, 예산과 가드레일(guardrails)이 필요합니다.
...

## 2. 도구 호출 (Tool Calling)

### 도구는 에이전트가 세상을 인식하고 영향을 미치는 방법입니다

**도구 호출**은 모델이 텍스트로 응답하는 대신(또는 그 전에), 자신 외부의 무언가를 요청하는 일반적인 메커니즘입니다. 모델은 구조화된 요청—도구 이름과 인자—을 방출하고, 사용자의 런타임이 이를 실행하며, 결과가 컨텍스트 안으로 다시 들어갑니다.

도구의 종류:
  READ / RETRIEVE    문서 검색, 데이터베이스 질의, 페이지 가져오기, 파일 읽기        (위험도 낮음)
  COMPUTE            코드 실행, 수학 계산, 데이터 변환                                    (위험도는 샌드박싱에 따라 다름)
...

### 도구 설계: 에이전트 엔지니어링에서 가장 높은 레버리지를 가진 작업

CLEAR NAMES AND DESCRIPTIONS 설명은 모델을 위한 도구의 전체 사용자 매뉴얼입니다. 무엇을 하는지, 언제 사용해야 하는지, 언제 사용하면 안 되는지, 각 매개변수가 무엇을 의미하는지, 그리고 그 한계를 명시하세요. 모호한 설명은 잘못된 호출과 놓치는 호출을 유발하며, 이는 어떤 프롬프트 수정보다도 심각합니다.
...

### 잘 설명된 도구

[Description("고객의 지원 티켓을 검색합니다. 주제나 키워드로 티켓을 찾는 데 사용하세요. " +
"최대 5개의 일치 항목이 반환되며, 최신순입니다. 특정 티켓을 읽으려면 id를 사용하여 get_ticket을 사용하세요.")]
public async Task<string> SearchTicketsAsync(
...

### 도구 결과는 신뢰할 수 없는 입력값입니다

도구가 반환하는 모든 것—웹 페이지, 이메일 본문, 고객이 작성한 티켓, 파일—은 모델의 컨텍스트로 다시 들어갑니다. 만약 여기에 지침(

**Function calling**은 도구 사용을 신뢰성 있게 만드는 특정 API 기능입니다. 사용자는 함수(이름, 설명, 매개변수에 대한 JSON Schema)를 설명하고, 모델은 스키마와 일치하는 구조화된 호출로 응답하며, 사용자의 코드가 이를 실행합니다. 제공업체들은 또한 'tool calling'이라는 용어를 사용하며, 실제로는 두 용어가 거의 상호 교환적으로 사용됩니다. 여기서 'tools'는 웹 검색이나 코드 인터프리터와 같은 호스팅된 도구를 포함하는 더 광범위한 개념입니다. 이 메커니즘은 _AI APIs with .NET_의 섹션 6과 _Microsoft.Extensions.AI_의 섹션 7에서 다루고 있습니다.

1. 전송하는 내용: 메시지(messages) + 함수 정의(function DEFINITIONS) (이름, 설명, 매개변수 스키마)
2. 모델이 전송하는 내용: 함수 호출(function CALL) { name: "search_tickets", arguments: { "query": "refund", "status": "open" } }
   (FinishReason = ToolCalls) — 한 번에 여러 개의 호출일 수 있음
   ...

### Microsoft.Extensions.AI를 사용한 함수 정의

var searchTool = AIFunctionFactory.Create(tools.SearchTicketsAsync, name: "search_tickets");
var getTool = AIFunctionFactory.Create(tools.GetTicketAsync, name: "get_ticket");

...

`AIFunctionFactory.Create`는 C# 메서드와 그 `[Description]` 속성으로부터 이름, 설명 및 JSON Schema를 파생합니다. 파이프라인이 루프를 대신 실행하도록 하려면 `UseFunctionInvocation()` 미들웨어를 사용하고; 완전한 제어권을 유지하려면(위의 루프와 같이) 직접 `FunctionCallContent`를 처리해야 합니다.

### 도구 선택 및 병렬 호출

ToolMode Auto 모델이 도구를 호출할지 여부를 결정합니다.
ToolMode RequireAny 모델은 반드시 도구를 호출해야 합니다(강제 추출 또는 라우팅에 유용함).
ToolMode None 도구는 설명되지만 호출될 수 없습니다(예: 최종 요약 단계에서).
...

### Function Calling 시 발생할 수 있는 문제점

잘못된 도구 사용 / 잘못된 인자 (WRONG TOOL / WRONG ARGUMENTS)   보통 모호한 설명, 중복되는 도구, 또는 너무 많은 도구를 의미합니다. 먼저 도구 설계를 수정해야 합니다. 
HALLUCINATED ARGUMENTS         모델이 부여받지 않은 ID나 값을 지어내는 경우입니다. 현실(예: "존재하지 않는 주문 99999")과 비교하여 유효성을 검사하고, 도움이 되는 오류 메시지를 반환합니다.
...

### 호출 경계에서의 유효성 검사 및 정책 (Validation and policy at the call boundary)

public sealed class ToolPolicy(ICurrentUser user) : IToolPolicy
{
private static readonly HashSet<string> ReadOnly = ["search_tickets", "get_ticket", "search_docs"];
private static readonly HashSet<string> Sensitive = ["issue_refund", "send_email", "close_account"];

public ToolD