API 호출 에이전트 이해, 구축 및 최적화에 대한 가이드 To-Do 목록 API version: 1.0.0 paths: /tasks: post: summary: 새로운 태스크 추가 requestBody: required: true

기술 회사에서 인공지능의 역할은 빠르게 발전하고 있습니다. 인공지능의 사용 사례는 수동적인 정보 처리에서 능동적인 에이전트로 발전하였으며, 태스크를 실행할 수 있는 에이전트가 등장했습니다. 2025년 3월에 Georgian과 NewtonX가 수행한 글로벌 인공지능 채택에 관한 조사에 따르면, 성장 단계와 기업 회사에서 91%의 기술 책임자들이 에이전트 인공지능을 사용하거나 사용할 계획이라고 보고했습니다.

API 호출 에이전트는 이러한 변화를 대표하는 예입니다. API 호출 에이전트는 대형 언어 모델(LLM)을 사용하여 소프트웨어 시스템과 상호 작용할 수 있습니다.

예를 들어, 자연어 명령을 정밀한 API 호출로 번역하여 에이전트는 실시간 데이터를 검색하거나, 반복적인 태스크를 자동화하거나, 다른 소프트웨어 시스템을 제어할 수 있습니다. 이 기능은 인공지능 에이전트를 유용한 중간자로 변환하여 인간의 의도와 소프트웨어 기능 사이를 연결합니다.

현재 회사들은 다양한 영역에서 API 호출 에이전트를 사용하고 있습니다.

• 소비자 애플리케이션: Apple의 Siri나 Amazon의 Alexa와 같은 어시스턴트는 스마트 홈 디바이스를 제어하거나 예약을 하는 등의 일상적인 태스크를 단순화하기 위해 설계되었습니다.
• 기업 워크플로우: 기업은 반복적인 태스크를 자동화하기 위해 API 에이전트를 배포했습니다. 예를 들어, CRM에서 데이터를 검색하거나, 보고서를 생성하거나, 내부 시스템에서 정보를 통합하는 등의 태스크를 자동화할 수 있습니다.
• 데이터 검색 및 분석: 기업은 독점적인 데이터셋, 구독 기반 리소스, 공공 API에 대한 접근을 단순화하기 위해 API 에이전트를 사용하고 있습니다. 이를 통해 통찰력을 얻을 수 있습니다.

이 기사에서는 API 호출 에이전트를 이해하고, 구축하고, 최적화하는 방법에 대한 엔지니어링 중심의 접근 방식을 사용하겠습니다. 이 기사의 내용은 부분적으로 Georgian의 AI 연구소에서 수행한 실제 연구와 개발에 기반하고 있습니다. AI 연구소의 연구는 주로 “조직이 API를 가지고 있다면, 자연어를 사용하여 그 API와 상호 작용할 수 있는 에이전트를 구축하는 가장 효과적인 방법은 무엇인가?”라는 질문에 초점을 맞추고 있습니다.

API 호출 에이전트가 어떻게 작동하는지와 어떻게 성능을 위해 성공적으로 설계하고 구축할 수 있는지에 대해 설명하겠습니다. 마지막으로, 엔지니어링 팀이 API 호출 에이전트를 구현하기 위해 사용할 수 있는 체계적인 워크플로우를 제공하겠습니다.

I. 주요 정의:

• API 또는 응용 프로그램 프로그래밍 인터페이스: 다른 소프트웨어 애플리케이션이 통신하고 정보를 교환할 수 있도록 하는 규칙과 프로토콜의 집합입니다.
• 에이전트: 특정 목표를 달성하기 위해 환경을 인식하고, 의사 결정을 내리고, 행동을 취하는 인공지능 시스템입니다.
• API 호출 에이전트: 자연어 지시를 정밀한 API 호출로 번역하는 전문 에이전트입니다.
• 코드 생성 에이전트: 소프트웨어 개발을 지원하는 인공지능 시스템으로, 코드를 작성하고, 수정하고, 디버깅합니다. 이 기사에서는 주로 API를 호출하는 에이전트에 초점을 맞추고 있지만, 인공지능은 이러한 에이전트를 구축하는 데에도 도움이 될 수 있습니다.
• MCP (모델 컨텍스트 프로토콜): Anthropic에서 개발한 프로토콜로, 대형 언어 모델(LLM)이 외부 도구와 데이터 소스를 연결하고 사용하는 방법을 정의합니다.

