# agent 훅: 상한 없는 에이전트 루프 탐지하기

> 명령줄에서 코드베이스를 스캔해 스텝 수나 시간에 상한이 없는 에이전트나 LLM 호출을 찾거나, 호출 하나에 점수를 매길 수 있습니다.

표준 URL: https://lagune.ai/ko-KR/docs/hooks/agent
언어: ko-KR
원문: https://lagune.ai/docs/hooks/agent
마지막 업데이트: 2026-11-03

`agent` 훅은 **턴 수, 예산, 시간 중 어느 것에도 상한을 두지 않고 반복 실행되는 에이전트 런타임**을 잡아냅니다. 자율 실행이 폭주할 수 있는 이 허점 때문에, 조작된 입력 하나가 끝없는 비용 증가나 프롬프트 인젝션 피해 확대로 이어집니다. **언어를 인식하며**, 두 에이전트 프레임워크 생태계를 다룹니다: **JavaScript**(**Claude** 에이전트 SDK의 `query` 런타임)와 **Python**(**LangChain**, **LangGraph**, **CrewAI**, **OpenAI Agents**)입니다. 또한 [`llm` 전문 지식](https://lagune.ai/ko-KR/docs/catalog)을 뒷받침하는 결정론적 엔진이며, **scan** 모드나 **check** 모드로 직접 실행할 수도 있습니다.

## 실행하기

**코드베이스 스캔**

```bash
npx lagune read agent                # scans the whole project
npx lagune read agent --dir src/ai   # scans a directory
npx lagune read agent --file chat.ts # scans a single file
```

**호출 검사**

```bash
npx lagune read agent --lang javascript --pattern 'query({ prompt })'                           # => uncapped
npx lagune read agent --lang javascript --pattern 'query({ prompt, options: { maxTurns: 5 } })' # => safe
npx lagune read agent --lang python --pattern 'AgentExecutor(agent=a, max_iterations=None)'     # => uncapped
```

**Uncapped agent loops found** 아래의 각 줄은 에이전트 SDK를 임포트하는 파일에서 찾은 다음 둘 중 하나입니다: 턴 수, 예산, 시간 상한 없이 호출한 Claude 에이전트 SDK의 `query` 런타임(JavaScript, 기본적으로 상한 없음), 또는 `max_iterations=None` / `max_turns=None` 설정처럼 프레임워크의 기본 상한을 명시적으로 없앤 코드(Python, 기본적으로 상한 있음)입니다. 어느 쪽이든 0이 아닌 종료 코드를 반환합니다. Vercel AI SDK의 `generateText`/`streamText` 함수는 기본적으로 한 스텝만 실행하므로(`stopWhen: stepCountIs(1)` 설정) 옵션 없이 호출해도 반복되지 않아 잡아내지 않으며, 평범한 `db.query(...)` 호출을 에이전트 호출로 오인하는 일도 없습니다. 아무것도 발견되지 않으면 `no uncapped agent loops found` 메시지를 출력합니다.

## 판정 해석하기

| 판정       | 의미                                                                                      |
| ---------- | ----------------------------------------------------------------------------------------- |
| `uncapped` | 상한이 없는 `query` 런타임 호출(JS), 또는 명시적인 상한 제거(`=None`, Py)                 |
| `safe`     | 상한을 설정한 `query` 호출, 한 스텝짜리 생성, 또는 기본적으로 상한이 있는 프레임워크 호출 |
| `invalid`  | 판정할 수 있는 에이전트 호출이 없는 코드 조각                                             |

### CLI 옵션

| 옵션        | 값        | 설명                                                                        |
| ----------- | --------- | --------------------------------------------------------------------------- |
| `--pattern` | 코드 조각 | 호출 하나 검사. 반복해 지정하면 여러 호출을 검사해 한 줄에 판정 하나씩 출력 |
| `--lang`    | 언어      | `--pattern` 옵션 사용 시 필수: `javascript` 또는 `python`                   |
| `--dir`     | 디렉터리  | 스캔 범위를 디렉터리로 한정. 반복 지정 가능, `--file` 옵션과 함께 사용 가능 |
| `--file`    | 파일      | 스캔 범위를 단일 파일로 한정. 반복 지정 가능, `--dir` 옵션과 함께 사용 가능 |

옵션을 지정하지 않으면 프로젝트 전체를 스캔합니다. `--pattern` 옵션에는 `--lang` 옵션이 필요하며, `--dir` 또는 `--file` 옵션과 함께 쓸 수 없습니다.

**전수 검사가 아닌 최선의 탐지**

직접 구현한 에이전트 루프는 어떤 언어로 작성했든 정적 스캔으로 잡아낼 수 없습니다. 완전한 목록이 아니라 든든한 최소 기준으로 활용하세요.

**팁**

훅이 판단하는 것은 상한뿐입니다: 기능 범위 제한, 신뢰 수준 혼재, 인가처럼 판단이 필요한 부분은 여전히 [`llm` 전문 지식](https://lagune.ai/ko-KR/docs/catalog)이 다룹니다.

## 자주 묻는 질문

### 에이전트 루프에 왜 상한을 둬야 하나요?

상한이 없는 에이전트는 끝없는 재귀, 비용 증가, 프롬프트 인젝션 피해 확대로 내몰릴 수 있습니다. maxTurns/maxBudgetUsd/stopWhen/signal을 설정하면 실행에 한계가 생기며, agent 훅은 이 중 아무것도 설정하지 않은 query 런타임 호출을 잡아냅니다.