API: 에이전트가 외부 시스템과 연결되는 통로
AI 에이전트가 "실제로 일한다"는 말은, 단순히 답을 잘 만드는 것이 아니라 외부 시스템을 직접 움직인다는 뜻입니다. 일정을 등록하고, 이메일을 보내고, 데이터를 조회하고, 결제를 확인하는 작업은 모두 다른 서비스와 연결되어야 가능합니다. 이 연결의 핵심이 바로 API입니다.
API란 무엇인가
API(Application Programming Interface)는 프로그램과 프로그램이 서로 대화할 수 있도록 정해 둔 "연결 창구"입니다.
사람이 웹사이트에서 버튼을 누르면 화면이 바뀌는 것처럼, 프로그램도 다른 프로그램에게 "이 작업을 해 달라"고 요청할 수 있습니다. 다만 사람 대신 코드가 요청을 보낼 뿐입니다.
조금 더 쉽게 설명해 보겠습니다.
- 날씨 앱을 열면, 앱은 기상청 서버에 "서울의 현재 기온을 알려줘"라고 요청합니다.
- 기상청 서버는 데이터를 정해진 형식으로 돌려줍니다.
- 앱은 그 데이터를 화면에 보여 줍니다.
여기서 앱과 기상청 서버를 연결해 주는 창구가 API입니다. API는 "요청을 이렇게 보내면, 이런 형식으로 답을 준다"는 약속입니다.
에이전트도 같은 원리로 작동합니다. 사람이 화면을 클릭하는 대신, 에이전트가 API를 통해 직접 요청을 보냅니다.
에이전트가 API를 사용하는 흐름
에이전트가 외부 시스템과 연결될 때는 보통 다음 순서로 진행됩니다.
- 사용자의 요청을 이해합니다.
- 어떤 시스템이 필요한지 판단합니다.
- 해당 시스템의 API 형식에 맞춰 요청을 만듭니다.
- 응답을 받아 다음 단계에 활용합니다.
예를 들어 "내일 오후 3시에 팀 회의 일정 잡아줘"라는 요청이 들어오면 다음과 같이 처리합니다.
- 날짜와 시간을 추출합니다.
- 구글 캘린더 API를 사용해야 한다고 판단합니다.
- 일정 생성 형식에 맞춰 제목, 시간, 참석자 정보를 정리합니다.
- 캘린더 서버에 요청을 보냅니다.
- 성공 응답을 확인합니다.
대화형 AI는 일정을 "추천"하는 데 그치지만, 에이전트는 API를 통해 실제로 일정을 "등록"합니다.
차이는 API를 통해 실제 시스템을 움직일 수 있느냐에 있습니다.
API를 사용하려면 인증이 필요하다
외부 시스템은 아무 프로그램이나 받아들이지 않습니다. "이 요청을 보낸 사 람이 누구인지"를 확인해야 합니다. 이를 인증이라고 합니다. 대표적인 방식은 세 가지입니다.
1. API 키
서비스에서 발급받은 고유한 문자열을 함께 보내는 방식입니다. 요청할 때마다 이 키를 포함시키면 "허가된 사용자"로 인식됩니다.
이러한 방식은 구현이 간단하지만, 키가 유출되면 누구나 사용할 수 있다는 단점이 있습니다. 따라서 공개 데이터 조회나 간단한 서비스 연동에 주로 사용됩니다.
2. OAuth
사용자가 직접 로그인해 "이 앱이 내 데이터를 사용해도 된다"고 승인하는 방식입니다. 구글 계정으로 다른 앱에 로그인할 때 활용하는 인증 방식이 바로 OAuth입니다.
이 방식은 비밀번호를 외부에 넘기지 않아도 되고, 접근 권한을 세부적으로 조절할 수 있어 보안성이 높습니다.
3. 웹훅 (Webhook)
웹훅은 요청을 보내는 방식이 아니라, 특정한 사건(이벤트)이 발생했을 때 알림을 받는 구조입니다. 쉽게 말하면 "상대가 먼저 알려주는 구조"라고 이해하면 됩니다.
예를 들어 결제가 완료되면 결제 시스템이 자동으로 우리 서버에 "결제 완료" 신호를 보냅니다. 에이전트는 이 신호를 받아 후속 작업을 수행합니다.
실제 AI 에이전트의 업무 수행 예시
상황: "고객이 미팅을 확정하면 캘린더에 등록하고 슬랙으로 알림 보내기"
처리 과정은 다음과 같습니다.
- 이메일이나 폼에서 미팅 날짜와 시간을 추출합니다.
- OAuth로 연결된 구글 캘린더 API에 일정 생성 요청을 보냅니다.
- 일정 생성이 성공하면 슬랙 API에 메시지 전송 요청을 보냅니다.
- 팀 채널에 자동으로 알림이 올라갑니다.
이 모든 과정은 사람이 직접 화면을 조작하지 않아도 자동으로 이루어집니다. 이것이 에이전트의 "실행 능력"입니다.
좋습니다. 해당 부분을 더 실무적으로, 그리고 교육자료답게 밀도 있게 다시 작성해 보겠습니다.
에러 코드 이해하기
API를 연동하다 보면 숫자로 된 상태 코드(Status Code)를 자주 보게 됩니다. 이 숫자는 "요청이 어떻게 처리되었는지"를 한 줄로 요약한 결과입니다. 겉으로는 차갑게 보이지만, 사실은 문제를 진단하는 가장 중요한 단서입니다.
1) 200번대: 성공
- 200 OK: 요청이 정상적으로 처리되었습니다.
- 201 Created: 새로운 데이터가 성공적으로 생성되었습니다.
에이전트를 설계할 때는 단순히 "응답이 왔다"가 아니라, 200번대인지 확인하는 절차를 반드시 넣어야 합니다. 그렇지 않으면 실패했는데도 성공한 것처럼 다음 단계로 넘어가는 문제가 생깁니다.
2) 400번대: 내가 잘못 보낸 경우
400번대는 "요청 자체에 문제가 있다"는 의미입니다.
- 400 Bad Request: 요청 형식이 잘못됨 (필수 필드 누락, 형식 오류 등)
- 401 Unauthorized: 인증 정보가 없거나 잘못됨
- 403 Forbidden: 인증은 되었지만 권한이 없음
- 404 Not Found: 잘못된 주소(엔드포인트) 요청
- 429 Too Many Requests: 호출 횟수 제한 초과
실무에서 가장 많이 겪는 것은 401, 403, 429입니다.
자주 발생하는 상황은 다음과 같습니다.
- 토큰이 만료되었는데 재발급 로직이 없다면 401이 발생합니다.
- 읽기 권한만 있는데 쓰기 요청을 하면 403이 발생합니다.
- 테스트 중 반복 호출을 많이 하면 429가 발생합니다.
400번대 에러는 대부분 요청을 다시 설계하면 해결되는 문제입니다.
3) 500번대: 서버 측 문제
- 500 Internal Server Error: 서버 내부 오류
- 502/503: 서버가 일시적으로 과부하이거나 다운된 상태
500번대 에러는 사용자가 고칠 수 있는 문제가 아닙니다. 이를 처리하기 위해서는 다음과 같은 전략이 필요합니다.
- 자동 재시도 로직(예: 3회까지 재요청)
- 일정 시간 후 재호출
이렇게 에이전트는 "한 번 요청하고 끝"이 아니라, 실패했을 때 어떻게 복구할지까지 설계해야 합니다.
다음 내용이 궁금하다면?
코드프렌즈 PLUS 멤버십 가입 or 강의를 등록해 주세요!