소속팀: Developer팀 작성자: 유수영
상담은 끝났는데, 보고서가 열리지 않는다면?
AI Agent의 품질은 답변을 만드는 순간에만 결정되지 않습니다. 모델 인증이 유지되고, 생성한 문서를 필요한 사람에게 전달할 수 있어야 합니다. 이번 글은 비밀정보 조회와 파일 저장을 공통화한 설계를 바탕으로 그 연결을 살펴봅니다.
| 읽으면서 풀어볼 질문 | 이번 글의 관점 |
|---|---|
| API 키를 어디에 둘까? | 일반 설정과 인증 정보를 나누기 |
| 서비스마다 AWS 코드를 작성해야 할까? | 공통 접근 계층으로 연결하기 |
| 보고서 다운로드는 어떻게 제한할까? | 사용자 확인 후 짧은 서명 URL 발급하기 |
| 키가 바뀌어도 상담을 이어갈 수 있을까? | 조회, 연결 갱신, 실제 호출을 함께 확인하기 |
1. 개요: 답변 뒤에 남는 운영 문제 🤖
상담 Agent를 연결할 때는 모델 응답부터 확인하기 쉽습니다. 질문을 이해하고, 근거를 찾고, 자연스럽게 답하면 첫 단계는 통과입니다. 그런데 보고서 저장과 다운로드까지 붙이면 고민의 범위가 넓어집니다.
모델 API 키가 바뀌면 어느 연결을 새로 만들어야 할까요? 다운로드 버튼은 누가 눌러도 같은 문서를 열어도 될까요? 운영 환경에서만 저장이 실패하면 어디부터 확인해야 할까요?
기존 공통화 설계가 다루던 문제도 여기에 있습니다. 서비스마다 인증과 저장 코드를 흩어 놓으면 변경 지점이 늘어납니다. 공통 계층에서 연결 방식을 관리하고, 서비스에는 업무 판단을 남기는 편이 이해하기 쉽습니다.
그림 1. 모델과 저장소를 연결하는 Agent의 구성요소를 표현한 AI 생성 일러스트입니다.
이 글에서는 상담 결과를 짧은 문서로 저장하는 상황을 예로 듭니다. 모델 API 키는 AWS Secrets Manager에서 읽습니다. 문서는 Amazon S3에 보관하고, 권한을 확인한 사용자에게 전달합니다.
코드는 설계의 핵심을 확인하는 작은 예제입니다. 실제 프로젝트의 이름이나 운영 값을 사용하지 않습니다. 버킷 생성, 사용자 인증, 업무 DB 구현은 배포 환경에서 별도로 연결합니다.
2. 설정과 비밀정보를 먼저 나누기 🗂️
처음에는 모든 값을 하나의 설정 묶음으로 읽기 쉽습니다. 하지만 로그 수준과 모델 API 키는 바꾸는 주체도, 노출의 영향도 다릅니다. 같은 방식으로 취급하면 문제를 추적할 때 필요한 값까지 숨기게 됩니다.
반대로 설정 전체를 출력하면 인증 정보까지 로그에 남을 수 있습니다. 그래서 값의 성격을 먼저 구분합니다.
| 값 | 분류 | 관리할 때의 기준 |
|---|---|---|
| 모델 API 키 | 비밀정보 | 조회 권한과 교체 절차를 제한 |
| DB 비밀번호 | 비밀정보 | 실제 DB 계정 변경과 함께 관리 |
| 버킷 이름, AWS 리전 | 일반 설정 | 환경별 차이를 명시 |
| 모델 종류, 로그 수준 | 일반 설정 | 배포 설정에서 변경 |
| 내부 서비스 주소 | 민감할 수 있는 설정 | 인증 정보 여부와 별개로 공개 범위 판단 |
| 시크릿 식별자 | 연결 설정 | 값 자체 대신 조회할 대상을 지정 |
개발, 검증, 운영에서는 시크릿과 저장 공간을 분리합니다. 구분 기준은 이름만이 아닙니다. 개발용 실행 역할로 운영 비밀정보를 읽을 수 없어야 합니다.
💡 비밀정보가 아닌 값도 무조건 공개해도 된다는 뜻은 아닙니다. 내부 주소나 버킷 이름은 환경 구조를 드러낼 수 있습니다. 설정 분류와 로그 공개 정책은 따로 정합니다.
서비스에는 필요한 기능만 보여주기
기존 저장소 설계는 공통 인터페이스와 구현체를 나누는 방향입니다. 서비스는 “상담 보고서를 저장한다”는 의도를 전달합니다. 공통 계층은 AWS 클라이언트, 저장 위치, 암호화 옵션을 처리합니다.
| 서비스가 맡을 일 | 공통 계층이 맡을 일 |
|---|---|
| 어떤 내용을 문서로 만들지 결정 | S3 업로드와 다운로드 호출 |
| 누가 문서를 볼 수 있는지 판단 | 정해진 객체 버전으로 서명 |
| 산출물 상태를 업무 DB에 기록 | 저장 결과와 오류를 일정한 형태로 반환 |
| 사용자에게 보여줄 안내 선택 | 시크릿 조회와 연결 초기화 |
공통화했다고 업무 권한까지 자동으로 해결되지는 않습니다. 저장 기능은 상담 담당자의 역할이나 조직 관계를 알지 못합니다. 권한 판단 결과를 저장소 호출 앞에 두는 이유입니다.
3. AWS에 접속하는 자격과 모델 API 키는 다릅니다 🔑
Agent가 Secrets Manager에 접근할 때도 AWS 인증이 필요합니다. 여기에 장기 AWS 액세스 키를 다시 코드로 넣으면 출발점이 복잡해집니다. 운영에서는 실행 환경에 부여한 IAM 역할과 임시 자격 증명을 우선 사용합니다.
SDK가 찾는 AWS 자격 증명과 Secrets Manager에서 읽는 모델 API 키는 별개입니다. 전자는 AWS 서비스에 접근할 때 사용합니다. 후자는 모델 제공자에게 요청할 때 사용합니다. 역할 기반 접근은 AWS IAM 권장 사항을 기준으로 설계합니다.

