이 글을 쓰는 이유
저는 .NET 백엔드 개발자입니다. 지금까지는 프론트엔드나 모바일 팀을 위해 API를 만들어 왔습니다. 그런데 최근에 반복적으로 'AI Agent가 당신의 API를 사용할 것이다'라는 말을 듣게 되었습니다. 그래서 저는 이것이 무엇을 의미하는지, 그리고 제 API에서 무엇을 변경해야 하는지 알고 싶어졌습니다.
이 글은 그런 학습 노트입니다. 어떤 전문가가 쓴 것이 아니라, 한 학생이 정리한 요약본이라서, 한번 읽기만 해도 전체 내용을 이해할 수 있도록 했습니다.
한눈에 보기 (TL;DR)
AI Agent는 사람처럼 API를 사용하지 않습니다. 문서(documentation)를 읽지 않고, 추측하지 않으며, 에러가 발생했다고 해서 스스로 디버그하지도 않고, 그리고 매우 빠르게 재시도(retry)합니다. 따라서 5가지 작업을 수행해야 합니다:
| # | 작업 | 쉬운 말로 설명하기 |
|---|
| ১ | 전체 schema 및 description | Agent에게 무엇을 보내야 할지 명확하게 알려주기 |
| ... | | |
먼저 몇 가지 용어를 정리하겠습니다
- AI Agent: LLM이 스스로 결정을 내리고 다양한 tool 및 API 호출(call)을 통해 작업을 완료하는 프로그램입니다. 예를 들어, '이 고객에게 주문해 줘'라고 말하면, 어떤 API가 어떤 순서로 호출해야 할지 스스로 결정합니다.
- OpenAPI spec: 당신의 API에 대한 기계가 읽을 수 있는 설명서입니다 (Swagger에서 보는 것이 실제 출처). 어떤 엔드포인트(endpoint)가 있고, 무엇을 보내야 하며, 무엇이 반환되는지를 알려줍니다.
- Idempotency: 동일한 요청(request)을 여러 번 보내더라도 그 결과가 한 번 보낸 것과 같은 상태를 유지하는 것입니다.
- MCP (Model Context Protocol): AI Agent에게 외부 tool 및 데이터와 연결해 주는 오픈 프로토콜입니다. 일종의 'AI를 위한 USB 포트'라고 할 수 있습니다.
사람 개발자 대 AI Agent
| 항목 | 사람 개발자 | AI Agent |
|---|
| 문서(Documentation) | 읽고, 이해한다 | 주로 OpenAPI spec 및 description에 의존한다 |
| ... | | |
| 이러한 차이점 때문에 아래의 5가지 규칙이 생겨납니다. | | |
가상의 예시 하나
이해하기 쉽도록 Order API가 있다고 가정하고, Agent에게 '상품 2개 주문해 줘'라고 지시했다고 해봅시다. (이는 상상일 뿐, 실제 사건은 아닙니다.)
- Spec에
quantity의 타입(type)이 적혀있지 않아서, Agent는 `
1. 전체 스키마 및 의미 있는 설명
규칙: 모든 필드에 type, format, constraint 및 description을 제공하세요.
.NET에서 request model에 attribute를 사용하면 OpenAPI spec에 포함됩니다:
public record PlaceOrderRequest(
[property: Description("사용자가 주문하는 고객의 ID")]
Guid CustomerId,
...
엔드포인트 설명도 고려하세요. "데이터 가져오기"보다는 "상태와 날짜 범위로 필터링된 인보이스의 페이지네이션 목록을 반환합니다"가 Agent에게 훨씬 좋은 신호를 줍니다.
2. 모든 곳에서 일관성 (Consistency)
Agent는 하나의 엔드포인트에서 패턴을 학습하여 다른 곳에 적용합니다. 한 곳에서는 status가 pending이고, 다른 곳에서는 IN_PROGRESS, 또 다른 곳에서는 done이라면 혼란스러워합니다.
모든 곳에서 지킬 컨벤션을 정하고 따르세요:
- 명명 규칙 (camelCase 또는 snake_case, 둘 다 사용하지 않기)
- ID 형식 (예: 모든 곳에서
uuid)
- 페이지네이션 방식
- 에러 구조
- 상태 값의 표기법
3. 구조화된 에러 (Structured Error)
규칙: 에러를 Agent가 이해할 수 있는 지침으로 만드세요: 어떤 필드가 잘못되었는지, 무엇을 받았는지, 어떤 값이 유효한지.
ASP.NET Core에는 RFC 9457 (Problem Details)이 내장되어 있습니다. 여기에 자체 필드를 추가할 수 있습니다:
return Results.Problem(
title: "Invalid field value",
detail: "Field 'status' received invalid value 'processing'.",
...
결과 JSON:
{
"title": "Invalid field value",
"status": 400,
...}
{"error": "Invalid input"}와 비교해 보세요. 이것을 받으면 Agent가 다음 시도에서 올바른 값을 보낼 수 있습니다.
4. Idempotency (멱등성)
문제: 네트워크 타임아웃이 발생하면 Agent(또는 모든 클라이언트)가 재시도합니다. POST /orders를 두 번 보내면 주문이 두 개 생성될 수 있습니다.
해결책: 클라이언트는 Idempotency-Key 헤더를 보냅니다. 서버는 그 키를 기억합니다. 같은 키가 다시 오더라도 새로운 주문을 만들지 않고 이전 결과를 반환합니다.
학습용 간단한 스케치 (in-memory, 프로덕션에서는 Redis나 데이터베이스 필요):
var seenKeys = new ConcurrentDictionary<string, bool>();
app.MapPost("/orders", (HttpRequest http, PlaceOrderRequest body) =>
...
중요한 두 가지 사항:
- 원자적 확인 (Atomic check): '먼저 있는지 확인하고, 그 다음에 설정한다'는 두 단계로 처리하면 두 개의 병렬 요청(parallel request) 모두 실패할 수 있습니다. Redis의
SET NX나 데이터베이스의 unique constraint가 이 작업을 수행합니다.
- 실제 시스템에서는 이전 성공 응답을 저장하여 반환해야 하며, 단순히 Conflict만 반환해서는 안 됩니다. 이 스케치는 개념 이해를 위한 것입니다.
5. 신중하게 설계된 Operation, 단순 CRUD 이상
각 엔드포인트를 Agent에게 tool로 제공하면, 그 앞에 너무 많은 선택지가 생겨 잘못 선택할 가능성도 커집니다. 잘 정의된 operation 몇 가지가 더 유용합니다.
예시: 고객을 검색 → 재고 확인 → 주문 생성처럼 주문하려면 세 번의 호출이 필요하다면, 하나의 PlaceOrder operation을 만들 수 있습니다. Agent는 단계를 구성할 필요가 없고, 중간에 오류가 발생할 여지도 줄어듭니다.
MCP: Agent를 위한 다음 단계
MCP(Model Context Protocol)를 사용하면 여러분의 operation들을 Agent가 쉽게 찾고 사용할 수 있도록 노출시킬 수 있습니다. .NET용 공식 C# SDK가 있습니다. 하나의 tool은 대략 다음과 같습니다:
[McpServerToolType]
public class OrderTools
{
...
SDK는 빠르게 변경되므로, 설정에 필요한 정확한 코드는 official repository에서 확인하세요.
여기서도 5번 규칙이 적용됩니다: 모든 엔드포인트를 MCP tool로 만들 필요는 없습니다. Agent에게 정말 필요한 것들만 만드세요.
체크리스트
직접 해보는 작은 과제
읽는 것과 하는 것은 다릅니다. 1~2시간이면 할 수 있습니다:
- 작은
POST /orders 엔드포인트를 만드세요 (의도적으로 type 및 오류를 모호하게 남겨두어도 무방합니다).
- MCP 지원 클라이언트 또는 Agent로 이를 호출해보고, 어디서 막히는지 확인하세요.
- 5가지 규칙을 하나씩 적용하며, 매번 동작이 어떻게 변하는지 기록하세요.
더 읽어볼 자료
마무리하며
API는 오랫동안 개발자들을 위해 설계되어 왔습니다. 이제 API의 소비자(consumer)로서 Agent도 등장하고 있으며, 이들은 추측하거나 디버깅하지 않습니다. 스키마가 명확하고, 오류 지시적이며, 재시도가 안전한 API는 Agent와 사람 모두에게 좋습니다.
여러분의 API에 위 5가지 중 어떤 것을 가장 먼저 적용하시겠습니까? 댓글로 알려주세요.
_이전 글: Repository, MediatR, CQRS를 활용한 프로덕션 경험