API로 AI 에이전트를 내 앱에 연결해야 하는 이유

AI 에이전트 API란?

AI 에이전트 API를 쓰면 내 소프트웨어가 이미 만들어 둔 에이전트에 메시지를 보내고 답변을 받아 올 수 있어요. 에이전트는 지침, 지식, 모델, 도구, 안전 규칙을 그대로 유지해요. 앱은 질문만 보내면 돼요.

이 점이 일반 모델 API와 다른 부분이에요. 모델 API는 텍스트 생성만 제공하고 나머지는 모두 직접 해야 해요. 프롬프트, 문서 검색, 메모리, 요청 제한, 결제까지요. IMFA의 REST API는 이 모든 것을 이미 갖춘 관리형 에이전트를 에이전트 전용 키 하나로 제공해요.

에이전트는 AI 챗봇 빌더로 만들어요. API는 웹사이트, WhatsApp, Instagram, Facebook, Telegram, Discord, 음성 회선에 이어 에이전트가 답할 수 있는 또 하나의 창구예요.

언제 API로 에이전트를 연결해야 할까요?

대화가 내가 운영하는 서비스 안에서 이뤄진다면 API를 쓰세요.

• 내 앱이나 고객 포털에 정책을 잘 아는 도움말 어시스턴트가 필요하지만, 챗봇을 하나 더 관리하고 싶지는 않을 때.
• 백엔드가 주문 페이지, 예약 도구, 내부 대시보드 같은 다른 시스템의 질문에 답해야 할 때.
• 리드를 CRM으로 옮기고 싶을 때. API는 모든 채널에서 에이전트가 수집한 리드를 돌려주므로 정해진 주기로 동기화할 수 있어요.
• 리포트나 품질 검토를 위해 대화 기록이 필요할 때.

웹사이트에 채팅 버블만 필요하다면 한 줄짜리 임베드가 더 간단해요. API는 위젯이 아니라 내 제품이 인터페이스일 때 쓰는 방법이에요.

IMFA 에이전트 API의 작동 방식

기본 URL은 https://site.imfa.app/v1이에요. 모든 요청에는 에이전트 키가 필요하며, 브라우저나 모바일 번들이 아닌 신뢰할 수 있는 서버 코드에서 보내야 해요.

1. 에이전트를 게시하세요. IMFA에서 지침, 지식, 모델, 도구를 설정하고 실제 질문으로 테스트한 뒤 게시하세요. API는 게시된 버전으로 응답해요.
2. 키를 생성하세요. 에이전트의 API 화면이나 API 키 화면에서 키를 생성하세요. 키는 한 번만 표시되고 해시로만 저장돼요. IMFA_API_KEY 같은 서버 환경 변수에 보관하세요.
3. 채팅 요청을 보내세요. Authorization: Bearer <key>, 고유한 Idempotency-Key(8~128자), 그리고 message와 선택 항목인 sessionId가 담긴 JSON 본문으로 POST /v1/agents/{slug}/chat을 호출하세요. 응답에는 sessionId와 usage.credits가 함께 와요.
4. 대화를 이어 가세요. 첫 요청에서는 sessionId를 빼고, 이후에는 받은 값을 다시 보내세요. 에이전트가 맥락을 기억해요.
5. 기록을 확인하세요. GET /v1/agents/{slug}/sessions는 대화 목록을, GET /v1/agents/{slug}/sessions/{sessionId}/messages는 특정 대화를, GET /v1/agents/{slug}/leads는 수집된 리드를 돌려줘요. 목록은 기본 20개, 최대 100개까지 커서와 함께 반환돼요. GET /v1/agents로 키가 어떤 에이전트용인지 확인할 수 있어요.

제한도 명확해요. 메시지는 앞의 4,000자까지만 사용되고, 본문은 최대 64,000바이트이며, 오류는 유형별로 구분돼요(유효성 검사, 인증, 크레딧, 요청 제한, 서버). 429에는 Retry-After가 함께 오고, 402는 소유자의 크레딧이 소진됐다는 뜻이에요.

직접 만드는 대신 에이전트 API를 써야 하는 이유

몇 달간의 기반 작업을 건너뛸 수 있어요. 문서 검색, 세션, 요청 제한, 재시도, 크레딧 정산, 프롬프트 인젝션 방어 규칙이 이미 돌아가고 있어요. 팀은 HTTP 요청 하나만 작성하면 돼요.

에이전트 하나, 동작도 하나. 앱에 보이는 답변은 웹사이트와 WhatsApp의 답변과 같아요. 같은 에이전트니까요. IMFA에서 한 번만 수정하면 모든 채널에 반영돼요.

재시도가 안전해요. 멱등성 키 덕분에 네트워크 재시도 시 대화가 한 번 더 과금되지 않고 원래 답변이 반환돼요.

리드가 흩어지지 않아요. 어떤 채널에서 들어왔든 수집된 모든 리드를 엔드포인트 하나로 가져올 수 있어요.

그래도 완전히 직접 만들 수도 있어요. 모든 계층을 직접 소유해야 한다면 일반 모델 API가 그런 통제권을 주지만, 대신 직접 구축하고 운영해야 해요. Codex나 Claude Code 같은 코딩 에이전트는 MCP로 IMFA 에이전트를 관리할 수 있고, 서버는 REST 키로 고객에게 응답하면 돼요.

AI 에이전트 API에 대해 자주 묻는 질문

브라우저에서 AI 에이전트 API를 바로 호출할 수 있나요?

아니요. 키는 소유자의 크레딧을 사용하므로 신뢰할 수 있는 서버에만 있어야 해요. API는 브라우저에서의 광범위한 접근을 허용하지 않아요. 브라우저는 내가 운영하는 보호된 엔드포인트를 호출하고, 그 엔드포인트가 IMFA를 호출하게 하세요.

IMFA 에이전트 API 요청은 어떻게 인증하나요?

에이전트의 API 화면이나 API 키 화면에서 에이전트 전용 키를 생성한 뒤, 서버 코드에서 Authorization: Bearer YOUR_API_KEY를 보내세요. MCP 토큰은 다른 자격 증명이라 여기서는 쓸 수 없어요.

같은 API 대화를 어떻게 이어 가나요?

첫 채팅 요청에서는 sessionId를 빼고, API가 돌려준 sessionId를 저장해 다음 메시지와 함께 보내세요. 웹사이트나 채널 대화의 세션 ID는 읽기 전용이라 API 대화를 이어 가는 데 쓸 수 없어요.

채팅에 Idempotency-Key가 필요한 이유는 무엇인가요?

재시도를 안전하게 해 주기 때문이에요. 같은 키로 똑같이 재시도하면 새 대화가 생기지 않고 같은 결과가 반환돼요. 새 메시지마다 새 키를 쓰세요.

에이전트 API가 내 지식과 도구를 사용하나요?

네. 게시된 에이전트를 지침, 모델, 지식, 스킬, 도구, 안전 규칙과 함께 호출해요. 답변은 게시된 설정, 크레딧, 현재 서비스 한도에 따라 달라질 수 있어요.

API가 요청 제한에 걸리거나 크레딧이 떨어지면 어떻게 되나요?

요청 제한에 걸리면 Retry-After 헤더와 함께 429가, 소유자의 크레딧이 소진되면 402가 반환돼요. 연동 코드에서 문서화된 모든 상태 코드를 처리하세요.