II. 핵심 작업: 자연어를 API 동작으로 번역

API 호출 에이전트의 기본적인 기능은 사용자의 자연어 요청을 해석하고, 하나 이상의 정밀한 API 호출로 변환하는 것입니다. 이 과정에는 일반적으로 다음 단계가 포함됩니다.

1. 의도 인식: 사용자의 목표를 이해하는 것, 즉 사용자가 모호하게 표현하더라도.
2. 도구 선택: 사용 가능한 옵션 중에서 의도를 충족할 수 있는 적절한 API 엔드포인트(또는 “도구”)를 식별하는 것입니다.
3. 매개 변수 추출: 선택한 API 호출에 필요한 매개 변수를 사용자의 질의에서 식별하고 추출하는 것입니다.
4. 실행 및 응답 생성: API 호출을 수행하고, 응답을 받고, 이를 일관된 답변이나 후속 동작으로 합성하는 것입니다.

“Siri, 오늘 날씨는 어떻나요?”라는 요청을 고려해 보십시오. 에이전트는 날씨 API를 호출해야 한다는 것을 식별해야 하며, 사용자의 현재 위치를 결정해야 하거나(또는 위치를 지정할 수 있도록 해야 함) 날씨 정보를 검색하기 위한 API 호출을 구성해야 합니다.

예를 들어, “Siri, 오늘 날씨는 어떻나요?”라는 요청에 대한 샘플 API 호출은 다음과 같습니다.

GET /v1/weather?location=뉴욕&units=미터법

초기 고수준의 도전은 자연어의 모호성과 에이전트가 다단계 상호 작용에서 맥락을 유지해야 하는 필요성과 관련이 있습니다.

예를 들어, 에이전트는 종종 이전 대화의 일부 또는 이전 API 호출 결과를 “기억”해야 하여 현재의 동작을 알 수 있습니다. 맥락 손실은 이를 명시적으로 관리하지 않으면 일반적인 오류 모드입니다.

III. 솔루션 설계: 주요 구성 요소 및 프로토콜

효과적인 API 호출 에이전트를 구축하려면 구조화된 설계 접근 방식이 필요합니다.

1. 에이전트를 위한 도구 정의

LLM이 API를 사용하려면, 그 API의 기능이 에이전트가 이해할 수 있는 방식으로 설명되어야 합니다. 각 API 엔드포인트 또는 함수는 일반적으로 “도구”로 표현됩니다. 강력한 도구 정의에는 다음이 포함됩니다.

• 도구의 목적과 기능에 대한 명확한 자연어 설명.
• 입력 매개 변수(이름, 유형, 필수/선택 사항 여부, 설명)의 정확한 사양.
• 도구가 반환하는 출력 또는 데이터에 대한 설명.

2. 모델 컨텍스트 프로토콜(MCP)의 역할

MCP는 LLM이 외부 도구와 데이터 소스를 더 표준화된 방식으로 사용할 수 있도록 하는 중요한 역할을 합니다. 외부 도구와 데이터 소스를 연결하고 사용하는 방법을 정의하는 구조화된 형식을 제공합니다.

MCP 표준화는 다양한 도구의 통합을 더 쉽게 만들고, 도구 정의의 재사용을 다양한 에이전트 또는 모델에서 촉진하며, 또한 엔지니어링 팀에게 좋은 관행입니다. 이는 잘 정의된 API 사양, 즉 OpenAPI 사양과 함께 시작하는 것을 의미합니다. Stainless.ai와 같은 도구는 이러한 OpenAPI 사양을 MCP 구성으로 변환하여 API를 “에이전트 준비”로 만드는 과정을 간소화합니다.

