메타 정보 API 개발

Adapter Agent 서버에서 구현한 Capability와 오류 정보를 공유하기 위해 Adapter Agent API의 Agent Capability를 구현해야 합니다.

주의
Agent Capability 구현 시 모든 Adapter Agent 서버를 반드시 구현해야 합니다.

구현한 Capability 정보 제공하기

Adapter Agent 서버는 getAgentCapabilities API를 통해 카카오 i 서비스 시스템에 자신이 구현한 Capability 목록을 제공해야 합니다. 카카오 i 서비스 시스템은 이 정보가 있어야만 각 Adapter Agent 서버가 구현한 Capability에 맞는 동작을 수행할 수 있습니다. 만약 여러 법인이 하나의 Adapter Agent 서버에서 처리될 경우(ex. 그룹사의 Adapter Agent 서버를 통합 구현 시)에는 orgLoginTypeId에 해당하는 법인의 capabilities를 반환합니다.

카카오 i 서비스 시스템에서 getAgentCapabilities API를 호출하는 시점은 다음과 같습니다.

• 카카오 i 계정 관리자 사이트 접근 시점
• 그 외 Adapter Agent 서버가 구현한 Capability 정보가 필요한 시점

API 작업 흐름

카카오 i 서비스 시스템에서 getAgentCapabilities API를 호출하는 작업 흐름은 다음과 같습니다.

그림Capability 정보 제공 흐름

1. Adapter Agent 서버가 구현한 Capability 목록이 필요할 때, 카카오 i 계정 서버가 Adapter 서버를 호출합니다.

2. getAgentCapabilities 요청이 Adapter 서버로 전달됩니다.

3. Adapter 서버가 Adapter Agent 서버의 getAgentCapabilities를 호출합니다.

4. Adapter Agent 서버는 자신이 구현한 Capability 목록을 반환합니다.

Adapter Agent 서버 동작 예제

Adapter Agent 서버의 동작 예제는 다음과 같습니다.

1. 해당 Adapter Agent 서버가 어떤 Capability를 구현하고 있는지 파악합니다.

2. API 레퍼런스의 응답 포맷에 맞춰 Capability를 반환합니다.

정보 활용 예시

getAgentCapabilities API에서 제공하는 정보의 활용 예시는 다음과 같습니다.

• 관리자가 사용하는 카카오 i 계정 관리자 시스템의 계정 연동 설정 메뉴에서 Adapter Agent가 지원하는 Capability 목록 노출
• 카카오 i 서비스 시스템에서 각 Adapter Agent 서버가 어떤 Capability를 구현했는지 파악하여 연동 개발 자동화 및 연동 장애 감지에 활용

그림계정 연동 설정

오류 정보 수신하기

고객사 시스템과 카카오 i 서비스 시스템 간 연동은 카카오 i 서비스 시스템의 단방향 API 호출 방식입니다. 그러므로 Adapter Agent API의 응답이 반환된 이후 오류가 발생했을 때, Adapter Agent 서버는 이를 감지할 수 없습니다.
이러한 단점을 보완하기 위해 Adapter Agent API에는 오류정보를 수신하는 reportError API가 정의되어 있으며, Adapter Agent 서버에 해당 API를 구현하시면 오류 정보를 수신할 수 있습니다. 고객사는 이 정보를 기업의 로그 시스템에 기록하여 오류 분석 용도로 활용할 수 있습니다.

카카오 i 서비스 시스템에서 reportError API를 호출하는 시점은 다음과 같습니다.

• Adapter Agent API의 응답이 응답 규격에 맞지 않는 경우
• Adapter Agent API의 응답을 받아 카카오 i 서비스 시스템이 로직을 처리하는 도중 오류가 발생했을 경우
• 그 외 Adapter Agent 서버에게 오류를 전파할 필요가 있는 경우

API 작업 흐름

카카오 i 서비스 시스템에서 reportError API를 호출하는 작업 흐름은 다음과 같습니다.

그림reportError 호출 작업 흐름

1. Adapter Agent API의 응답이 API 사양과 일치하지 않는 경우, 카카오 i 서비스 시스템에서 오류가 발생합니다.

   • 이때 Adapter Agent 서버는 Adapter 서버에 정상 응답을 반환했으므로 고객사 서버는 오류 발생을 알 수 없습니다.

2. 카카오 i 서비스 시스템은 reportError API를 호출하여 고객사 서버에 오류 정보를 전송합니다.
   

안내
API별 상세 레퍼런스는 카카오 i 계정 API 레퍼런스 문서를 참고하시기 바랍니다.