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

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

API 호출 에이전트는 이러한 에이전트로의 전환의 주요 예입니다. API 호출 에이전트는 소프트웨어 시스템과 상호 작용하기 위해 대형 언어 모델(LLM)을 사용합니다.

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

현재 회사들은 다양한 도메인에서 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=New%20York&units=metric

이 번역 프로세스에는 초기 고수준의 도전이 내재되어 있습니다. 예를 들어, 자연어의 모호성과 에이전트가 다단계 상호 작용에서 컨텍스트를 유지해야 하는 필요성입니다.

예를 들어, 에이전트는 종종 이전 대화의 이전 부분이나 이전 API 호출 결과를 “기억”해야 하여 현재 동작을 информ합니다. 컨텍스트 손실은 명시적으로 관리하지 않는 경우 일반적인 실패 모드입니다.

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

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

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

LLM이 API를 사용하려면 해당 API의 기능을 이해할 수 있는 방식으로 설명해야 합니다. 각 API 엔드포인트 또는 함수는 종종 “도구”로 표시됩니다. 강력한 도구 정의에는 다음이 포함됩니다.

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

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

MCP는 LLM이 외부 도구 및 데이터 소스를 사용하는 더 표준화되고 강력한 방법을 제공하는 중요한 활성화자입니다. 외부 도구 및 데이터 소스에 연결하는 방법을 정의하는 구조화된 형식을 제공합니다.

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

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

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

• Pydantic: 전용 에이전트 프레임워크는 아니지만, Pydantic은 도구 입력 및 출력에 대한 데이터 구조를 정의하고, 신뢰성에 중요함에도 불구하고, 유형 안전성을 보장하는 데 유용합니다. 많은 사용자 지정 에이전트 구현은 구조적 무결성을 위해 Pydantic을 활용합니다.
• LastMile의 mcp_agent: 이 프레임워크는 MCP와 함께 작동하도록 설계되었으며, Anthropic과 같은 곳에서 연구에 설명된 바와 같이 효과적인 에이전트를 구축하는 관행에 맞춰진 더 의견이 있는 구조를 제공합니다.
• 내부 프레임워크: 또한 AI 코드 생성 에이전트(예: Cursor 또는 Cline)를 사용하여 에이전트, 도구 및周围 논리에 대한 보일러플레이트 코드를 작성하는 것이 점점 더 일반적입니다. Georgian의 AI 연구소는 회사와의 협력을 통해 에이전트 구현에 대한 경험을 통해 이것이 매우 최소한의 사용자 지정 프레임워크를 생성하는 데 좋을 수 있음을 보여주었습니다.

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

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

1. 데이터셋 생성 및 검증

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

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

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

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

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

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

V. 효과적인 API 에이전트로의 권장 경로

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

1. 명확한 API 정의에서 시작: 상호 작용할 API에 대한 잘 구조화된 OpenAPI 사양으로 시작합니다.
2. 도구 액세스 표준화: OpenAPI 사양을 MCP 도구로 변환합니다. Stainless.ai와 같은 도구를 사용하여 API를 “에이전트 준비”로 만드는 프로세스를 간소화하는 데 도움이 될 수 있습니다.
3. 에이전트 구현: 적절한 프레임워크 또는 접근 방식을 선택합니다. 이는 Pydantic을 사용하여 사용자 지정 에이전트 구조 내의 데이터 모델링을 수행하거나, MCP와 함께 작동하도록 설계된 LastMile의 mcp_agent와 같은 프레임워크를 활용하는 것을 포함할 수 있습니다.
   • 이전에 MCP를 Claude Desktop 또는 Cline과 같은 도구에 연결하고, 수동으로 이 인터페이스를 사용하여 제네릭 에이전트가이를 얼마나 잘 사용할 수 있는지, MCP를 올바르게 사용하는 데 몇 번의 반복이 필요한지 및 구현 중 시간을節約할 수 있는 기타 세부 사항을 확인하는 것이 좋습니다.
4. 품질 평가 데이터셋 큐레이션: 수동으로 생성하거나, 철저히 검증된 데이터셋을 생성하여, 신뢰할 수 있는 테스트 및 최적화를 수행합니다.
5. 에이전트 프롬프트 및 논리 최적화: DSPy와 같은 프레임워크를 사용하여 에이전트의 프롬프트 및 내부 논리를 개선하고, 데이터셋을 사용하여 정확성 및 신뢰성의 향상을 驅動합니다.

VI. 워크플로우의 예시

API 호출 에이전트를 구축하기 위한 권장 워크플로우의 간소화된 예는 다음과 같습니다:

단계 1: 명확한 API 정의에서 시작

간단한 To-Do 목록을 관리하는 API를 상상해 보십시오. OpenAPI로 정의됩니다.

openapi: 3.0.0

info:
application/json:

schema:

type: object

properties:

description:

type: string

responses:

‘201’:

description: 작업 생성 성공

get:

summary: 모든 작업 가져오기

responses:

‘200’:

description: 작업 목록

단계 2: 도구 액세스 표준화

OpenAPI 사양을 Model Context Protocol(MCP) 구성으로 변환합니다. Stainless.ai와 같은 도구를 사용하여 MCP 도구를 생성할 수 있습니다.

단계 3: 에이전트 구현

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

단계 4: 품질 평가 데이터셋 큐레이션

데이터셋을 생성합니다:

단계 5: 에이전트 프롬프트 및 논리 최적화

DSPy를 사용하여 프롬프트를 개선하고, 명확한 지침, 도구 선택 및 매개변수 추출에 중점을 둡니다. 또한, 데이터셋을 사용하여 평가 및 향상을 위해 최적화합니다.

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