3-03 · Agent 권한과 실행 이력 완성하기
1. 실습 목표
기존 화면에 현재 테스트 사용자, 읽기 전용 Agent 권한 카드, Agent로 다시 확인과 사례별 실행 이력을 최소로 추가합니다. 실행 성공과 안전한 실패를 SQLite에 누적하되 최종 검토 결과·검토 자료·완료 상태는 바꾸지 않습니다.
2. 시작 지점
- 시작 체크포인트:
student/13-review-ui-ready - 기존 UI: 표본 12건, Agent 초안, 담당자 검토 입력·전체 이력, 완료·CSV
- 이번 실습에서 추가할 항목:
agent_runs테이블과 Agent 실행·조회 API
student/13-review-ui-ready의 담당자 검토·이력·완료·CSV 화면을 기준으로, 같은 디자인 안에 Agent 권한 카드와 실행·이력을 추가합니다.
3. 구현 범위 및 요구사항
Agent 실행 백엔드
POST /api/day2/agent-preview/{change_id}와 Pydantic 요청requester_user_id- 권한을 모델·MCP보다 먼저 확인: U701 허용, U601
403 - 허용 Tool
get_case_evidence하나, 최대 1회; 모델 실행 3단계 이하 OPENAI_API_KEY,OPENAI_MODEL, 선택적OPENAI_BASE_URL- 설정이 없으면 Agent API만
503; 기존 API·화면은 계속 동작 - 외부 호출은 OpenAI Responses Function Calling 형식을 따르며 테스트에서는 실제 호출 대신 정해진 응답을 사용
.env 설정
Agent 기능을 구현한 뒤 practice/workspace에서 예시 파일을 복사해 로컬 설정 파일을 만듭니다.
Copy-Item .env.example .env
notepad .env.env에 API 키와 모델을 입력합니다. OpenAI 호환 내부 API를 사용할 때만 OPENAI_BASE_URL의 주석을 풀고 주소를 입력합니다.
OPENAI_API_KEY=발급받은_API_키
OPENAI_MODEL=openai.us.gpt-5.4-mini
# OPENAI_BASE_URL=Warning
.env는practice/workspace루트에 두고 Git에 추가하지 않습니다. API 키를 코드·브라우저·화면·로그에 넣지 마세요. 설정이 없거나 잘못되면 Agent 실행만 중단되며 기존 검토 기능은 계속 사용할 수 있습니다. 값을 바꾼 뒤에는 백엔드를 다시 실행합니다.
이전 기록을 보존하는 실행 이력
같은 backend/data/day3_reviews.sqlite3 안에 review_events와 분리된 agent_runs를 만듭니다.
| 저장 | 저장하지 않음 |
|---|---|
| run ID, 사례·요청 사용자, 상태, 모델 처리 상태 | API 키·환경변수 값 |
| Tool 이름, 정제된 입력 JSON, Tool 상태 | 시스템 지시·전체 모델 메시지 |
| 사용자에게 표시한 설명, 안전한 오류 코드·요약 | 원본 ERP·Excel 전체 행, 비정제 외부 오류 |
| 시작·완료 시각 | 불필요한 개인정보 |
상태는 success, permission_denied, config_error, tool_error, model_error입니다. 실행마다 새 행을 추가하고 자동 삭제·덮어쓰기를 하지 않습니다. GET /api/day2/agent-runs?change_id=...&requester_user_id=U701은 최신 실행부터 반환하고 U601은 서버에서 거부합니다.
기존 UI에 추가할 최소 영역
- 최종 검토 결과의 U701/U601 선택 항목을
현재 테스트 사용자로 명확히 바꾸고 Agent와 검토가 같은 값을 사용합니다. - U701/U601은 권한 차이를 확인하기 위한 예시 사용자이며 실제 로그인 계정이 아님을 표시합니다.
- Agent 초안 근처에 현재 사용자·역할·permissions, 허용 Tool, 읽기 전용, 호출 1회, 최종 검토 결과 변경 불가, SQLite 기록을 보여 주는 카드만 추가합니다.
- 실행 중·성공·권한·설정·Tool·모델 오류를 구분합니다.
- 사례가 바뀌면 진행·일회성 결과는 지우고 저장된 해당 사례 이력은 다시 읽습니다.
- 각 이력에 시각, 사용자, 상태, Tool·상태와 설명 또는 안전한 오류를 표시합니다.
4. 실습 프롬프트
기존 담당자 검토 화면에 읽기 전용 Agent 실행과 사례별 실행 이력을 추가해 주세요.
현재 검토 자료 조회, 담당자 검토 이력, 완료 처리와 CSV 내보내기는 동작하지만 Agent 실행과 실행 이력은 연결되어 있지 않습니다. 기존 FastAPI, SQLite, `mcp_server.py`와 React 구조를 먼저 확인해 주세요.
구현이 끝나면 권한이 있는 사용자는 선택한 사례를 읽기 전용 Agent로 다시 확인할 수 있어야 합니다. 성공과 실패를 포함한 실행 결과는 사례별 이력으로 남고, 화면을 새로고침한 뒤에도 다시 확인할 수 있어야 합니다.
- `POST /api/day2/agent-preview/{change_id}`와 `GET /api/day2/agent-runs` 구현
- Tool과 모델 호출 전 사용자 권한 검사
- 허용 Tool의 `get_case_evidence` 한 개와 실행당 한 번 호출 제한
- 모델 처리의 최대 3단계 제한
- 성공, 권한 거부, 설정 오류, Tool 오류와 모델 오류의 구분
- 기존 기록을 덮어쓰지 않는 사례별 실행 이력 추가
- `.env`의 API 키·모델·선택적 기본 주소 사용과 비밀값 없는 `.env.example` 제공
- 화면의 사용자 권한 안내, 실행 상태, 안전한 오류와 누적 이력 표시
- 비밀값, 전체 모델 메시지, 원본 행과 정리되지 않은 외부 오류 저장 금지
- 담당자 검토 결과, 완료 상태, 검토 자료와 CSV 변경 금지
모델 응답은 테스트 대역으로 처리하고 허용되는 실행과 권한 거부를 한 번씩 확인해 주세요. 구현 후에는 변경 파일, 실제 API·화면·저장 동작, 검사 통과 여부와 남은 위험만 간단히 알려 주세요.5. 예상 결과
Success
- 종료 체크포인트:
student/14-agent-history-ready- U701 성공 2회 → 같은 사례 이력 2건, 새 연결·새로고침 후 유지
- U601은 모델·MCP 전 거부되고 안전한
permission_denied1건 기록- 설정 없음
503/config_error, Tool·모델 오류 구분working-paper.json, 최종 검토 결과·이력·완료 건수,30 / 29 / 21 / 8 / 1, 표본 12건 유지- 기존 담당자 검토·CSV 화면은 유지되고 Agent 실행·이력 영역만 새로 활성화됨
담당자 최종 검토 시연
| 변경 ID | 최종 검토 결과 |
|---|---|
001–004 | normal |
023 | follow_up |
022, 024–029 | control_exception |
최종 집계는 12 / 12 / 0 / 4 / 1 / 7, export_ready: true이며 결론은 담당자가 화면에서 직접 입력합니다.
6. 대표 실패 사례 및 복구
Failure
- API 키나 원본 행을 실행 이력·응답에 넣음
- U601 권한을 모델 호출 뒤 검사함
- Agent 결과로 최종 검토 결과·검토 자료·완료 건수를 바꿈
- 재실행이 기존 run을 덮어씀
Info
Agent API와 기존 API 상태를 분리해 확인합니다. 같은 오류가 두 번 반복되거나 10분 이상 지연되면
student/14-agent-history-ready로 이동해 기존 기능 전체 확인부터 수행합니다.
직접 확인할 결과
- 담당자 검토 화면의 테스트 사용자 선택을 Agent 권한 카드와 공유합니다.
U701로 사례를 두 번 실행해 성공 상태와 동일 사례 이력 2건을 확인합니다.U601로 실행해 모델·MCP 전에 권한 거부 상태를 확인합니다.- Agent 실행 전후에 담당자 결론·CSV 완료 상태·첫 과정 집계가 바뀌지 않는지 확인합니다.
7. 다음 실습
완성 결과와 적용 계획을 최종 시연·발표·마무리에서 공유합니다.