Impostazioni degli strumenti agentici

Gli strumenti agentici inviano a ogni passaggio il contenuto dei file, l’output dei comandi e tutta la cronologia della conversazione. Un prompt così grande può richiedere decine di secondi prima che arrivi il primo token. Se la tua app si arrende prima, la richiesta viene comunque conteggiata ma non ricevi nulla. Imposta timeout, streaming, retry e dimensione del contesto come indicato qui sotto.

Perché è importante

• Le richieste interrotte prima che arrivi la risposta vengono comunque conteggiate. Appena arriva una richiesta, il server IA inizia a elaborare l’intero prompt. Se la tua app la abbandona prima (timeout, pulsante stop, connessione persa), il costo dell’elaborazione è già stato sostenuto, ma non ricevi alcuna risposta.
• I prompt enormi richiedono più di 30 secondi prima del primo token. I prompt agentici da centinaia di KB con migliaia di messaggi possono superare il limite predefinito di molte app (30 o 60 secondi) prima che esca anche un solo token.
• Lo streaming tiene viva la connessione. Con lo streaming attivo, il nostro server invia subito gli header e poi un segnale keepalive ogni 10 secondi mentre attende la risposta. Ciò che può ancora interromperla è il limite di tempo totale della tua app, quindi impostalo ad almeno 300 secondi.
• Scegli un modello veloce per i contesti grandi. Per sessioni lunghe o repo grandi, usa un modello più veloce e tieni i modelli grandi per i passaggi che ne hanno davvero bisogno. Confrontali nella pagina Prezzi.

Linee guida per tutti gli strumenti

Timeout

Almeno 300 secondi. Attenzione all’unità: alcuni strumenti usano i secondi (300), altri i millisecondi (300000).

Streaming

Attivalo. Senza streaming non passa alcun dato finché la risposta non è completa, quindi proxy e app si arrendono prima.

Retry

Tienili bassi (0–3). Un retry dopo un timeout è una nuova richiesta, addebitata anch’essa. Correggi prima il timeout invece di aumentare i retry.

Contesto

Tienilo piccolo. Usa il compact/riepilogo automatico, avvia una nuova sessione per ogni attività ed escludi le cartelle grandi (node_modules, build, data).

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://ai.geraikita.com",
    "ANTHROPIC_AUTH_TOKEN": "gk-xxxxxxxx",
    "API_TIMEOUT_MS": "600000",
    "CLAUDE_CODE_MAX_RETRIES": "3",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "60"
  }
}

{
  "provider": {
    "geraikita": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Geraikita AI",
      "options": {
        "baseURL": "https://ai.geraikita.com/v1",
        "apiKey": "gk-xxxxxxxx",
        "timeout": 600000
      },
      "models": {
        "claude-sonnet-5": {
          "name": "Claude Sonnet 5",
          "limit": { "context": 128000, "output": 16000 }
        }
      }
    }
  },
  "compaction": { "auto": true }
}

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "geraikita": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://ai.geraikita.com/v1",
        "apiKey": "{env:GERAIKITA_API_KEY}",
        "headerTimeout": 300000,
        "chunkTimeout": 300000
      }
    }
  },
  "compaction": { "auto": true }
}

models:
  - name: Claude Sonnet 5 (Geraikita)
    provider: openai
    model: claude-sonnet-5
    apiBase: https://ai.geraikita.com/v1
    apiKey: gk-xxxxxxxx
    requestOptions:
      timeout: 600        # secondi, non millisecondi
    defaultCompletionOptions:
      contextLength: 64000  # più piccolo = cronologia tagliata
      maxTokens: 8192

from openai import OpenAI

client = OpenAI(
    base_url="https://ai.geraikita.com/v1",
    api_key="gk-xxxxxxxx",
    timeout=600.0,   # secondi
    max_retries=1,   # anche i retry dopo un timeout vengono addebitati
)
stream = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "Halo!"}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

import anthropic

client = anthropic.Anthropic(
    base_url="https://ai.geraikita.com",   # senza /v1
    api_key="gk-xxxxxxxx",
    timeout=600.0,   # secondi
    max_retries=1,   # anche i retry dopo un timeout vengono addebitati
)
with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=4096,
    messages=[{"role": "user", "content": "Halo!"}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

curl https://ai.geraikita.com/v1/chat/completions \
  --max-time 600 -N \
  -H "Authorization: Bearer gk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-5","stream":true,"messages":[{"role":"user","content":"Halo!"}]}'

Condizioni di addebito

Domande frequenti