> ## 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.

# Ricette CLI per agenti

> Documentazione delle ricette CLI di AgentEye per agenti.

Estrai dati di sessione, evento e valutazione (e attiva rivalutazioni) direttamente da uno script o da un agente di codifica, con JSON pulito su stdout che si collega direttamente a `jq`. Queste ricette trasformano i dati di osservabilità di AgentEye in qualcosa che un utente di terminale o un agente di codifica AI (Claude Code, Cursor) può interrogare e automatizzare, senza cliccare sulla dashboard.

I modelli seguenti sono pronti per il copia-incolla sulla CLI di AgentEye (`agenteye`). Per l'installazione, l'autenticazione e l'elenco completo delle opzioni, vedi [CLI](/it/agenteye/cli); esegui `agenteye -h` o `agenteye <command> -h` per l'aiuto integrato.

## Regole d'oro

1. **Le opzioni globali vanno *prima* del comando.** `agenteye --json sessions` è corretto; `agenteye sessions --json` non lo è. Le opzioni globali sono `--json`, `--base-url`, `--org`, `--token`, `--insecure`/`--secure`, `--timeout`, `--quiet`, `--no-color`.
2. **Passa `--json` ogni volta che analizzi l'output.** I dati vanno su **stdout** come JSON; i messaggi di stato umani e gli errori vanno su **stderr**, quindi stdout rimane pulito per collegarsi a `jq`.
3. **Ramifica in base al codice di uscita**, non al testo di stderr: `0` ok · `2` argomenti errati · `3` impossibile raggiungere la dashboard · `4` non connesso o sessione scaduta · `5` permesso mancante.
4. **Scopri con `-h`.** Ogni comando documenta i suoi filtri, i formati di valore e la forma JSON.

## Configurazione una tantum

```bash theme={null}
export AGENTEYE_DASHBOARD_URL=https://agenteye.example.com   # così non ripeti --base-url
agenteye login --email you@example.com                       # incolla il codice inviato per email; valido ~24h
```

## Conferma autenticazione prima di lavorare

`whoami` non genera mai errori per una sessione mancante o scaduta; invece riporta `logged_in:false`, quindi un agente può sondare lo stato di autenticazione in sicurezza. (Può comunque uscire con codice diverso da zero se nessun URL di base è impostato o la dashboard è irraggiungibile.)

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

## Trova sessioni con fallimento o punteggio basso

```bash theme={null}
# sessioni nelle ultime 24h la cui valutazione ha errore
agenteye --json sessions --since 24h --status error | jq -r '.sessions[].session_id'

# valutazioni con punteggio <= 0.5 su utilità, per un agente
agenteye --json evals --agent-id checkout-bot --score helpfulness:..0.5 \
  | jq '.evaluations[] | {session_id, scores}'
```

Il filtro dei punteggi si trova su **`evals`**, non su `sessions`. `--score KEY:MIN..MAX` è ripetibile e combinato con AND; entrambi i limiti sono opzionali (`..0.5` significa ≤ 0.5, `0.9..` significa ≥ 0.9). Puoi passare fino a 20 filtri di punteggio per richiesta; più di questo restituisce HTTP 400. `sessions` condivide i filtri `--env`, `--status`, `--agent-id`, `--session-id` e intervallo di tempo con `evals`, ma non ha `--score`.

## Leggi una sessione da capo a fondo

Non c'è un singolo comando `session show` — combina la traccia di eventi con la valutazione della sessione:

```bash theme={null}
# l'ultima valutazione della sessione (stato + punteggi)
agenteye --json evals --session-id run-001 | jq '.evaluations[0] | {status, scores}'

# ogni evento nell'esecuzione (aumenta --limit per una scansione completa)
agenteye --json events --session-id run-001 --all --limit 1000 | jq '.events[] | {ts, event_type}'

# solo le chiamate tool in una sessione
agenteye --json events --session-id run-001 --event-type tool_use,tool_result --all \
  | jq '.events[].payload'
```

## Recupera tutto (paginazione)

