에이전트를 위한 CLI 레시피

스크립트나 코딩 에이전트에서 세션, 이벤트, 평가 데이터를 직접 가져오고(재평가도 트리거할 수 있으며), jq로 바로 파이프할 수 있는 깔끔한 JSON을 stdout에 출력합니다. 이 레시피들은 AgentEye의 관찰 가능성 데이터를 터미널 사용자나 AI 코딩 에이전트(Claude Code, Cursor)가 대시보드를 클릭하지 않고도 쿼리하고 자동화할 수 있는 형태로 만들어 줍니다. 아래 패턴들은 AgentEye CLI(agenteye)에서 바로 복사해서 사용할 수 있습니다. 설치, 인증, 전체 옵션 목록은 CLI를 참고하세요. 내장 도움말은 agenteye -h 또는 agenteye <command> -h로 확인할 수 있습니다.

기본 원칙

전역 옵션은 명령어 앞에 붙입니다. agenteye --json sessions가 올바른 형태이며, agenteye sessions --json은 올바르지 않습니다. 전역 옵션은 --json, --base-url, --org, --token, --insecure/--secure, --timeout, --quiet, --no-color입니다.
출력을 파싱할 때는 반드시 --json을 전달하세요. 데이터는 JSON 형태로 stdout에 출력되고, 사람이 읽는 상태 메시지와 오류는 stderr로 출력되므로 stdout은 jq로 파이프하기에 깔끔한 상태를 유지합니다.
stderr 텍스트가 아닌 종료 코드로 분기하세요. 0 성공 · 2 잘못된 인수 · 3 대시보드에 연결할 수 없음 · 4 로그인되지 않았거나 만료됨 · 5 권한 없음.
-h로 탐색하세요. 모든 명령어는 필터, 값 형식, JSON 구조를 문서화하고 있습니다.

최초 설정

export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com   # --base-url을 반복하지 않아도 됩니다
agenteye login --email you@example.com                       # 이메일로 받은 코드를 붙여넣기; 약 24시간 유효

작업 전 인증 확인

whoami는 세션이 없거나 만료된 경우에도 오류를 발생시키지 않고 logged_in:false를 반환하므로, 에이전트가 안전하게 인증 상태를 확인할 수 있습니다. (베이스 URL이 설정되지 않았거나 대시보드에 연결할 수 없는 경우에는 여전히 non-zero로 종료될 수 있습니다.)

if [ "$(agenteye --json whoami | jq -r .logged_in)" != "true" ]; then
  echo "Not authenticated. Run: agenteye login" >&2; exit 1
fi

실패하거나 점수가 낮은 세션 찾기

# 지난 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 명령어는 없습니다 — 이벤트 기록과 세션 평가를 조합하세요:

# 세션의 최신 평가 (상태 + 점수)
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'

전체 가져오기 (페이지네이션)

결과는 최신순으로 반환되며 커서 기반 페이지네이션을 사용합니다.

# 한 번에: 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 모두 적용).

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). 필드명을 확인하는 간편한 방법입니다.

유효한 필터 값 탐색

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

조직 선택 (멀티 테넌트)

여러 조직에 속한 경우, 로그인 시 활성 테넌트를 선택할 수 있습니다(저장됩니다):

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 키 생성

# 시크릿은 한 번만 출력됩니다 — --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

저장된 쿼리 또는 즉석 쿼리 실행

agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows'
agenteye --json query run errs --arg prod | jq '.rows'   # 저장된 쿼리 + 위치 인수 $1

인시던트 비대화형으로 처리

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를 전달하세요.

스크립트에서의 종료 코드 처리

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": <cursor or null>}`
`evals`	`{"evaluations": [...], "next_cursor": <cursor or null>}`
`sessions`	`{"sessions": [...], "next_cursor": <cursor or null>}`
`errors`	`{"errors": [...], "next_cursor": <cursor or null>}`
`list <kind>`	`{"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": <n>, "status"?: <http>, "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의 필드 집합이 다르므로, 한쪽에서 유효한 이름이 다른 쪽에서는 거부될 수 있습니다.

​기본 원칙

​최초 설정

​작업 전 인증 확인

​실패하거나 점수가 낮은 세션 찾기

​세션 전체 읽기

​전체 가져오기 (페이지네이션)

​—fields로 출력 줄이기

​유효한 필터 값 탐색

​조직 선택 (멀티 테넌트)

​SDK/수집기용 API 키 생성

​저장된 쿼리 또는 즉석 쿼리 실행

​인시던트 비대화형으로 처리

​스크립트에서의 종료 코드 처리

​JSON 출력 구조