API LLM per Agent: Guida alla Chiamata di Funzioni
Un agent è un ciclo: il modello sceglie uno strumento, il tuo codice lo esegue, il risultato torna indietro e il modello decide cosa fare dopo. Ecco una versione funzionante di quel ciclo, più i limiti e i costi che dovresti pianificare.

Punti chiave
- L'endpoint supporta tools, tool_choice, tool_calls in streaming e risultati con ruolo tool.
- Limita il tuo ciclo, valida gli argomenti degli strumenti e riprova le risposte 429 con una breve attesa.
- Mantieni i worker paralleli a 8 o meno su una chiave completa; gli stream mantengono il loro slot fino alla fine.
- Un'esecuzione agent di sei passaggi con contesto in crescita costa circa mezzo centesimo.
Cosa serve all'agent dall'API
Se scegli un'API LLM Models per agent, la checklist è più breve di quanto suggerisca il marketing. Hai bisogno di chiamate di funzioni affidabili, una finestra di contesto abbastanza grande da contenere il transcript in corso, limiti di richieste prevedibili e un prezzo che non penalizzi un ciclo che fa molte chiamate.
Questa API copre questi punti tramite l'interfaccia standard OpenAI. Supporta tools e tool_choice, restituisce tool_calls in entrambe le risposte normali e in streaming, e accetta risultati degli strumenti come messaggi con role: "tool". La modalità JSON è disponibile tramite response_format. La finestra di contesto è di 100.000 token per prompt più completamento, e l'ID del modello è uncensored.
Poiché il lato framework è solo il client OpenAI, la maggior parte delle librerie agent che ti permettono di impostare un URL base funzionerà. Le punti verso https://api.llmmodelsapi.com/v1, fornisci la tua chiave e nomina il modello. I dettagli di configurazione sono nella documentazione, e puoi ottenere una chiave dalla pagina delle chiavi.
Due limiti plasmano il design. Primo, il modello è solo testo, quindi qualsiasi gestione di immagini, audio o file deve avvenire nei tuoi strumenti e tornare come testo. Secondo, non ci sono embeddings su questo endpoint, quindi se il tuo agent fa una ricerca, la ricerca vettoriale ha bisogno di un'altra fonte.
Un prompt di sistema che mantiene il ciclo stabile
La maggior parte dei fallimenti degli agent deriva da istruzioni vaghe, non dall'API. Un buon prompt di sistema dice al modello chi è, quali strumenti esistono, quando fermarsi e quale formato ha la risposta finale. Ecco uno per un assistente di ricerca.
Sei un assistente di ricerca. Puoi chiamare gli strumenti search_notes e read_note. Chiama uno strumento solo quando hai bisogno di informazioni che non hai già. Usa al massimo cinque chiamate di strumenti. Quando hai abbastanza informazioni, rispondi con una risposta breve e elenca gli ID delle note che hai usato. Se le note non contengono la risposta, dillo chiaramente.
Nota cosa fa. Nomina gli strumenti, imposta un budget di chiamate, definisce la condizione di arresto e dà al modello il permesso di dire che non lo sa. Quest'ultima parte è importante, perché un agent costretto a rispondere inventerà qualcosa.
Imposta una temperatura bassa per l'uso degli strumenti. Valori intorno a 0,2-0,4 mantengono stabili i nomi degli strumenti e i formati degli argomenti. Se il tuo agent scrive anche testo creativo alla fine, puoi aumentare la temperatura solo per quell'ultima chiamata. Il parametro seed viene passato attraverso, il che aiuta quando vuoi riprodurre un'esecuzione mentre esegui il debug.
Per agent di narrativa per adulti e roleplay, lo stesso pattern funziona: metti la persona, le regole della scena e gli strumenti nel messaggio di sistema. Il modello è ottimizzato per rispondere senza rifiuti di contenuti per l'uso adulto legale. I contenuti sessuali che coinvolgono minorenni rimangono fuori limite.
Un ciclo agent minimale in Python
Il ciclo qui sotto ha uno strumento, una ricerca in un dizionario che funge da dati reali. Si ferma quando il modello risponde senza una chiamata di strumento, o dopo un numero fisso di passaggi.
import json
from openai import OpenAI
client = OpenAI(base_url="https://api.llmmodelsapi.com/v1", api_key="YOUR_KEY")
NOTES = {
"n1": "Invoice 114 was paid on March 3.",
"n2": "Invoice 115 is overdue by 12 days.",
}
def search_notes(query):
return [{"id": k, "text": v} for k, v in NOTES.items() if query.lower() in v.lower()]
TOOLS = [{
"type": "function",
"function": {
"name": "search_notes",
"description": "Search internal notes by keyword",
"parameters": {
"type": "object",
"properties": {"query": {"type": "string"}},
"required": ["query"],
},
},
}]
SYSTEM = "You are a research assistant. Use search_notes when needed, at most five calls. Then answer briefly."
def run(question, max_steps=6):
messages = [
{"role": "system", "content": SYSTEM},
{"role": "user", "content": question},
]
for step in range(max_steps):
resp = client.chat.completions.create(
model="uncensored",
messages=messages,
tools=TOOLS,
temperature=0.3,
max_tokens=500,
)
msg = resp.choices[0].message
messages.append(msg)
if not msg.tool_calls:
return msg.content
for call in msg.tool_calls:
try:
args = json.loads(call.function.arguments)
result = search_notes(args["query"])
except Exception as exc:
result = {"error": str(exc)}
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(result),
})
return "Stopped: step limit reached."
print(run("Which invoice is overdue?"))
Tre dettagli meritano attenzione. Il limite di passaggi ferma un modello confuso dal fare loop finché il tuo budget non è esaurito. Il blocco try trasforma una stringa di argomento non valida in un messaggio di errore che il modello può leggere e correggere. E ogni risultato degli strumenti viene inviato di nuovo con il corrispondente tool_call_id, che è come il modello sa a quale chiamata appartiene ogni risposta.
Gestione delle risposte 429 e concorrenza
Gli agent sono a raffica. Un pianificatore può espandere cinque sotto-compiti in una volta, e ognuno di loro esegue il proprio loop. È lì che appaiono i limiti di richieste.
Una chiave completa permette 8 richieste concorrenti e 300 richieste al minuto. Una chiave di prova permette 2 e 60. Oltre il limite l'API risponde con HTTP 429. Il codice di errore ti dice quale limite hai raggiunto: rate_limited per richieste al minuto, concurrency per troppe in una volta. In caso di sovraccarico temporaneo ricevi anche un 429, con un'intestazione Retry-After: 5.
Tratta tutti questi come retryable. Attendi il numero di secondi nell'intestazione, o un paio di secondi se è assente, e invia di nuovo la richiesta. Le richieste fallite non vengono addebitate, quindi i retry costano zero. Un piccolo wrapper fa il lavoro.
import time
from openai import OpenAI, RateLimitError
client = OpenAI(base_url="https://api.llmmodelsapi.com/v1", api_key="YOUR_KEY", max_retries=0)
def chat_with_retry(**kwargs):
for attempt in range(5):
try:
return client.chat.completions.create(model="uncensored", **kwargs)
except RateLimitError as err:
wait = 5
if err.response is not None:
wait = int(err.response.headers.get("retry-after", 5))
time.sleep(wait)
raise RuntimeError("Still rate limited after 5 attempts")
Per evitare il 429 in primo luogo, limita il tuo pool di worker. Un semaforo di 8 corrisponde alla chiave completa. Se trasmetti risposte a un'interfaccia utente, ricorda che lo streaming mantiene il suo slot di concorrenza fino all'arrivo dell'ultimo token, quindi un client lento che legge una risposta lunga occupa uno slot per tutto il tempo. Leggere le intestazioni X-RateLimit-Limit-Requests e X-RateLimit-Limit-Concurrency permette al tuo codice di adattarsi a qualsiasi chiave stia usando.
Contesto, memoria e costi di un'esecuzione
Ogni passaggio del loop rispedisce l'intero transcript. È così che funzionano le API chat, e significa che i token di input crescono con ogni chiamata degli strumenti. Prendi un'esecuzione di sei passaggi dove il prompt inizia a 2.000 token e cresce di 1.000 per passaggio, con 300 token di output per passaggio.
- Token di input: 2.000 + 3.000 + 4.000 + 5.000 + 6.000 + 7.000 = 27.000
- Token di output: 6 x 300 = 1.800
- Costo input: 27.000 x 0,15 / 1.000.000 = $0,00405
- Costo output: 1.800 x 0,50 / 1.000.000 = $0,0009
- Totale: $0,00495 per esecuzione
Mille tali esecuzioni costano $4,95. È abbastanza economico da permettere a un agent di pensare in più passaggi, ma la crescita vale la pena di essere monitorata. Con 100.000 token di spazio, un agent a lungo termine riempirà eventualmente la finestra, e un prompt così grande costa 100.000 x 0,15 / 1.000.000 = $0,015 per input su ogni singolo passaggio.
Tre abitudini lo mantengono sotto controllo. Tronca grandi risultati degli strumenti prima che entrino nella cronologia, ad esempio i primi 2.000 caratteri di una pagina web. Riassumi i passaggi vecchi in un breve messaggio una volta che la cronologia supera una soglia. E memorizza fatti durevoli nel tuo database invece di fare affidamento sulla conversazione come memoria.
L'intestazione X-Balance-USD su ogni risposta mostra il credito rimanente, quindi un supervisore agent può fermare un'esecuzione quando il saldo scende sotto un livello minimo. Il credito è prepagato da $20, e non scade mai. Vedi la pagina dei prezzi per i bonus di ricarica.
Limiti onesti su cui pianificare
Gli agent costruiti su qualsiasi modello hanno bisogno di guardrail, e questo non fa eccezione. Preparati per quanto segue.
- Argomenti non validi. Il modello può produrre argomenti degli strumenti che non sono JSON validi o mancano un campo richiesto. Analizza con cautela e restituisci l'errore come risultato dello strumento.
- Scelta errata dello strumento. Scrivi descrizioni brevi e distinte degli strumenti. Se due strumenti suonano simili, il modello li confonderà. Usa
tool_choiceper forzare una chiamata specifica quando il flusso lo richiede. - Solo testo. Nessun input o output di immagini, nessun audio, nessun embedding, nessun fine-tuning. Fai quelle parti altrove e passa il risultato come testo.
- Modello singolo. C'è un unico modello a pesi aperti dietro l'endpoint, non un router tra fornitori. Non puoi scegliere un modello più piccolo per passaggi facili.
- Strumenti distruttivi. Non dare a un agent uno strumento di cancellazione o pagamento senza un passaggio di conferma nel tuo codice.
Gli agent di pianificazione beneficiano anche di un secondo passaggio. Dopo che il loop restituisce una risposta, puoi fare un'altra chiamata economica che chiede al modello di verificare la risposta contro i risultati degli strumenti che ha visto, usando la modalità JSON per restituire un verdetto e un elenco di affermazioni non supportate. Questo aggiunge qualche centinaio di token e cattura il fallimento più comune, che è una risposta sicura che ignora ciò che gli strumenti hanno restituito.
Infine, registra ogni passaggio. Memorizza i messaggi, gli argomenti degli strumenti e l'intestazione X-Request-Id da ogni risposta. Quando un'esecuzione va male, l'ID della richiesta ti permette di puntare alla chiamata esatta, e il transcript registrato mostra quale risultato degli strumento ha ingannato il modello. Gli agent sono più facili da migliorare quando puoi riprodurre una cattiva esecuzione e cambiare una cosa alla volta.
Testa un agent con la prova prima di impegnarti. I nuovi utenti possono richiedere $0,50 di credito, che per l'esecuzione di sei passaggi sopra copre circa 101 esecuzioni complete (0,50 / 0,00495). Tieni presente le 2 richieste concorrenti della prova e esegui un agent alla volta. Per una visione più ampia del servizio, leggi la panoramica pay-per-token. I prompt non sono usati per l'addestramento.
Altre guide
Domande e risposte
L'API supporta la chiamata di funzioni per gli agent?
Sì. Accetta strumenti e tool_choice, restituisce tool_calls (anche in streaming) e accetta i risultati come messaggi con role tool.
Quante chiamate agent possono essere eseguite in parallelo?
Una chiave completa permette 8 richieste concorrenti e 300 al minuto. Una chiave di prova ne permette 2 concorrenti e 60 al minuto.
Cosa deve fare un agent quando riceve un 429?
Attendi il valore Retry-After, o qualche secondo se non c'è, e riprova. Le richieste rifiutate non vengono addebitate.
L'agent può gestire immagini o audio?
No. Il modello funziona solo con testo, quindi qualsiasi altro supporto deve essere elaborato dai tuoi strumenti e passato come testo.
La tua chiave è a un modulo di distanza
Crea un account, copia la chiave, modifica l'URL di base. È tutta la configurazione.