API Agent는 GraphQL 또는 REST API를 Multi-Channel Protocol (MCP) 서버로 전환하여, 사용자가 자연어로 API 데이터를 질의하고 복잡한 데이터 후처리까지 수행할 수 있도록 지원하는 도구입니다. 이 시스템은 API의 스키마를 자동 분석(introspect)하고, 데이터 페칭(fetching) 후 DuckDB에 저장하여 SQL 기반의 고급 데이터 처리(예: 랭킹, 필터링, 조인, 집계)를 가능하게 합니다.

주요 특징 및 차별점:

1. Zero-Configuration (Zero-Config): 별도의 설정 코드 없이 GraphQL 엔드포인트나 OpenAPI 명세 URL만 제공하면 자동으로 스키마를 분석합니다.
2. SQL Post-processing: API가 직접 지원하지 않는 기능(예: 정렬, 집계, JOIN)을 DuckDB를 사용하여 구현합니다. 예를 들어, 정렬되지 않은 대량의 API 응답 데이터에 대해 상위 N개 랭킹을 매기거나, GROUP BY 없는 API 결과에 집계를 수행하고, 여러 엔드포인트의 데이터를 JOIN할 수 있습니다.
3. 안전성 (Safe by default): 기본적으로 읽기(Read-only) 작업만 허용하며, POST, PUT, DELETE, PATCH와 같은 변경(mutations) 작업은 X-Allow-Unsafe-Paths 헤더를 통해 명시적으로 허용된 경로에 대해서만 가능합니다.
4. 레시피 학습 (Recipe learning): 성공적으로 실행된 질의 패턴을 "recipes"로 학습하고 캐싱합니다. 학습된 레시피는 LLM(Large Language Model)의 추론 없이 직접 재사용될 수 있어 반복적인 질의의 성능과 효율성을 향상시킵니다. 스키마 변경 시 레시피는 자동으로 만료됩니다.

코어 방법론 (How It Works):

API Agent의 동작 흐름은 다음과 같습니다:

5. 질의 수신: 사용자가 MCP 클라이언트를 통해 자연어 질의와 함께 X-Target-URL (대상 API URL) 및 X-API-Type (GraphQL 또는 REST) 등의 헤더를 포함하여 MCP 서버에 요청을 보냅니다.
6. 스키마 인트로스펙션: MCP 서버는 X-Target-URL을 기반으로 대상 API로부터 스키마를 동적으로 분석(introspect)합니다.
7. 에이전트 질의 생성: 분석된 스키마와 사용자의 자연어 질의는 Agent (내부적으로 OpenAI Agents SDK 활용)로 전달됩니다. Agent는 이 정보를 바탕으로 LLM의 추론을 통해 적절한 API 호출(GraphQL 쿼리 또는 REST 요청) 계획을 수립합니다.
8. API 호출 및 데이터 수집: Agent는 생성된 계획에 따라 실제 대상 API를 호출하여 데이터를 가져옵니다.
9. DuckDB 저장 및 SQL 후처리: 가져온 API 데이터는 인메모리(in-memory) 분석 데이터베이스인 DuckDB에 저장됩니다. Agent는 사용자의 질의에 따라 LLM이 생성한 SQL 문을 DuckDB에 실행하여 필요한 데이터 후처리(필터링, 정렬, 집계, 조인 등)를 수행합니다.
10. 결과 반환: SQL 후처리된 결과는 MCP 서버를 통해 사용자에게 반환됩니다.

레시피 학습 과정 (Recipe Learning):

레시피 학습은 Agent가 LLM의 추론을 통해 API 호출 및 SQL 처리를 성공적으로 완료한 후 이루어집니다.

11. 실행 (Executes): LLM의 추론을 통해 API 호출 및 SQL 처리가 수행됩니다.
12. 추출 (Extracts): 성공적인 실행의 추적(trace) 정보를 기반으로 LLM이 매개변수화된 템플릿(parameterized template)을 추출합니다.
13. 캐싱 (Caches): 추출된 템플릿은 (API, 스키마 해시)를 키로 사용하여 캐시됩니다.
14. 도구 노출 (Exposes): 캐시된 레시피는 $r_{recipe_slug}$ 형태의 새로운 MCP 도구로 노출됩니다. 이 도구는 LLM의 추론 없이 직접 호출될 수 있으며, 클라이언트에게 tools/list_changed 이벤트를 통해 변경 사항이 통보됩니다.

기술 스택:

• FastMCP: MCP 서버 프레임워크.
• OpenAI Agents SDK: LLM 기반의 에이전트 구축 및 관리에 사용.
• DuckDB: 인메모리 분석 데이터베이스로 SQL 기반의 데이터 후처리에 사용.

설정 및 배포:

• OPENAI_API_KEY는 필수 환경 변수입니다.
• X-Target-URL, X-API-Type 헤더를 통해 대상 API를 지정하며, X-Target-Headers를 통해 인증 정보를 전달할 수 있습니다.
• X-Allow-Unsafe-Paths 및 X-Poll-Paths 헤더를 통해 위험한 작업 허용 목록 및 폴링 경로 패턴을 JSON 배열 문자열 형태로 설정할 수 있습니다.
• API_AGENT_ENABLE_RECIPES 설정을 통해 레시피 학습 기능을 활성화/비활성화할 수 있습니다.

이 시스템은 API 데이터의 접근성과 활용성을 극대화하며, 복잡한 데이터 요구사항을 자연어 인터페이스와 강력한 백엔드 처리 능력으로 충족시키는 것을 목표로 합니다.