agent-loop

English: README.en.md · 설계 문서: docs/설계서.md

LLM 에이전트 실행 루프를 바닥부터 — 추론 → 도구 선택 → 실행 → 관찰 → 재계획, MCP로 외부 도구(브라우저·SQL)까지 물리고, 평가 하네스로 채점한다.

프레임워크 없이 순수 파이썬으로 구현했습니다. 에이전트 엔진의 본체인 루프가 어떻게 도구를 고르고, 실패에서 복구하고, 무한 루프를 스스로 끊는지를 코드로 보여주는 저장소입니다.

이런 상황에서 씁니다

상황 — 에이전트 제품을 만드는 팀. 루프 프롬프트나 도구 스키마를 고칠 때마다 "잘 되던 과제가 깨졌는지"를 몇 번 돌려 보고 감으로 판단한다. 성공률·개입률 같은 숫자가 없으니 개선인지 퇴보인지 논쟁만 남는다.

도입 후 — 시나리오 하네스가 릴리스 게이트가 된다. 수정 → run_eval → 이전 성적표와 회귀 비교 → 깨진 시나리오가 있으면 머지 전에 안다. "성공률 87.5%, 개입 필요율 12.5%, s03 회귀"처럼 논쟁이 숫자로 바뀐다.

통합 데모 — 브라우저·계산기·메모를 넘나드는 에이전트

MCP 커넥터로 외부 서버의 도구를 루프에 물릴 수 있습니다. browser-guard-mcp를 연결한 실행 예:

pip install -e . && pip install browser-guard-mcp가 설치된 환경  # 또는 examples/mcp.json의 command 경로 수정
agent-loop "데모 상점을 열어 3만 원 이하 상품의 가격 합계를 계산하고 '장바구니' 키로 메모해줘" \
  --mcp-config examples/mcp.json

[agent-loop] MCP 도구 7개 로드: ['browser_navigate', 'browser_get_text', ...]
  ▶ browser_navigate({"url": "index.html"})
    관찰: {"url": "file://.../demo_site/index.html", "title": "가드 데모 상점"}
  ▶ browser_get_text({})
    관찰: 무선 마우스 — 19,000원 ... 노트북 파우치 — 24,500원 ...
  ▶ calculator({"expression": "19000+24500"})
    관찰: 43500
  ▶ memo_save({"key": "장바구니", "text": "43500"})
    관찰: '장바구니' 메모 저장 완료
상태: success · 스텝 4
합계는 43,500원입니다.

루프는 내장 도구와 MCP 도구를 구분하지 않습니다 — 브라우저 서버의 가드 거절("허용되지 않은 도메인")도 관찰로 돌아와 에이전트가 스스로 경로를 바꿉니다. 크로스 도구 평가 시나리오는 eval/scenarios_mcp.jsonl, 실행: python scripts/run_eval.py --scenarios eval/scenarios_mcp.jsonl --mcp-config examples/mcp.json --backend claude-cli.

루프의 신뢰성 설계

모든 실패는 예외가 아니라 관찰이다. 없는 도구 호출, 인자 스키마 위반, 도구 내부 예외 — 전부 "오류: 원인 + 다음 행동"이 관찰로 돌아가고, LLM이 다음 턴에 스스로 고칩니다. 그 위에 방어 3층:

층	동작
형식 복구	JSON 깨지면 형식 안내 후 재요청(2회) → 반복 시 llm_error
반복 감지	같은 (도구, 인자) 3회 초과 → loop_detected
스텝 상한	10스텝 → step_limit — 최후 방어선

어떤 경우에도 전체 궤적(steps)과 중단 사유를 담아 종료합니다 — 조용히 죽지 않습니다.

평가 하네스

시나리오 8건(계산·메모 저장·다단계 조합)으로 에이전트를 채점합니다. 성공 조건은 전부 코드로 판정하며, 최종 답뿐 아니라 도구 부작용(실제로 저장했는가)까지 검사합니다.

python scripts/run_eval.py --backend claude-cli > report.json

{
  "success_rate": 0.875,
  "needs_intervention_rate": 0.125,   // 사람이 이어받아야 했던 비율
  "avg_steps_on_success": 2.4,
  "invalid_call_rate": 0.03           // 도구 오호출 비율 — Tool Calling 신뢰성
}

루프·프롬프트를 고친 뒤 --baseline report.json을 붙이면 시나리오 단위 회귀(성공→실패)·개선 목록이 나옵니다 — 리그레션 방지가 기본 워크플로입니다.

설치·실행

pip install -e .

# 백엔드 1: OpenAI 호환 (vLLM·Ollama 포함)
export AGENT_API_BASE="https://api.openai.com/v1"
export AGENT_API_KEY="sk-..."
python scripts/run_eval.py

# 백엔드 2: Claude 구독 (API 키 불필요)
python scripts/run_eval.py --backend claude-cli

테스트

pip install -e ".[dev]"
pytest   # 18건, 네트워크 불필요 — 에러 복구 3종, 반복 감지, 상한, 부작용 채점, 회귀 비교

함께 보기

• browser-guard-mcp — 이 루프에 물릴 수 있는 가드 달린 브라우저 도구
• judge-mcp — 같은 평가 철학의 텍스트 품질 버전
• log-triage-agent · sql-guard-mcp · llm-sse-gateway

라이선스

MIT