> ## Documentation Index > Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt > Use this file to discover all available pages before exploring further. # 에이전트를 위한 CLI 레시피 > 에이전트를 위한 AgentEye CLI 레시피 문서. 스크립트나 코딩 에이전트에서 세션, 이벤트, 평가 데이터를 직접 가져오고(재평가도 트리거할 수 있으며), `jq`로 바로 파이프할 수 있는 깔끔한 JSON을 stdout에 출력합니다. 이 레시피들은 AgentEye의 관찰 가능성 데이터를 터미널 사용자나 AI 코딩 에이전트(Claude Code, Cursor)가 대시보드를 클릭하지 않고도 쿼리하고 자동화할 수 있는 형태로 만들어 줍니다. 아래 패턴들은 AgentEye CLI(`agenteye`)에서 바로 복사해서 사용할 수 있습니다. 설치, 인증, 전체 옵션 목록은 [CLI](/ko/agenteye/cli)를 참고하세요. 내장 도움말은 `agenteye -h` 또는 `agenteye -h`로 확인할 수 있습니다. ## 기본 원칙 1. **전역 옵션은 명령어 *앞*에 붙입니다.** `agenteye --json sessions`가 올바른 형태이며, `agenteye sessions --json`은 올바르지 않습니다. 전역 옵션은 `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`입니다. 2. **출력을 파싱할 때는 반드시 `--json`을 전달하세요.** 데이터는 JSON 형태로 **stdout**에 출력되고, 사람이 읽는 상태 메시지와 오류는 **stderr**로 출력되므로 stdout은 `jq`로 파이프하기에 깔끔한 상태를 유지합니다. 3. **stderr 텍스트가 아닌 종료 코드로 분기하세요.** `0` 성공 · `2` 잘못된 인수 · `3` 대시보드에 연결할 수 없음 · `4` 로그인되지 않았거나 만료됨 · `5` 권한 없음. 4. **`-h`로 탐색하세요.** 모든 명령어는 필터, 값 형식, JSON 구조를 문서화하고 있습니다. ## 최초 설정 ```bash theme={null} export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com # --base-url을 반복하지 않아도 됩니다 agenteye login --email you@example.com # 이메일로 받은 코드를 붙여넣기; 약 24시간 유효 ``` ## 작업 전 인증 확인 `whoami`는 세션이 없거나 만료된 경우에도 오류를 발생시키지 않고 `logged_in:false`를 반환하므로, 에이전트가 안전하게 인증 상태를 확인할 수 있습니다. (베이스 URL이 설정되지 않았거나 대시보드에 연결할 수 없는 경우에는 여전히 non-zero로 종료될 수 있습니다.) ```bash theme={null} if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then echo "Not authenticated. Run: agenteye login" >&2; exit 1 fi ``` ## 실패하거나 점수가 낮은 세션 찾기 ```bash theme={null} # 지난 24시간 내 평가가 오류인 세션 agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id' # 특정 에이전트에서 도움성 점수가 0.5 이하인 평가 agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \ | jq '.evaluations[] | {session_id, scores}' ``` 점수 필터링은 `sessions`가 아닌 \*\*`evals`\*\*에서 처리됩니다. `--score KEY:MIN..MAX`는 반복 사용 가능하며 AND 조건으로 결합됩니다. 각 경계는 선택 사항입니다(`..0.5`는 ≤ 0.5, `0.9..`는 ≥ 0.9를 의미합니다). 요청당 최대 20개의 점수 필터를 전달할 수 있으며, 그 이상이면 HTTP 400을 반환합니다. `sessions`는 `evals`와 `--env`, `--status`, `--agent-id`, `--session-id`, 시간 범위 필터를 공유하지만 `--score`는 없습니다. ## 세션 전체 읽기 단일 `session show` 명령어는 없습니다 — 이벤트 기록과 세션 평가를 조합하세요: ```bash theme={null} # 세션의 최신 평가 (상태 + 점수) agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}' # 실행의 모든 이벤트 (전체 조회를 위해 --limit 값을 높이세요) agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}' # 세션 내 도구 호출만 조회 agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all \ | jq '.events[].payload' ``` ## 전체 가져오기 (페이지네이션) 결과는 최신순으로 반환되며 커서 기반 페이지네이션을 사용합니다. ```bash theme={null} # 한 번에: 200행 단위 페이지로 최대 500행 가져오기 agenteye --json events --session-id run-001 --limit 500 --all > events.json # 수동 페이징: next_cursor를 다시 전달 page=$(agenteye --json events --limit 100) cursor=$(echo "$page" | jq -r '.next_cursor // empty') [ -n "$cursor" ] && agenteye --json events --limit 100 --cursor "$cursor" ``` ## --fields로 출력 줄이기 에이전트가 읽어야 할 양을 줄이기 위해 키를 제한합니다(테이블과 `--json` 모두 적용). ```bash theme={null} agenteye --json sessions --since 7d --fields session_id,status,scores | jq -c '.sessions[]' agenteye --json events --session-id run-001 --fields ts,event_type --all ``` 알 수 없는 필드명은 유효한 목록과 함께 거부됩니다(종료 코드 `2`). 필드명을 확인하는 간편한 방법입니다. ## 유효한 필터 값 탐색 ```bash theme={null} agenteye --json list envs | jq -r '.values[]' # --env 값 목록 agenteye --json list tools | jq -r '.values[]' # 도구 이름; agents, models, event_types 등도 가능 agenteye --json list score_filters | jq -r '.values[]' # --score KEY:MIN..MAX의 유효한 KEY ``` ## 조직 선택 (멀티 테넌트) 여러 조직에 속한 경우, 로그인 시 활성 테넌트를 선택할 수 있습니다(저장됩니다): ```bash theme={null} agenteye login --org acme --email you@corp.com # 로그인과 동시에 테넌트 설정 agenteye --json orgs list | jq -r '.orgs[].org_slug' agenteye --org globex --json sessions --since 24h # 단일 명령어에 대해 재정의 ``` `--org` 없이 여러 조직에 로그인하면 non-zero로 종료되고 선택 가능한 조직 목록이 출력됩니다. ## SDK/수집기용 API 키 생성 ```bash theme={null} # 시크릿은 한 번만 출력됩니다 — --json 사용 시 .key 필드에 있습니다 key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key') agenteye keys regenerate ci-bot --yes # 교체; 폐기하려면 agenteye keys disable ci-bot --yes ``` ## 저장된 쿼리 또는 즉석 쿼리 실행 ```bash theme={null} agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows' agenteye --json query run errs --arg prod | jq '.rows' # 저장된 쿼리 + 위치 인수 $1 ``` ## 인시던트 비대화형으로 처리 ```bash theme={null} id=$(agenteye --json incidents list --state firing | jq -r '.incidents[0].id') agenteye incidents ack "$id" agenteye incidents assign "$id" --assignee you@corp.com agenteye incidents resolve "$id" --yes ``` > 변경(mutation) 명령어는 `--json` 사용 시 또는 stdin이 TTY가 아닐 때 확인 프롬프트를 자동으로 건너뛰므로 에이전트가 멈추지 않습니다. 다른 상황에서 명시적으로 건너뛰려면 `--yes`/`-y`를 전달하세요. ## 스크립트에서의 종료 코드 처리 ```bash theme={null} out=$(agenteye --json sessions --since 1h) || code=$? case "${code:-0}" in 0) echo "$out" | jq '.sessions | length' ;; 4) echo "Session expired - run 'agenteye login'." >&2 ;; 5) echo "Missing permission (ask an admin for evaluations:read)." >&2 ;; 3) echo "Dashboard unreachable - check the URL." >&2 ;; *) echo "Unexpected error (exit ${code})." >&2 ;; esac ``` ## JSON 출력 구조 | 명령어 | stdout JSON (`--json` 사용 시) | | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `whoami` | `{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` 또는 `{"logged_in": false}` | | `orgs list` | `{"active_org", "orgs": [{"org_slug","org_name","permission_set","permissions"}]}` | | `events` | `{"events": [...], "next_cursor": }` | | `evals` | `{"evaluations": [...], "next_cursor": }` | | `sessions` | `{"sessions": [...], "next_cursor": }` | | `errors` | `{"errors": [...], "next_cursor": }` | | `list ` | `{"kind", "values": [...]}` | | `keys list` / `keys create` | `{"keys": [...]}` / `{id, name, permissions, created_at, key}` (`key`는 한 번만 표시) | | `query run` | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}` | | `users list` / `settings list` | `{"users": [...]}` / `{"settings": [...]}` | | `alerts list` / `incidents list` | `{"alerts": [...]}` / `{"incidents": [...]}` | | create/update/delete (모든 경우) | 리소스 객체, 또는 삭제 시 `{"deleted": true, "id"}` | | 실패 (모든 경우, `--json` 사용 시) | stdout에 `{"error": "...", "exit_code": , "status"?: , "hint"?: "..."}` | * 각 **이벤트** 항목(`events`): `id, session_id, agent_id, event_type, ts, payload, environment`. * 각 **평가** 항목(`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`. * 각 **세션** 항목(`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`. 각 명령어의 `--fields`는 해당 항목의 필드명만 허용합니다 — `sessions`와 `evals`의 필드 집합이 다르므로, 한쪽에서 유효한 이름이 다른 쪽에서는 거부될 수 있습니다.