에이전트와 외부 서비스 연결

외부 서비스는 에이전트의 손과 발이다

에이전트가 실제 제품에서 쓸모 있어지는 순간은 외부 서비스와 연결될 때입니다. 이메일을 읽고, 캘린더 일정을 확인하고, 문서 목록을 가져오고, 데이터베이스에서 고객 정보를 조회할 수 있어야 작업이 됩니다.

하지만 연결이 많아질수록 위험도 커집니다. 에이전트가 메일을 잘못 보내거나, 문서를 삭제하거나, 고객 데이터를 과도하게 읽는 상황을 막아야 합니다. 외부 서비스 연결의 핵심은 더 많은 권한을 주는 것이 아니라, 필요한 권한만 정확히 주는 것입니다.

API는 도구의 입구다

이메일, 캘린더, 문서 저장소, 데이터베이스는 모두 도구로 감쌀 수 있습니다. 중요한 것은 모델에게 서비스 전체를 열어주는 것이 아니라, 제한된 API만 제공하는 것입니다.

예를 들어 문서 서비스라면 다음처럼 도구를 나눌 수 있습니다.

• 문서 목록 조회

• 특정 문서 내용 읽기

• 문서 요약 생성

• 폴더 이동 제안

• 문서 이름 변경

• 문서 삭제

이 중 문서 목록 조회와 내용 읽기는 비교적 낮은 위험입니다. 반면 이름 변경, 이동, 삭제는 사용자 업무에 직접 영향을 줍니다. 따라서 같은 문서 서비스라도 도구별로 권한과 승인 조건을 다르게 설계해야 합니다.

좋은 도구 API는 입력이 명확합니다. document_id, folder_id, date_range, query처럼 필요한 값만 받습니다. 자연어 전체를 그대로 API에 넘기지 말고, 에이전트가 구조화된 값으로 바꾼 뒤 실행하게 해야 합니다.

OAuth로 사용자 권한을 위임받기

외부 서비스를 연결할 때는 보통 OAuth를 사용합니다. OAuth는 사용자의 비밀번호를 에이전트 서비스에 직접 맡기지 않고, 특정 범위의 접근 권한만 위임하는 방식입니다.

흐름은 단순합니다. 사용자가 외부 서비스 로그인 화면에서 권한을 승인합니다. 서비스는 에이전트 애플리케이션에 토큰을 발급합니다. 에이전트는 이 토큰으로 API를 호출합니다.

여기서 중요한 것은 토큰의 범위입니다. 이메일 전체 권한이 아니라 메일 읽기 권한만 받을 수 있습니다. 캘린더도 일정 읽기, 일정 생성, 일정 삭제를 분리해야 합니다. 처음부터 모든 권한을 요구하면 보안 위험도 커지고 사용자 신뢰도 낮아집니다.

토큰은 암호화해서 저장해야 합니다. 만료 시간도 관리해야 합니다. 토큰 갱신에 실패하면 에이전트가 임의로 우회하지 말고 사용자에게 재연결을 요청해야 합니다.

읽기와 쓰기를 반드시 나눈다

외부 서비스 도구는 조회, 생성, 수정, 삭제로 나누어 설계하는 것이 좋습니다. 이 구분은 권한 관리의 기준이 됩니다.

조회 작업은 정보를 가져옵니다. 문서 목록 읽기, 일정 조회, 고객 정보 검색이 여기에 속합니다. 생성 작업은 새 항목을 만듭니다. 임시 문서 작성, 초안 메일 생성, 일정 초안 생성이 예입니다. 수정 작업은 기존 데이터를 바꿉니다. 제목 변경, 폴더 이동, 태그 추가가 포함됩니다. 삭제 작업은 되돌리기 어렵기 때문에 가장 높은 수준의 확인이 필요합니다.

특히 쓰기 작업은 바로 실행하지 않는 편이 안전합니다. 에이전트가 먼저 변경안을 만들고, 사용자가 확인한 뒤 실행하게 해야 합니다. 6장에서 다룬 승인 흐름은 여기서 실제 도구 권한과 연결됩니다.

로그는 나중을 위한 안전장치다

에이전트가 외부 서비스를 호출하면 반드시 기록을 남겨야 합니다. 로그는 단순한 디버깅 자료가 아닙니다. 문제가 생겼을 때 누가, 언제, 어떤 권한으로, 어떤 도구를, 어떤 입력값으로 실행했는지 확인하는 감사 추적의 기반입니다.

최소한 다음 항목은 남겨야 합니다.

• 사용자 ID

• 작업 ID

• 호출한 도구 이름

• 입력 파라미터

• 실행 결과 상태

• 승인 여부와 승인자

• 실행 시각

• 오류 메시지

단, 로그에 민감한 원문을 그대로 저장하면 안 됩니다. 이메일 본문, 고객 개인정보, 토큰 값은 마스킹하거나 별도 보안 저장소에서 관리해야 합니다. 로그는 남겨야 하지만, 로그 자체가 새로운 위험이 되어서는 안 됩니다.

실습: 문서 정리 에이전트 설계

문서 정리 에이전트를 만들어 봅시다. 목표는 문서 저장소를 읽고, 요약과 분류를 제안한 뒤, 사용자가 승인하면 정리 작업을 실행하는 것입니다.

먼저 도구를 세 개로 제한합니다. list_documents는 문서 목록을 가져옵니다. read_document는 선택한 문서 내용을 읽습니다. propose_organization은 요약, 태그, 이동할 폴더를 제안합니다. 여기까지는 읽기와 제안 단계입니다.

실제 변경 도구는 따로 둡니다. move_document, rename_document, add_tag는 쓰기 작업입니다. 이 도구들은 사용자 승인 없이는 실행되지 않아야 합니다.

작업 흐름은 다음과 같습니다.

1. 최근 30일 문서 목록을 조회한다.

2. 문서 제목과 일부 내용을 읽는다.

3. 문서를 업무, 회의록, 계약, 참고자료 등으로 분류한다.

4. 이동할 폴더와 새 태그를 제안한다.

5. 사용자에게 변경안을 보여준다.

6. 승인된 항목만 실행한다.

7. 실행 결과와 실패 항목을 로그로 남긴다.

이 구조의 장점은 명확합니다. 에이전트는 많은 문서를 빠르게 검토하지만, 실제 변경은 사람이 통제합니다. 외부 서비스 연결은 자동화의 힘을 키우는 동시에 책임의 경계도 분명히 해야 합니다. 좋은 에이전트는 마음대로 움직이는 시스템이 아니라, 허용된 권한 안에서 기록을 남기며 일하는 시스템입니다.