I risultati sono in ordine più recente prima e impaginati con cursore.

```bash theme={null}
# una sola volta: recupera fino a 500 righe in pagine di 200 righe
agenteye --json events --session-id run-001 --limit 500 --all > events.json

# paginazione manuale: reinserisci 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"
```

## Riduci l'output con --fields

Limita le chiavi (sia nella tabella che in `--json`) per ridurre ciò che un agente deve leggere.

```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
```

I nomi di campo sconosciuti vengono rifiutati (uscita `2`) con l'elenco valido, un modo economico per scoprire i nomi dei campi.

## Scopri valori di filtro validi

```bash theme={null}
agenteye --json list envs | jq -r '.values[]'           # valori per --env
agenteye --json list tools | jq -r '.values[]'          # nomi tool; anche agenti, modelli, event_types, …
agenteye --json list score_filters | jq -r '.values[]'  # KEY valido per --score KEY:MIN..MAX
```

## Scegli la tua organizzazione (multi-tenant)

Se appartieni a più di un'organizzazione, scegli il tenant attivo al login (viene salvato):

```bash theme={null}
agenteye login --org acme --email you@corp.com   # imposta il tenant nello stesso passaggio del login
agenteye --json orgs list | jq -r '.orgs[].org_slug'
agenteye --org globex --json sessions --since 24h   # sostituisci per un comando
```

Un login multi-org senza `--org` esce con codice diverso da zero e stampa le organizzazioni tra cui scegliere.

## Provisioning di una chiave API per SDK/collector

```bash theme={null}
# il segreto è stampato UNA VOLTA — con --json è il campo .key
key=$(agenteye --json keys create ci-bot --add events:read.add | jq -r '.key')
agenteye keys regenerate ci-bot --yes    # ruota; agenteye keys disable ci-bot --yes per revocare
```

## Esegui una query salvata o ad hoc

```bash theme={null}
agenteye --json query run --sql "select count(*) from analytics.events" | jq '.rows'
agenteye --json query run errs --arg prod | jq '.rows'   # una query salvata + un $1 posizionale
```

## Triage di un incident non interattivamente

```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
```

> Le mutazioni saltano automaticamente il prompt di conferma con `--json` o quando stdin non è un TTY, quindi gli agenti non si bloccano mai; passa `--yes`/`-y` per saltarlo esplicitamente altrove.

## Gestione del codice di uscita in uno script

```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
```

## Forme di output JSON

| Comando                           | JSON stdout (con `--json`)                                                                                                                   |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `whoami`                          | `{"logged_in": true, "id", "email", "is_instance_admin", "active_org", "permissions": [...], "memberships": [...]}` o `{"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` mostrato una volta)                                                    |
| `query run`                       | `{columns: [{name,type}], rows: [[...]], truncated, elapsed_ms}`                                                                             |
| `users list` / `settings list`    | `{"users": [...]}` / `{"settings": [...]}`                                                                                                   |
| `alerts list` / `incidents list`  | `{"alerts": [...]}` / `{"incidents": [...]}`                                                                                                 |
| create/update/delete (qualsiasi)  | l'oggetto risorsa, o `{"deleted": true, "id"}` per eliminazioni                                                                              |
| failure (qualsiasi, con `--json`) | `{"error": "...", "exit_code": <n>, "status"?: <http>, "hint"?: "..."}` su stdout                                                            |

* Ogni elemento **event** (`events`): `id, session_id, agent_id, event_type, ts, payload, environment`.
* Ogni elemento **evaluation** (`evals`): `id, session_id, agent_id, environment, status, scores, reasoning, summary, error, attempt_count, duration_ms, completed_at, created_at`.
* Ogni elemento **session** (`sessions`): `session_id, agent_id, environment, status, scores, event_count, started_at, last_event_at, first_event_id, last_event_id, latest_evaluation`.

Ogni `--fields` del comando accetta esattamente i nomi dei campi del suo elemento — l'insieme è diverso tra `sessions` e `evals`, quindi un nome valido per uno può essere rifiutato dall'altro.