3. 에이전트 프레임워크 및 구현 선택

에이전트를 구축하는 데 도움이 되는 여러 프레임워크가 있습니다. 이러한 프레임워크에는 다음이 포함됩니다.

• Pydantic: 에이전트 프레임워크만이 아닌, 도구 입력 및 출력에 대한 데이터 구조를 정의하고, 타입 안전성을 보장하는 데 유용합니다. 많은 사용자 정의 에이전트 구현에서 Pydantic를 사용하여 구조적完整성을 보장합니다.
• LastMile의 mcp_agent: 이 프레임워크는 MCP와 함께 작동하도록 설계되었으며, Anthropic과 같은 곳에서 연구된 에이전트 구축 관행에 따라 더 의견이 있는 구조를 제공합니다.
• 내부 프레임워크: 또한 AI 코드 생성 에이전트(예: Cursor 또는 Cline)를 사용하여 에이전트, 도구 및周辺 논리를 위한 보일러플레이트 코드를 작성하는 데 도움이 될 수 있습니다. Georgian의 AI 연구소는 회사와의 협력에서 이 접근 방식이 매우 최소한의 사용자 정의 프레임워크를 생성하는 데 좋다는 것을 알게 되었습니다.

IV. 신뢰성 및 성능을 위한 엔지니어링

에이전트가 API 호출을 신뢰성 있게 수행하고, 잘 작동하도록 보장하려면, 집중된 엔지니어링 노력이 필요합니다. 이를 달성하는 두 가지 방법은 (1) 데이터셋 생성 및 검증과 (2) 프롬프트 엔지니어링 및 최적화입니다.

1. 데이터셋 생성 및 검증

에이전트를 훈련(적용 가능한 경우), 테스트 및 최적화하려면 높은 품질의 데이터셋이 필요합니다. 이 데이터셋은 대표적인 자연어 질의와 해당하는 원하는 API 호출 시퀀스 또는 결과로 구성되어야 합니다.

• 수동 생성: 데이터셋을 수동으로 큐레이션하면 높은 정확도와 관련성이 보장되지만, 노동 집약적일 수 있습니다.
• 합성 생성: 프로그래밍 방식으로 또는 LLM을 사용하여 데이터를 생성할 수 있지만, 이는 상당한 도전을 제기합니다. Georgian AI 연구소의 연구에 따르면, 생성된 API 호출과 질의의 정확성과 현실적인 복잡성을 보장하는 것이 매우 어렵습니다. 종종 생성된 질문은 너무 단순하거나 불가능할 정도로 복잡하여, 에이전트의 성능을 측정하기가 어려웠습니다. 합성 데이터의 경우, 철저한 검증이 절대적으로 중요합니다.

중요한 평가를 위해, 작은 규모의 수동으로 검증된 데이터셋은 큰 규모의 노이즈가 있는 합성 데이터셋보다 더 신뢰할 수 있는 통찰력을 제공할 수 있습니다.

2. 프롬프트 엔지니어링 및 최적화

LLM 기반 에이전트의 성능은 프롬프트를 사용하여 에이전트의推論과 도구 선택을 안내하는 데 크게 영향을 받습니다.

• 효과적인 프롬프트는 에이전트의 작업을 명확하게 정의하고, 사용 가능한 도구를 설명하며, 매개 변수 추출을 구조화하는 것을 포함합니다.
• 시스템적인 최적화를 위한 프레임워크인 DSPy를 사용하면 성능을 크게 향상시킬 수 있습니다. DSPy를 사용하면 에이전트의 구성 요소(예: 思考 생성, 도구 선택, 매개 변수 형식 지정 모듈)를 정의하고, 데이터셋의 예를 사용하여 이러한 구성 요소에 대한 최적의 프롬프트 또는 구성 찾기 위해 컴파일러와 같은 접근 방식을 사용할 수 있습니다.

