HomeGuida
Aggiornato
Finestra di contesto per agent AI: come si usano 100k token
La finestra di contesto di un agent AI è lo spazio totale in token condiviso tra prompt, risultati degli strumenti e risposta del modello. Su questa API quello spazio è di 100.000 token e gli agent a lunga esecuzione tendono a riempirlo più velocemente del previsto.

Punti chiave
- La finestra da 100.000 token copre prompt e completion, quindi ogni risultato di tool che mantieni riduce lo spazio per l'output successivo.
- In un ciclo agent, l'intera cronologia viene inviata di nuovo a ogni passaggio, quindi l'input totale cresce col quadrato del numero di passaggi, non linearmente.
- Riduci prima i vecchi output degli strumenti, mantieni il prompt di sistema e gli ultimi turni, e misura con il campo usage.
- Un ciclo di 20 passaggi con 1.500 nuovi token per passaggio costa circa $0,055 in totale.
Nessuna carta necessaria. Dopo la registrazione, ottieni $0,50 di credito di prova gratuito con un clic (una volta per persona).
Ottieni la chiave APILa risposta breve: un budget condiviso di 100.000 token
Quando le persone cercano la finestra di contesto di un agente AI, di solito vogliono sapere quanto può ricordare un agente prima di andare in errore. Qui il numero è 100.000 token, e conta tutto: il prompt di sistema, le definizioni dei tool, ogni messaggio precedente, ogni risultato di tool e la completion che il modello sta per scrivere. La completion può utilizzare tutto ciò che resta, e max_tokens è opzionale.
Questo trasforma la finestra in un budget, non in uno spazio di archiviazione. Un chatbot raramente si avvicina al limite. Un agente che chiama tool in un ciclo può raggiungerlo nel pomeriggio, perché ogni passaggio aggiunge un messaggio del modello e un risultato di tool alla cronologia, e l'intera cronologia viene inviata di nuovo alla chiamata successiva. Il modello non ha memoria tra le richieste. Ciò che sembra memoria sei tu che reinvii la cronologia.
Cosa riempie effettivamente la finestra in un agent
La maggior parte dello spazio non è il testo dell'utente. Monitora queste cinque fonti e potrai prevedere dove un'esecuzione si esaurirà.
- System prompt. Regole, persona e formato di output. Spesso 500-2.000 token e inviato a ogni chiamata.
- Definizioni degli strumenti. Ogni nome di funzione, descrizione e schema JSON conta. Dieci strumenti con descrizioni lunghe possono costare diverse migliaia di token prima del primo messaggio dell'utente.
- Risultati degli strumenti. Il colpevole più comune. Un risultato di ricerca, un dump di file o un set di righe di database possono essere migliaia di token e rimangono nella cronologia a meno che non lo rimuovi.
- Messaggi dell'assistente. Ragionamento scritto in testo e gli argomenti di
tool_callsprodotti dal modello. - La risposta in fase di generazione. Ha bisogno di spazio anche lei. Se il prompt è di 99.000 token, alla risposta restano circa 1.000 token.
L'API riporta i numeri esatti nel blocco usage di ogni risposta, quindi non devi indovinare. Registra prompt_tokens dopo ogni passaggio e vedrai la curva.
Un esempio pratico: 20 passaggi di un loop di strumenti
Prendi un agent con un avvio da 3.000 token (system prompt più definizioni degli strumenti). Ogni passaggio aggiunge circa 1.500 token alla cronologia: la chiamata agli strumenti del modello e il risultato dello strumento. Scrive anche circa 300 token di output per passaggio. L'agent esegue 20 passaggi.
L'input al passaggio k è 3.000 + 1.500 × (k − 1). Sommato su 20 passaggi:
- 3.000 × 20 = 60.000 token per l'avvio fisso, reinviato ogni volta.
- 1.500 × (0 + 1 + ... + 19) = 1.500 × 190 = 285.000 token di cronologia accumulata.
- Input totale: 345.000 token. Output totale: 20 × 300 = 6.000 token.
| Voce | Token | Prezzo per 1M | Costo |
|---|---|---|---|
| Input | 345,000 | $0.15 | $0.05175 |
| Output | 6,000 | $0.50 | $0.003 |
| Totale | circa $0,055 |
Due cose spiccano. Primo, il contesto al passo 20 è 3.000 + 1.500 × 19 = 31.500 token, ben all'interno della finestra, ma hai pagato per 345.000 token di input, perché la cronologia è stata reinviata ogni volta. Secondo, una singola chiamata con una finestra completamente piena (100.000 token di input) costa 100.000 × $0,15 / 1M = $0,015 per il lato input. Contesti lunghi sono convenienti per chiamata; il costo deriva dal ripeterli su molti passaggi. Vedi la pagina dei prezzi per le tariffe e i bonus di ricarica.
Quanti passaggi entrano prima che la finestra sia piena
Puoi stimarlo prima di scrivere qualsiasi codice. Tieni una riserva per la risposta, diciamo 20.000 token, che lascia un budget di 80.000 token per il prompt. Con un avvio di 3.000 token e 1.500 token aggiunti per passaggio, la cronologia raggiunge quel budget dopo (80.000 − 3.000) / 1.500, o circa 51 passaggi.
Ora valuta un'esecuzione di quella lunghezza. Su 51 passaggi l'input è 3.000 × 51 + 1.500 × (0 + 1 + ... + 50) = 153.000 + 1.500 × 1.275 = 153.000 + 1.912.500 = 2.065.500 token. Output a 300 token per passaggio è 15.300 token. Costo: 2.065.500 × $0,15 / 1M = $0,30983, più 15.300 × $0,50 / 1M = $0,00765, quindi circa $0,32.
Confrontalo con l'esecuzione di 20 passaggi a circa $0,055. L'esecuzione è 2,55 volte più lunga ma costa circa 5,8 volte di più, perché ogni passaggio trasporta una cronologia più lunga. Questa è la ragione pratica per tagliare la cronologia: limita il costo per passaggio e protegge la finestra.
Tenere un agent all'interno della finestra
Riduci prima i vecchi output degli strumenti
I risultati grezzi degli strumenti sono la parte più grande e meno utile di una vecchia cronologia. Una volta che il modello ha agito su un elenco di file, raramente ha bisogno dell'elenco di nuovo. Sostituisci i vecchi risultati con uno stub di una riga come "risultato rimosso, 4.200 token", o elimina la coppia interamente.
Riassumi la parte centrale, mantieni entrambe le estremità
Mantieni il system prompt e gli ultimi pochi turni letteralmente. Per tutto il resto, chiedi al modello un breve riassunto delle decisioni prese e dei fatti trovati, quindi archivia quel riassunto come un singolo messaggio. Esegui la chiamata di riassunto prima di raggiungere il limite, non dopo.
Sposta i fatti fuori dal transcript
Se l'agent impara qualcosa che deve mantenere per ore, scrivilo su un file o un piccolo database tramite uno strumento, e leggilo di nuovo quando necessario. Questo è più economico che trasportarlo in ogni richiesta e sopravvive ai riavvii.
Mantieni gli schemi degli strumenti brevi
Riduci le descrizioni a ciò di cui il modello ha bisogno per scegliere lo strumento. Passa solo gli strumenti rilevanti per la fase corrente del compito.
Codice: un loop di strumenti con un budget di token
Questo loop taglia i messaggi più vecchi quando la dimensione approssimativa supera un budget di 80.000 token, lasciando spazio per la risposta. La stima divide i caratteri per quattro, un'approssimazione comune per il testo inglese; il conteggio reale torna in usage. Il taglio elimina i messaggi tool orfani in modo che un risultato non appaia mai senza la sua chiamata.
import json, os
from openai import OpenAI
client = OpenAI(base_url="https://api.aivideogenapi.com/v1", api_key=os.environ["API_KEY"])
BUDGET = 80_000
tools = [{"type": "function", "function": {
"name": "get_scene_length",
"description": "Return the length of a scene in seconds",
"parameters": {"type": "object",
"properties": {"scene": {"type": "integer"}},
"required": ["scene"]}}}]
def rough_tokens(messages):
return sum(len(json.dumps(m)) for m in messages) // 4
def trim(messages):
system, rest = messages[0], messages[1:]
while rough_tokens([system] + rest) > BUDGET and len(rest) > 4:
rest.pop(0)
while rest and rest[0]["role"] == "tool":
rest.pop(0)
return [system] + rest
def run_tool(name, args):
return json.dumps({"seconds": 4 * args["scene"]}) # stub
messages = [
{"role": "system", "content": "You plan video scenes. Use tools for lengths."},
{"role": "user", "content": "Total the length of scenes 1 to 5."},
]
for step in range(20):
resp = client.chat.completions.create(
model="uncensored", messages=trim(messages), tools=tools)
msg = resp.choices[0].message
messages.append(msg.model_dump(exclude_none=True))
print(step, resp.usage.prompt_tokens)
if not msg.tool_calls:
print(msg.content)
break
for call in msg.tool_calls:
result = run_tool(call.function.name, json.loads(call.function.arguments))
messages.append({"role": "tool", "tool_call_id": call.id, "content": result})
La chiamata agli strumenti segue il formato OpenAI: tools, tool_choice, e i risultati restituiti come role: "tool". La documentazione elenca i parametri che vengono trasmessi.
Limiti importanti oltre alla finestra
La finestra è un vincolo. Gli agenti incontrano anche limiti di richiesta. Una chiave completa permette 8 richieste concorrenti e 300 richieste al minuto; una chiave di prova ne permette 2 e 60. Un ciclo stretto con sott-agenti paralleli può superare rapidamente il limite di concorrenza. L'API risponde con HTTP 429 e il codice di errore concurrency o rate_limited, e in caso di sovraccarico temporaneo con l'intestazione Retry-After: 5. Attendi quel tempo e riprova.
Se usi lo streaming, ricorda che una richiesta in streaming occupa il suo slot di concorrenza fino alla fine del flusso. Un client bloccato che non chiude mai il flusso mantiene uno slot occupato.
Il corpo massimo è 8 MB, che è molto più di 100.000 token di testo, quindi la finestra è il limite che colpirai per primo. Per un esempio di pipeline solo testo basata su questa API, vedi la guida agli script video. Quando sei pronto per eseguirla, crea una chiave API; i nuovi utenti possono richiedere $0,50 di credito di prova con un clic, valido per 7 giorni e senza bisogno di pagamento.
Altre guide
Domande e risposte
Quanto è grande la finestra di contesto?
100.000 token, contando prompt e completamento insieme. Il completamento può usare tutto ciò che il prompt lascia libero.
Il modello ricorda le richieste precedenti?
No. Ogni richiesta è indipendente, quindi il tuo codice deve reinviare i messaggi che vuole che il modello veda.
Cosa succede se superi il limite?
La richiesta non entra, quindi riduci o riassumi la cronologia prima di inviare. Le richieste fallite non vengono addebitate.
Come conto i token?
Leggi prompt_tokens e completion_tokens dal blocco di utilizzo di ogni risposta, oppure usa una stima approssimativa di quattro caratteri per token per l'inglese prima di inviare.
La tua chiave è a un modulo di distanza
Crea un account, copia la chiave, modifica l'URL di base. È tutta la configurazione.