[AIOps Agent 1] 에이전트 개발 기본기와 Repository 설계

Об этом предложении

이 글에서 다룰 주제 Agent의 기본기 : 모델 호출과 운영 에이전트는 무엇이 다른가? 개발 순서 : 무엇부터 공부하고 어떤 MVP를 만들까? 저장소 구조 : 프롬프트·도구·정책·상태·평가를 어떻게 분리할까? 주요 단어 · AIOps · Tool Calling · Runtime · Workflow · State · Evidence · Repository 읽기 안내 · Python 함수와 JSON을 본 적이 있는 입문자를 위한 글입니다. 읽고 나면 모델·Runtime·도구의 책임을 구분하고, 근거 검증기를 직접 실행할 수 있습니다. 결제 서비스가 느려졌다는 알림이 왔다. 담당자는 지표, 로그, 트레이스, 배포 이력을 차례로 살펴본다. AIOps 에이전트의 첫 목표는 이 조사 과정을 대신 수행하고 확인한 사실과 아직 모르는 부분을 근거와 함께 정리하는 것 이다. 이 시리즈는 기초 → 메모리·권한 → Grafana 연동 → 운영·Langfuse로 이어진다. 모든 서비스명·수치·정책은 학습용 가상 예시다. 실제 운영 환경에서 배포하거나 성능을 측정한 결과는 아니다. 그림 1. 모델이 도구를 제안하더라도, 실제 호출과 종료 조건은 Runtime이 통제한다. 추가 조사는 정해진 예산 안에서 반복한다. 이번 시리즈에서 계속 사용할 장애 상황 서비스는 checkout , 환경은 staging , 담당 팀은 team-a 다. 분석 시간은 2026-10-04 01:00 01:10 UTC(한국시간 10:00 10:10) 로 고정한다. 목표는 “왜 느린가?”를 곧바로 맞히는 것이 아니라 다음 네 질문에 답하는 것이다. 실제로 사용자 응답이 느려졌는가? 어떤 구간이 느리고, 어떤 증거가 있는가? 현재 후보를 반박하는 증거 또는 아직 없는 자료는 무엇인가? 사람이 다음에 확인하거나 승인할 일은 무엇인가? 설명을 위해 기준 p95는 0.3초, 현재 p95는 1.2초라고 가정한다. 4배 증가지만 원인을 알려 주는 숫자는 아니다. 트래픽 증가, DB 대기, 외부 API 지연, 배포 문제 모두 가능하다. 이 구분을 놓치면 Agent가 “이상 탐지”를 “원인 확정”으로 건너뛴다. 1. Agent 기초: 모델은 판단을 제안하고 프로그램은 실행을 책임진다 Agent 는 목표와 현재 상태를 바탕으로 필요한 도구를 선택하고, 결과를 확인하며 다음 행동을 결정하는 시스템이다. Runtime 은 그 과정의 실행·상태·제한·실패 처리를 맡는 프로그램이다. LLM은 문맥을 입력받아 응답을 생성하는 모델이다. 도구 호출 기능은 모델이 get_latency(service="checkout") 같은 구조화된 요청을 출력하게 한다. 외부 API 호출은 모델 자체가 아니라 애플리케이션이 수행한다. JSON 형식이 맞아도 서비스·시간 범위·권한이 올바르다는 뜻은 아니다. 구성 맡는 일 결제 서비스 조사 예시 입력 계약 요청의 범위 정의 tenant, 환경, 서비스, 시작·종료 시각 모델 조사할 항목·가설·설명 생성 DB 지연을 더 확인하자 도구 검증 가능한 데이터 조회 승인된 PromQL 실행 상태 이번 작업의 진행 상황 보관 완료한 조회, 증거 ID, 남은 예산 정책 허용되는 행동 판정 production 변경은 승인 필요 검증기 결과의 형식과 근거 확인 모든 사실에 유효한 evidence_id가 있는가 프롬프트는 행동 지침이고, 권한은 실행 코드와 인프라가 강제하는 경계 다. 이 구분이 전체 설계의 출발점이다. 1.1 실제로 한 번 도구를 호출하면 벌어지는 일 모델에게 “checkout의 지연을 조사해 줘”라고 말해도 모델은 회사의 Prometheus 주소나 현재 지표를 저절로 알지 못한다. 개발자가 사용 가능한 도구의 설명과 입력 스키마를 전달해야 한다. 그림 2. 그림 1과 같은 배치다. 주황색은 오류 표시가 아니라 지금 읽을 실행 경로다. 모델 제안은 Runtime을 거쳐야 실제 조회가 된다. 순서 전달되는 내용 누가 책임지는가 1 질문 + 조회 가능한 서비스 + 도구 목록 API·Runtime 2 도구 이름과 인자 선택 모델 3 서비스·기간·권한·예산 검증 Runtime·정책 코드 4 고정 질의로 실제 백엔드 호출 Adapter 5 출처·시각을 포함한 증거 저장 Evidence 계층 6 증거를 읽고 다음 조회 또는 보고서 선택 모델·검증기 예를 들어 2단계에서 모델이 24시간 조회를 요청해도 정책이 30분까지만 허용하면 3단계에서 거부한다. 프롬프트를 잘 썼는지와 무관하게 동작해야 한다. 반대로 도구가 timeout 을 반환하면 모델은 수치가 없음을 보고해야 하며, 이전의 1.2초를 새 측정값처럼 사용하면 안 된다. 1.2 LLM·RAG·Workflow·Agent는 어떻게 함께 쓰이나? LLM은 설명을 만드는 엔진, RAG는 관련 문서를 찾아 넣는 방법, Workflow는 실행 순서, Agent는 다음 조사에 선택권이 있는 실행 방식이다. 서로 대체 제품 네 개를 고르는 문제가 아니다. 하나의 고정 Workflow 안에서 RAG로 런북을 찾고 LLM으로 보고서를 작성할 수 있다. 여기에 “근거가 부족할 때 허용된 추가 도구를 선택”하는 단계가 생기면 Agent 성격이 커진다. 처음에는 도구 선택 없이도 개발할 것이 많다. 서비스 이름을 정확히 연결하고, 빈 결과를 구분하고, 보고서에 근거를 붙이는 작업이 끝나야 모델의 자유도가 실제 가치를 내는지 평가할 수 있다. 2. Workflow부터 시작하면 실패 지점이 보인다 Workflow 는 개발자가 정한 순서와 분기를 실행하는 흐름이다. Agent는 일부 다음 단계를 모델이 고를 수 있어 자유도가 커진다. 첫 버전은 알림 정규화 → 지표 조회 → 로그 조회 → 변경 이력 조회 → 보고서 검증 으로 고정해도 충분하다. 자주 발생하는 조사에서 다음 조회가 상황마다 달라지는 지점만 모델에 위임한다. “에이전트를 만든다”는 이유로 처음부터 무제한 반복과 여러 에이전트를 도입할 필요는 없다. 학습용 Runtime 의사코드는 다음과 같다. 완성된 SDK 예제나 보안 구현은 아니다. state = create_run(authenticated_context, validated_request) for step in range(MAX_STEPS): if state.deadline_exceeded() or state.cost_exceeded(): break proposal = planner.choose_next(public_view(state)) if proposal.kind == "finish": report = validate_report(proposal.report, state.evidence) return save_report(report) args = validate_tool_args(proposal) decision = policy.authorize(state.auth_context, proposal.tool, args) if not decision.allowed: state.record_denial(decision) continue result = tools.call(proposal.tool, args, timeout=TOOL_TIMEOUT) state.add_evidence(normalize_and_redact(result)) if state.deadline_exceeded() or state.cost_exceeded(): break return save_partial_report(state, reason="budget_exhausted") 실제 구현에서는 취소 전파, 체크포인트, 감사 기록, 오류 분류, 권한 재검증을 추가한다. 단계 제한에 걸렸을 때 정상 완료로 꾸미지 않고 partial 또는 needs_human 으로 끝낸다. 고정 워크플로라면 위 planner 없이 정해진 함수를 호출하면 된다. 3. 공부 순서: 프레임워크보다 선행하는 기본기 난이도 공부할 내용 이해했는지 확인할 결과물 기초 1 Python 타입, 함수, 예외, pytest, HTTP·JSON API 응답을 타입 모델로 검증 기초 2 Linux, 컨테이너, Git, 환경변수, TLS 로컬 API와 테스트 실행 기초 3 토큰·문맥 길이, 구조화 출력, Tool Calling 잘못된 도구 인자 거부 기초 4 RED 지표, SLI/SLO, 로그·트레이스 같은 장애를 세 신호로 설명 중급 async, DB 트랜잭션, 큐, RAG, 체크포인트 워커 재시작 후 조사 재개 중급 RBAC, 멀티테넌시, 인증·인가 다른 팀 데이터 접근 차단 고급 멱등성, 분산 잠금, 장애 격리, 평가 설계 중복 알림·부분 실패 재현 고급 OTel, Langfuse, 회귀 평가, 점진 배포 변경 전후 품질·비용 비교 RED 는 요청량(Rate), 오류(Errors), 소요 시간(Duration)을 보는 관점이다. SLI 는 서비스 품질을 측정하는 지표, SLO 는 그 지표의 목표다. CPU가 높다는 사실과 사용자가 결제를 못 한다는 영향은 다르므로, 자원 지표만 공부하지 말고 서비스 품질의 정의를 함께 공부한다. 4. Repository 구조: 바뀌는 이유가 다른 코드를 나눈다 Python 기반 단일 저장소의 제안 예시다. 폴더마다 별도 서버를 만들라는 뜻은 아니다. aiops-agent/ ├── pyproject.toml # 의존성 정의 ├── uv.lock # 선택한 패키지 도구의 잠금 파일 ├── .env.example # 이름·예시만, 실제 비밀 없음 ├── src/aiops_agent/ │ ├── api/ # 인증, webhook, 요청 검증 │ ├── workflows/ # incident_triage 흐름 │ ├── runtime/ # 상태 전이, 예산, 재시도, 취소 │ ├── domain/ # Run, Evidence, Report, ActionPlan │ ├── tools/ # 도구 스키마와 registry │ ├── adapters/ # Prometheus, Loki, Tempo, Git │ ├── policy/ # tenant·resource·action 권한 │ ├── memory/ # checkpoint, runbook 검색 │ ├── observability/ # OTel, masking, 선택적 Langfuse │ └── prompts/ # 프롬프트와 출력 계약 버전 ├── migrations/ # DB 스키마 이력 ├── evals/ │ ├── cases/ # 비식별 고정 사례 │ ├── graders/ # 근거·정책·정답 평가 │ └── baselines/ # 비교 대상과 설정 ├── tests/ │ ├── unit/ # 상태·정책 단위 검증 │ ├── contract/ # 외부 API 응답 계약 │ └── integration/ # 큐·DB·도구 경계 ├── deploy/ # 로컬 compose, 필요 시 Helm └── docs/ # ADR, 위협 모델, 운영 런북 tools/ 는 모델이 볼 인터페이스이고 adapters/ 는 실제 API 연결 구현이다. 예를 들어 도구 이름이 get_latency_summary 로 유지되면, 뒤에서 Prometheus를 Mimir로 바꾸더라도 워크플로 변경을 줄일 수 있다. policy/ 를 프롬프트 폴더에 넣지 않는 이유는 정책이 실행 강제 로직이기 때문이다. evals/ 를 일반 테스트와 나누는 이유는 도구가 정상 동작하는 것과 보고서가 유용한 것이 서로 다른 품질이기 때문이다. 프롬프트·모델·도구 스키마·정책 버전을 실행 기록에 남겨야 회귀 원인을 찾을 수 있다. 4.1 하나의 요청이 Repository를 통과하는 순서 그림 3. 전체도의 실행 경로를 확대한 상세도다. 함수와 폴더는 제안 구조이며, 한 박스가 독립 서버를 뜻하지 않는다. 가령 Prometheus 인증 방식이 바뀌면 adapters/prometheus.py 를 수정한다. 사용자별 허용 서비스가 바뀌면 policy/authorize.py 를 바꾼다. 보고서 문체를 바꾸려면 prompts/triage.md 를 바꾼다. 세 변경이 한 파일에 뒤섞이면 보안 변경이 프롬프트 수정처럼 배포되거나, 테스트하기 어려운 거대한 함수가 생기기 쉽다. 의존성의 방향도 정한다. domain/ 의 Evidence는 Grafana SDK를 몰라도 표현할 수 있어야 한다. Adapter가 외부 응답을 Evidence로 바꾸고, Workflow는 그 공통 계약만 읽는다. 외부 API를 호출하지 않는 fake adapter로 Workflow를 시험할 수 있게 만드는 것이 분리의 실질적인 이득이다. 작은 MVP에서는 domain.py , policy.py , tools.py , workflow.py 네 파일로 시작해도 된다. 기능이 자랄 때 위 폴더로 분리한다. 처음부터 Kafka·Vector DB·여러 마이크로서비스를 의무적으로 추가하지 않는다. 5. 최소 데이터 계약: 증거 없는 설명을 막는다 Evidence 는 도구가 관측한 결과와 출처·시각·범위를 묶은 증거 레코드다. { "evidence_id": "ev-001", "source": "prometheus", "service": "checkout", "environment": "staging", "window": {"start": "2026-10-04T01:00:00Z", "end": "2026-10-04T01:10:00Z"}, "query_template": "latency_p95_v1", "unit": "seconds", "status": "ok", "value": 1.2, "fetched_at": "2026-10-04T01:10:05Z" } 1.2 는 가상의 설명용 값이다. 실제 계약에는 tenant, cluster, 데이터 최신 시각, 샘플 수, 잘림 여부, 원문 참조, 질의 버전도 포함한다. fetched_at 은 조회 시각일 뿐 데이터가 최신이라는 증명이 아니다. 보고서는 관측 사실 → 원인 후보 → 반증·누락 → 다음 조사 순서로 만든다. “배포 직후 지연 증가”는 사실일 수 있지만 “배포가 원인”은 추가 검증이 필요한 가설이다. 모델이 임의로 붙인 95% 확신도를 실제 원인 확률처럼 보여 주지 않는다. 5.1 작은 실행 실습: 같은 1.2초라도 받아들일 수 없는 경우 다음 코드는 Python 3.9.6에서 실제 실행 확인 했다. 표준 라이브러리만 사용하며 API 키·LLM·Grafana 설치가 필요 없다. evidence_lab.py 로 저장해 python3 evidence_lab.py 를 실행한다. 원격 시스템 연동이 아니라 증거 검증 규칙을 익히는 실습 이다. """Python 표준 라이브러리 실습: 외부 API·LLM 호출 없음.""" from __future__ import annotations from dataclasses import dataclass from datetime import datetime @dataclass(frozen=True) class Scope: tenant: str service: str environment: str start: str end: str @dataclass(frozen=True) class Evidence: id: str scope: Scope status: str value: float | None unit: str observed_at: str def validate(request: Scope, evidence: Evidence) -> str: if evidence.scope != request: return "rejected: scope_mismatch" if evidence.status != "ok": return f"partial: {evidence.status}" if evidence.unit != "seconds" or evidence.value is None: return "rejected: invalid_value_or_unit" age = (datetime.fromisoformat(request.end) - datetime.fromisoformat(evidence.observed_at)).total_seconds() if not 0 <= age <= 60: return "partial: stale_or_future_sample" return f"observed: p95={evidence.value:.1f}s [{evidence.id}]" scope = Scope("team-a", "checkout", "staging", "2026-10-04T01:00:00+00:00", "2026-10-04T01:10:00+00:00") other = Scope("team-b", "checkout", "staging", scope.start, scope.end) cases = [ Evidence("ev-1", scope, "ok", 1.2, "seconds", "2026-10-04T01:09:50+00:00"), Evidence("ev-2", scope, "no_data", None, "seconds", scope.end), Evidence("ev-3", other, "ok", 1.2, "seconds", scope.end), Evidence("ev-4", scope, "ok", 1.2, "seconds", "2026-10-04T01:05:00+00:00"), ] for case in cases: print(validate(scope, case)) 실행 결과: observed: p95=1.2s [ev-1] partial: no_data rejected: scope_mismatch partial: stale_or_future_sample 첫 결과만 해당 요청 범위의 최신 관측으로 받아들였다. 두 번째는 데이터가 없어서 보류했고, 세 번째는 다른 팀의 데이터라 거부했다. 네 번째는 최신 샘플이 분석 종료 시각보다 5분 오래되어 보류했다. 여기서 신선도 60초는 설명용 정책이다. observed_at 은 최신 원본 샘플 시각이어야 한다. Adapter가 현재 서버 시각을 넣으면 오래된 데이터도 새 데이터처럼 통과한다. 또한 이 간단한 함수는 숫자의 유한성, timezone 유효성, 샘플 완전성, 권한 DB 조회까지 검증하지 않는다. Production에서는 별도로 추가한다. 검증기가 있다고 보안 전체가 완성된 것은 아니며, 검증할 범위를 명시하는 것이 중요하다. 그림 4. 1.2초라는 관측 사실만으로 DB를 원인으로 확정할 수 없다. 가능한 원인을 좁히고, 반증과 누락을 확인한 만큼만 결론을 말한다. 6. 첫 MVP의 완료 기준 입력은 알림 하나, 대상은 staging 서비스 하나, 도구는 읽기 전용 3개로 제한한다. 출력은 근거 링크가 달린 조사 보고서다. 자동 재시작·롤백은 후속 단계다. 성공 사례뿐 아니라 빈 데이터, 시간 초과, 다른 tenant 요청, 잘못된 서비스명도 처리해야 한다. 사람에게 기존 대시보드를 열어 보라고 안내하는 것에서 끝나지 않고, 어떤 기간의 어떤 쿼리를 보고 무엇을 확인했는지 남겨야 조사 시간을 줄일 수 있다. 프레임워크는 이 작은 흐름을 구현한 뒤 선택한다. 단순 흐름은 일반 Python으로도 충분하다. 중단·승인·재개가 중요한 시점에는 LangGraph 같은 상태 중심 도구를 검토한다. LangGraph의 체크포인트는 상태 저장을 제공하지만 업무 권한과 외부 API의 중복 실행까지 자동 해결하지는 않는다. LangGraph Persistence 자료 기준 : 2026-10-04, 본문에 연결한 공식 문서의 해당 기능·구문을 확인했다. 모든 버전의 전체 동작을 검증한 것은 아니다. 아키텍처와 저장소는 학습용 제안이다. 함께 읽기 : 기존 AIOps 시리즈 · Prometheus HTTP API AIOps 에이전트 개발 시리즈 [AIOps Agent 1] 에이전트 개발 기본기와 Repository 설계 [AIOps Agent 2] 메모리·도구 권한·승인과 안전한 실행 [AIOps Agent 3] Grafana·Prometheus·Loki·Tempo 연결하기 [AIOps Agent 4] 운영·평가부터 OpenTelemetry와 Langfuse까지