V. 효과적인 API 에이전트에 대한 추천 경로

강력한 API 호출 에이전트를 개발하는 것은 반복적인 엔지니어링입니다. Georgian AI 연구소의 연구 결과에 기반하여, 다음과 같은 체계적인 워크플로우를 사용하면 결과를 크게 향상시킬 수 있습니다.

1. 명확한 API 정의부터 시작하십시오: 에이전트가 상호 작용할 API에 대한 잘 구조화된 OpenAPI 사양으로 시작하십시오.
2. 도구 접근을 표준화하십시오: OpenAPI 사양을 MCP 도구로 변환하십시오. Stainless.ai와 같은 도구를 사용하면 이 과정은 간소화될 수 있으며, 에이전트가 API를 이해하고 사용할 수 있는 표준화된 방법을 제공합니다.
3. 에이전트를 구현하십시오: 적절한 프레임워크 또는 접근 방식을 선택하십시오. 이는 Pydantic를 사용하여 사용자 정의 에이전트 구조 내의 데이터 모델링을 정의하는 것을 포함하거나, MCP와 함께 작동하도록 설계된 LastMile의 mcp_agent와 같은 프레임워크를 사용하는 것을 포함할 수 있습니다.
4. 품질 평가 데이터셋을 큐레이션하십시오: 수동으로 생성하거나, 철저하게 검증된 데이터셋을 생성하여, 대표적인 자연어 질의와 해당하는 원하는 API 호출 또는 결과를 포함하십시오. 이는 테스트 및 최적화를 위한 신뢰할 수 있는 데이터셋을 제공합니다.
5. 에이전트 프롬프트와 논리를 최적화하십시오: DSPy와 같은 프레임워크를 사용하여 에이전트의 프롬프트와 내부 논리를 개선하고, 데이터셋을 사용하여 정확성과 신뢰성의 향상을 주도하십시오.

VI. 워크플로우의 예시

API 호출 에이전트를 구축하기 위한 추천 워크플로우의 간소화된 예입니다.

단계 1: 명확한 API 정의부터 시작하십시오

간단한 To-Do 목록을 관리하는 API를 생각해 보십시오. OpenAPI로 정의된 이 API는 다음과 같습니다.

openapi: 3.0.0

info:
application/json:

schema:

type: object

properties:

description:

type: string

responses:

‘201’:

description: 태스크 생성 성공

get:

summary: 모든 태스크 가져오기

responses:

‘200’:

description: 태스크 목록

단계 2: 도구 접근을 표준화하십시오

OpenAPI 사양을 MCP 구성으로 변환하십시오. Stainless.ai와 같은 도구를 사용하면 다음과 같은 결과가 나올 수 있습니다.

단계 3: 에이전트를 구현하십시오

Pydantic를 사용하여 데이터 모델링을 정의하고, MCP 도구에 해당하는 함수를 생성합니다. 그런 다음, LLM을 사용하여 자연어 질의를 해석하고, 적절한 도구와 매개 변수를 선택합니다.

단계 4: 품질 평가 데이터셋을 큐레이션하십시오

데이터셋을 생성합니다.

단계 5: 에이전트 프롬프트와 논리를 최적화하십시오

DSPy를 사용하여 프롬프트를 개선하고, 데이터셋을 사용하여 평가 및 개선을 위해 에이전트의 내부 논리를 최적화합니다.

이러한 빌딩 블록을 통합함으로써 – 구조화된 API 정의, 표준화된 도구 프로토콜, 엄격한 데이터 관행 및 체계적인 최적화 – 엔지니어링 팀은 더 능력 있고, 신뢰할 수 있고, 유지 보수가 가능한 API 호출 인공지능 에이전트를 구축할 수 있습니다.