그림 2. 설정은 대상을 정하고, 실행 역할은 AWS 접근 권한을 제공합니다. 편집 가능한 draw.io 원본도 함께 관리합니다.
예제 1. 자격 증명을 코드에 넣지 않는 클라이언트 생성
|
import boto3 |
|---|
여기서는 액세스 키를 인자로 받지 않습니다. 실제 자격 증명은 Boto3의 기본 조회 체계를 사용합니다. 개발 환경과 배포 환경에 맞는 공급자를 설정해야 합니다.
시간 제한과 재시도 횟수는 예시입니다. 한 번의 읽기 제한이 전체 사용자 요청의 제한 시간과 같지는 않습니다. 재시도와 모델 응답까지 포함한 전체 처리 시간도 서비스에서 관리합니다.
클라이언트는 요청마다 새로 만들기보다 애플리케이션 수명에 맞춰 주입합니다. 이렇게 하면 테스트에서 SDK 대역으로 바꾸기도 쉽습니다. AWS 자격 증명 갱신과 모델 API 키 갱신은 각각 확인합니다.
4. 시크릿은 읽은 뒤에도 검증합니다 🧩
Secrets Manager 조회가 성공했다고 모델 연결이 준비된 것은 아닙니다. 값이 비어 있거나, 예상한 JSON 구조와 다를 수 있습니다. 잘못된 값을 빈 문자열로 바꾸면 문제는 나중에 모델 인증 실패로 나타납니다.
그래서 조회 경계에서 형식을 확인합니다. 필수 시크릿을 읽지 못하면 해당 기능을 준비 완료로 표시하지 않습니다. 비밀정보를 감춘 오류와 요청 식별자로 원인을 추적합니다.
예제 2. API 키와 조회 버전을 함께 받기
|
import json |
|---|
이 예제의 입력 규약은 api_key를 가진 JSON 문자열입니다. 바이너리 시크릿을 처리하는 예제는 아닙니다. AWS 권한 오류나 통신 오류는 호출자에게 전달하고, 서비스 경계에서 안전한 안내로 바꿉니다.
repr=False는 객체를 출력할 때 키가 보이지 않도록 돕습니다. 직렬화나 사전 변환까지 막아주는 기능은 아닙니다. 객체 전체를 로그나 추적 속성에 넣지 않는 원칙이 필요합니다.
공식 Python 시크릿 조회 가이드는 캐시 활용도 안내합니다. 캐시는 조회 비용과 지연을 줄이지만, 교체된 값을 반영하는 시점을 늦출 수 있습니다. 캐시 만료 시간과 갱신 실패 시 동작을 함께 정합니다.
| 캐시 상황 | 애플리케이션에서 정할 행동 |
|---|---|
| 유효 기간 안의 값 | 승인된 캐시 값을 사용 |
| 만료되어 새 값을 읽음 | 형식 확인 후 새 연결에 적용 |
| 갱신 요청이 실패함 | 제한된 재시도 후 실패 상태 기록 |
| 이전 값 사용이 필요한 업무 | 허용 시간과 중단 조건을 별도로 합의 |
“오류가 나면 이전 값을 계속 사용한다”는 무기한 정책은 피합니다. 이미 폐기된 키를 반복 호출하면 장애가 더 오래 이어집니다. 다만 모든 서비스에 같은 캐시 시간을 적용할 필요도 없습니다.
5. 문서를 저장할 때는 주소보다 소유 관계가 먼저입니다 📎
상담 보고서가 만들어지면 저장 위치부터 정하고 싶어집니다. 하지만 다운로드 시점에 더 필요한 정보는 따로 있습니다. “어느 조직의 누가 볼 수 있는 문서인가?”라는 관계입니다.
객체 키에 조직 식별자가 있다고 권한 검사가 끝나지는 않습니다. 키는 저장 주소입니다. 업무 DB의 산출물 기록에 소유자와 공개 범위를 연결해야 합니다.
사용자 화면에는 산출물 ID만 전달해도 됩니다. 서버가 해당 ID로 기록을 찾고, 로그인 사용자의 권한을 확인합니다. 버킷과 객체 키는 서버가 관리하는 기록에서 가져옵니다.
그림 3. 문서의 근거와 접근 대상을 확인하는 장면을 표현한 AI 생성 일러스트입니다.
키에는 탐색에 필요한 최소 정보만
S3는 객체 키를 기준으로 저장하는 평면 구조입니다. 슬래시는 폴더처럼 보이게 하는 구분자이며, 그 자체가 권한 경계는 아닙니다. 이 차이는 S3 객체 키 설명에서 확인할 수 있습니다.
| artifacts/{tenant_id}/{yyyy-mm-dd}/{artifact_id} |
|---|
위 규칙은 샘플입니다. tenant_id는 고객 이름이 아닌 서버가 관리하는 불투명 식별자를 뜻합니다. 사용자가 입력한 파일 이름이나 상담 내용을 그대로 키에 넣지 않습니다.
예제 3. 산출물 기록과 키 만들기
|
import re |
|---|
산출물 ID와 생성일은 서버에서 먼저 정하고, 재시도에도 같은 값을 사용합니다. 매번 새 ID를 만들면 같은 보고서가 여러 개 생길 수 있습니다. 키 규칙은 조회 편의를 위한 것이고, 재시도 정책은 별도로 설계합니다.
6. 업로드가 끝나면 버전까지 기록합니다 📦
사용자가 받은 문서와 나중에 확인한 문서가 같아야 할 때가 있습니다. 같은 키에 다른 내용이 저장되면 주소만으로는 구분하기 어렵습니다. 이 예제는 버전 관리가 활성화된 일반 S3 버킷을 사용합니다.
저장 결과의 버전 ID를 업무 기록에 남깁니다. 이후 다운로드에서도 같은 버전을 지정합니다. 버전 관리는 S3 Versioning 안내를 참고합니다.
예제 4. 작은 상담 문서를 조건부로 업로드하기
|
import base64 |
|---|
2 MiB 제한은 이 글의 작은 문서 예제에만 적용합니다. 큰 파일에는 스트리밍과 멀티파트 업로드 등 다른 처리 방식이 필요합니다. 텍스트 이외의 형식은 허용 형식과 콘텐츠 유형도 따로 정합니다.
IfNoneMatch=”*”는 같은 키가 있을 때 덮어쓰지 않도록 요청합니다. 이미 존재하면 412, 업로드와 충돌하는 작업이 있으면 409가 발생할 수 있습니다. 동작과 요청 옵션은 PutObject API를 기준으로 확인합니다.
412를 무조건 성공으로 바꾸지는 않습니다. 기존 객체가 이번 요청의 결과인지 버전과 해시로 확인해야 합니다. 409와 응답 유실도 구분하고, 같은 요청을 다시 처리할 수 있는 절차를 둡니다.
예제는 별도 KMS 키를 사용하는 저장 시 암호화를 요청합니다. 기본 암호화와 선택 가능한 방식은 S3 KMS 암호화 안내를 참고합니다. 암호화되어 있어도 잘못된 사용자에게 다운로드를 허용하면 문서는 노출됩니다.
S3 저장과 업무 DB 기록은 한 번에 묶이지 않습니다
업로드는 성공했지만 산출물 기록 저장이 실패할 수 있습니다. 이때 저장 함수를 다시 부르는 것만으로 정합성이 해결되지는 않습니다. 버전 확인 실패로 예외가 나도 객체는 이미 저장되었을 수 있습니다.
| 산출물 상태 | 사용자 화면 | 후속 처리 |
|---|---|---|
| 저장 준비 | 문서 생성 중 | 예약한 ID로 업로드 |
| 객체 저장 완료 | 아직 다운로드 제한 | 버전과 소유 관계 기록 |
| 공개 준비 완료 | 다운로드 버튼 표시 | 권한 확인 후 전달 |
| 기록 불일치 | 처리 지연 안내 | 객체 조회 후 기록 복구 또는 정리 |
✅ 재처리 작업은 요청 ID와 산출물 ID를 함께 추적합니다. 저장된 객체를 찾을 근거를 남기고, 오래된 미완료 항목을 정리합니다. 무조건 재업로드하는 방식보다 사용자가 보는 상태를 설명하기 쉽습니다.
7. 다운로드 URL은 권한 확인 뒤에 발급합니다 🔗
서명 URL은 브라우저가 문서를 직접 받도록 해줍니다. 그만큼 서버를 통과하는 파일 전송량을 줄일 수 있습니다. 대신 URL을 가진 사람이 문서를 받을 수 있다는 특성을 이해해야 합니다.
URL은 기본적으로 일회용이 아닙니다. 만료 전 재사용할 수 있고, 임시 AWS 자격 증명이 먼저 끝나면 더 일찍 만료될 수 있습니다. 자세한 유효 조건은 S3 서명 URL 안내에 설명되어 있습니다.
예제 5. 서버가 조회한 산출물에만 URL 발급하기
|
def authorize_artifact( |
|---|
이 예제의 권한 규칙은 같은 조직의 문서 소유자만 허용하는 것입니다. 실제 상담 조직의 공동 열람이나 관리자 권한은 별도 정책으로 확장합니다. tenant_id와 user_id는 인증된 세션에서 가져옵니다.
artifact도 요청 본문을 그대로 변환한 객체여서는 안 됩니다. 서버가 관리하는 산출물 기록을 조회하고, 공개 준비 상태까지 확인한 결과여야 합니다. 버킷은 배포 설정에서 결정합니다.
300초는 서비스 정책 예시이며 S3의 최대 유효 시간을 뜻하지 않습니다. 서명 문자열 생성 성공만으로 객체 존재나 실제 읽기 권한이 확인되지는 않습니다. SDK의 URL 생성 방식은 Boto3 서명 URL 가이드도 참고합니다.
📌 URL 전체를 로그, 분석 이벤트, 상담 대화 이력에 남기지 않습니다. 추적에는 산출물 ID, 요청 ID, 발급 결과를 사용합니다. 즉시 접근 철회나 매번 권한 재검사가 필요하면 서버 중계 방식을 검토합니다.
예제 6. 서버가 직접 받을 때도 같은 버전 사용하기
|
def download_report( |
|---|
읽기 결과는 업무 DB에 저장한 SHA-256과 비교합니다. ETag를 항상 파일의 MD5로 해석하지 않습니다. 이 코드는 작은 문서를 메모리로 받는 예제이며, 대용량 전송용 구현은 아닙니다.
특정 버전 조회에는 s3:GetObjectVersion 권한이 필요합니다. 암호화된 객체에는 해당 KMS 키 사용 권한도 함께 검토합니다. 요청별 조건은 GetObject API를 기준으로 맞춥니다.
8. 키 교체는 새 값을 저장하는 것으로 끝나지 않습니다 🔄
모델 API 키가 바뀌면 시크릿 값만 고치면 될 것처럼 보입니다. 하지만 실행 중인 클라이언트가 예전 값을 계속 사용할 수 있습니다. DB 연결 풀과 시크릿 캐시도 함께 살펴봐야 합니다.
운영 관점에서는 “새 값을 읽었다”와 “새 값으로 호출했다”를 나눠 봅니다. 전자는 조회 경로의 확인입니다. 후자는 실제 인증과 연결이 준비되었다는 확인입니다.
이 구분이 있어야 장애 지점을 좁힐 수 있습니다. 상담 요청을 받기 전에 필요한 연결을 확인합니다. 비밀 값 자체를 출력해서 확인하는 방법은 사용하지 않습니다.
그림 4. 연결 갱신과 운영 상태를 확인하는 AI 생성 일러스트입니다.

그림 5. 신·구 인증 정보의 동시 사용을 지원하는 서비스에서 적용할 수 있는 교체 흐름입니다.
AWS의 시크릿 교체 설명처럼, 교체는 저장된 값과 대상 서비스의 인증 정보를 함께 바꾸는 일입니다. 새 API 키를 발급하지 않고 저장소 문자열만 바꾸면 인증은 실패합니다. 교체 방식은 연결 대상이 제공하는 기능에 맞춰야 합니다.
| 확인 시점 | 운영자가 확인할 내용 |
|---|---|
| 새 키 준비 | 대상 서비스에서 실제로 유효한 키인가 |
| 조회 버전 전환 | 새 버전이 읽히고 캐시 갱신이 적용되는가 |
| 클라이언트 갱신 | 새 연결로 인증 호출이 성공하는가 |
| 전환 관찰 | 이전 키를 사용하는 작업이 남아 있는가 |
| 이전 키 폐기 | 재사용이 차단되고 정상 서비스가 유지되는가 |
두 키의 병행 사용은 제공자가 지원할 때만 가능합니다. 단일 비밀번호만 허용하는 DB는 교체 전략과 연결 정리 순서를 따로 잡습니다. 짧은 중단이나 요청 재시도가 필요할 수 있으므로 무중단을 전제하지 않습니다.
이전 키를 이미 폐기했다면 시크릿 버전만 되돌려도 복구되지 않습니다. 대상 서비스에서 유효한 인증 정보를 확보하는 절차가 먼저입니다. 되돌리기 절차도 실제 호출로 확인합니다.
9. 실패 지점을 나누면 운영 안내가 쉬워집니다 🛠️
사용자에게는 같은 “다운로드 실패”여도 원인은 다릅니다. URL이 만료된 경우와 다른 사람의 문서를 요청한 경우를 같은 재시도로 처리하면 안 됩니다. 운영 기록에는 실패한 단계와 안전한 오류 분류를 남깁니다.
| 증상 | 먼저 확인할 지점 | 대응 방향 |
|---|---|---|
| 시크릿 조회 거부 | 실행 역할, 대상 시크릿, 키 정책 | 권한 범위를 확인 |
| 모델 인증 실패 | 실제 API 키 유효성, 조회 버전 | 캐시와 클라이언트 갱신 확인 |
| 업로드 접근 거부 | S3 정책, KMS 정책 | 요청한 작업의 허용 여부 확인 |
| 조건부 업로드 충돌 | 기존 객체와 산출물 기록 | 동일 요청인지 확인 후 재처리 |
| URL로 다운로드 실패 | 만료, 객체 버전, 읽기 권한 | 권한 재확인 후 필요 시 재발급 |
| 특정 환경에서만 실패 | 리전, 역할, 시크릿 식별자 | 환경별 설정 차이 확인 |
S3의 403 응답만으로 객체가 존재한다고 단정하지 않습니다. 객체가 없어도 요청자의 권한에 따라 403이 반환될 수 있습니다. 사용자에게 내부 키를 보여주기보다 산출물 ID로 지원 요청을 연결합니다.
배포 전에 확인할 작은 시나리오
| 시나리오 | 기대 결과 |
|---|---|
| 필수 API 키가 비어 있음 | 연결 초기화 단계에서 명확하게 실패 |
| 다른 조직 사용자가 다운로드 요청 | URL 생성 전에 차단 |
| 같은 산출물을 두 번 업로드 | 무조건 덮어쓰지 않고 기존 결과 확인 |
| 시크릿은 갱신됐지만 연결은 예전 값 사용 | 실제 호출 검증에서 식별 |
| 저장 성공 후 업무 기록 실패 | 미완료 상태를 찾아 복구 또는 정리 |
SDK 대역 테스트로 요청 인자와 오류 처리를 확인할 수 있습니다. 실제 IAM, KMS, 버킷 정책은 검증 환경에서 별도로 확인합니다. 로컬 테스트 통과를 클라우드 권한 검증 완료로 해석하지 않습니다.
보관 기간도 문서 공개 정책과 함께 정합니다. 버전 관리를 켠 버킷에서는 이전 버전의 정리 정책까지 필요합니다. 현재 문서만 지웠다고 과거 내용까지 모두 삭제되었다고 가정하지 않습니다.
10. 결론: 운영 변경을 받아들이는 공통 계층 🌱
기존 설계의 핵심은 비밀정보 조회와 문서 저장을 한곳에서 관리하는 것입니다. 서비스마다 SDK 초기화와 저장 규칙을 반복하지 않도록 돕습니다. 인증 방식이나 저장 옵션이 바뀌어도 변경 지점을 좁힐 수 있습니다.
그 위에 사용자 관점의 약속을 더합니다. 내 문서는 권한이 있는 사람에게만 전달되어야 합니다. 키가 바뀌면 실제 연결도 갱신되어야 합니다. 저장이 중간에 실패하면 진행 상태를 설명하고 복구할 수 있어야 합니다.
이 약속을 지키는 공통 계층은 Agent의 답변만큼 중요합니다. 모델 호출부터 보고서 다운로드까지 이어져야 상담 경험이 완성됩니다. 🤝
참조 출처 📚
- AWS Secrets Manager: Python으로 비밀정보 조회
- AWS Secrets Manager: 인증 정보 교체
- AWS IAM: 역할과 임시 자격 증명 권장 사항
- Boto3: 자격 증명 조회 체계
- Amazon S3: 객체 키
- Amazon S3: 버전 관리
- Amazon S3: PutObject API
- Amazon S3: GetObject API
- Amazon S3: KMS를 이용한 암호화
- Amazon S3: 서명 URL의 동작과 유효 조건
- Boto3: 서명 URL 생성
태그 🏷️
#AIAgent #AWSSecretsManager #S3 #Security #SecretManagement #Storage #Boto3 #운영보안 #Python