IT ▾
Ottieni la chiave API

Documentazione LangChain Agentic AI: Strumenti e modalità JSON

La maggior parte della documentazione LangChain Agentic AI presuppone una classe modello proprietaria del fornitore, ma qualsiasi endpoint compatibile con OpenAI funziona con ChatOpenAI una volta impostato un base URL. Questa guida collega LangChain a questa API e costruisce un agent con chiamata di funzioni passo dopo passo.

Aggiornato

Punti chiave

  • Usa ChatOpenAI con base_url impostato su questa API e model impostato su uncensored.
  • La chiamata di funzioni e la modalità JSON sono supportate, quindi bind_tools e response_format funzionano come documentato.
  • Limita i cicli degli agenti, convalida gli argomenti degli strumenti e mantieni max_concurrency a 8 o meno con una chiave completa.
  • Lo streaming su SSE restituisce l'utilizzo dei token alla fine, il che ti aiuta a tracciare il costo di ogni esecuzione dell'agent.
Braccio robotico che sposta cubi attraverso stazioni di strumenti su un percorso a loop, che rappresenta un loop di agent LangChain

Cosa ti serve prima di iniziare

Se stai leggendo la documentazione di LangChain per l'intelligenza artificiale agentica e ti chiedi cosa cambia quando il modello non proviene dal fornitore degli esempi, la risposta è: pochissimo. Un agente in LangChain è un ciclo: il modello legge la conversazione, decide se chiamare uno strumento, il tuo codice esegue lo strumento e il risultato torna al modello finché non produce una risposta finale. L'endpoint del modello deve solo supportare le completions per chat con chiamata di funzioni, e questa API lo fa.

Ti servono tre cose: una chiave API dalla pagina delle chiavi, Python 3.10 o superiore e i pacchetti seguenti. Il base URL è https://api.unlimitedaiapi.com/v1 e l'ID del modello è uncensored. È un modello a pesi aperti gestito da un provider indipendente, quindi non c'è un elenco di modelli tra cui scegliere; GET /v1/models lo restituisce per la scoperta del client.

pip install -U langchain langchain-openai
export UNLIMITED_API_KEY="your-key-here"

Passo 1: connetti ChatOpenAI all'endpoint

La classe ChatOpenAI di LangChain accetta un base_url personalizzato. Tutto il resto rimane invariato, incluse le varianti invoke, stream, batch e async.

import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="uncensored",
    base_url="https://api.unlimitedaiapi.com/v1",
    api_key=os.environ["UNLIMITED_API_KEY"],
    temperature=0.2,
)

print(llm.invoke("Reply with one short sentence.").content)

Se questo stampa una frase, autenticazione, routing e nome del modello sono tutti corretti. L'autenticazione utilizza l'intestazione standard Authorization: Bearer, che la classe aggiunge per te. Un errore comune è dimenticare /v1 nel base URL, il che solitamente fa fallire la prima chiamata.

Fase 2: definisci gli strumenti e collegali

Gli strumenti sono semplici funzioni Python con una docstring. La docstring e gli hint di tipo diventano lo schema che il modello vede, quindi scrivili come se stessi spiegando la funzione a un nuovo collega.

import os
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI

@tool
def get_order_status(order_id: str) -> str:
    '''Look up the status of an order by its ID, for example A100.'''
    return {"A100": "shipped", "A101": "processing"}.get(order_id, "not found")

llm = ChatOpenAI(
    model="uncensored",
    base_url="https://api.unlimitedaiapi.com/v1",
    api_key=os.environ["UNLIMITED_API_KEY"],
    temperature=0,
)
llm_with_tools = llm.bind_tools([get_order_status])

ai = llm_with_tools.invoke("Where is order A100?")
print(ai.tool_calls)

L'elenco stampato contiene una chiamata con il nome get_order_status e argomenti come {"order_id": "A100"}. Sotto il cofano LangChain invia la tua funzione come voce nell'array tools della richiesta di completions per chat e l'API supporta tools, tool_choice e tool_calls in streaming. Per forzare una chiamata di funzione, passa tool_choice a bind_tools.

Perché la temperatura è bassa

Gli agenti concatenano più chiamate al modello, quindi un singolo argomento malformato può compromettere un'esecuzione. Una temperatura tra 0 e 0,2 rende la selezione degli strumenti più ripetibile. Aumentala solo per il passaggio della risposta finale se vuoi una prosa più varia.

Passo 3: esegui il loop dell'agent

Scrivere il ciclo da te richiede quindici righe e mostra esattamente cosa succede a ogni passaggio, il che aiuta quando qualcosa va storto. I risultati degli strumenti tornano al modello come oggetti ToolMessage, che diventano messaggi role: "tool" in transito.

import os
from langchain_core.messages import HumanMessage, ToolMessage
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI

@tool
def get_order_status(order_id: str) -> str:
    '''Look up the status of an order by its ID, for example A100.'''
    return {"A100": "shipped", "A101": "processing"}.get(order_id, "not found")

llm = ChatOpenAI(
    model="uncensored",
    base_url="https://api.unlimitedaiapi.com/v1",
    api_key=os.environ["UNLIMITED_API_KEY"],
    temperature=0,
)
tools = {"get_order_status": get_order_status}
llm_with_tools = llm.bind_tools(list(tools.values()))

messages = [HumanMessage("Where is order A100, and what about A101?")]
for _ in range(5):                      # hard cap on loop length
    ai = llm_with_tools.invoke(messages)
    messages.append(ai)
    if not ai.tool_calls:
        break
    for call in ai.tool_calls:
        result = tools[call["name"]].invoke(call["args"])
        messages.append(ToolMessage(content=str(result), tool_call_id=call["id"]))

print(ai.content)

Nota range(5). Un agent senza limite di passaggi può andare in loop all'infinito su un risultato di strumento confuso e ogni passaggio costa token di input per l'intera conversazione finora. Cinque è un soffitto ragionevole per compiti semplici; aumentalo deliberatamente.

Utilizzo dell'helper per agent predefiniti

Le versioni recenti di LangChain includono un helper che esegue questo ciclo per te. Il nome e il percorso di importazione sono cambiati tra le versioni, quindi conferma i dettagli rispetto alla documentazione della versione installata. Nella linea 1.x attuale appare così:

import os
from langchain.agents import create_agent
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI

@tool
def get_order_status(order_id: str) -> str:
    '''Look up the status of an order by its ID, for example A100.'''
    return {"A100": "shipped", "A101": "processing"}.get(order_id, "not found")

llm = ChatOpenAI(
    model="uncensored",
    base_url="https://api.unlimitedaiapi.com/v1",
    api_key=os.environ["UNLIMITED_API_KEY"],
    temperature=0,
)

agent = create_agent(llm, tools=[get_order_status], system_prompt="You are a concise support assistant.")
result = agent.invoke({"messages": [{"role": "user", "content": "Where is order A100?"}]})
print(result["messages"][-1].content)

Usa l'helper quando vuoi il pattern standard e il loop scritto a mano quando hai bisogno di regole di arresto personalizzate, logging per passaggio o risultati degli strumenti che vuoi filtrare prima che il modello li veda.

Output strutturato con modalità JSON

Gli agenti spesso devono passare dati ad altri codici, come un piano, una classificazione o un elenco di campi estratti. La modalità JSON forza la risposta a essere un oggetto JSON valido. In LangChain puoi passarla tramite bind:

import json
import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="uncensored",
    base_url="https://api.unlimitedaiapi.com/v1",
    api_key=os.environ["UNLIMITED_API_KEY"],
    temperature=0,
)
json_llm = llm.bind(response_format={"type": "json_object"})

msg = json_llm.invoke(
    "Extract the city and country from: 'I moved to Lyon, France last spring.' "
    "Answer as JSON with the keys city and country."
)
print(json.loads(msg.content))

Menziona la parola JSON nel prompt e descrivi le chiavi che ti aspetti, come nell'esempio. La modalità JSON garantisce la sintassi, non il tuo schema, quindi valida comunque l'oggetto analizzato (con Pydantic, ad esempio) e gestisci una chiave mancante.

Limiti, streaming e costi per le esecuzioni degli agent

Gli agenti fanno molte chiamate in breve tempo, quindi i limiti dell'account sono più importanti che per un semplice chatbot. Una chiave completa permette 8 richieste parallele e 300 richieste al minuto. Una chiave di prova permette 2 e 60. Se fai fan-out con batch o esegui più agenti contemporaneamente, limita la parallelità nella configurazione:

import os
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="uncensored",
    base_url="https://api.unlimitedaiapi.com/v1",
    api_key=os.environ["UNLIMITED_API_KEY"],
)
prompts = ["Name one prime number.", "Name one even number.", "Name one square number."]
answers = llm.batch(prompts, config={"max_concurrency": 8})
for a in answers:
    print(a.content)

Usa 2 invece di 8 sulla chiave di prova. Per gli agent interattivi, llm.stream(...) restituisce i token su SSE man mano che vengono generati e i numeri di utilizzo arrivano alla fine dello stream.

Il costo è facile da stimare. Un'esecuzione a 5 passaggi che in media utilizza 4.000 token di input e 300 token di output per passaggio usa 20.000 token di input e 1.500 token di output in totale, che sono $0,003 + $0,00075 = $0,00375 per esecuzione alle tariffe di $0,15 e $0,50 per 1M di token. La pagina prezzi ha le tariffe e la documentazione elenca i parametri e le intestazioni della richiesta, incluso X-Request-Id per tracciare una singola chiamata fallita.

Progettazione degli strumenti utilizzabili dal modello

La maggior parte dei fallimenti degli agent risale agli strumenti, non al loop. Alcune regole aiutano con qualsiasi modello:

  • Mantieni ogni strumento limitato. Uno strumento chiamato get_order_status funziona meglio di uno chiamato database_query che accetta testo libero.
  • Usa tipi di argomento semplici: stringhe, interi e enum brevi. Oggetti profondamente annidati danno al modello più modi per sbagliare un campo.
  • Restituisci risultati brevi e semplici. Uno strumento che riversa 50.000 caratteri nella conversazione riempie la finestra di contesto e aumenta il costo di ogni passaggio successivo.
  • Restituisci gli errori come testo, ad esempio "order_id deve assomigliare a A100", invece di sollevare eccezioni che terminano l'esecuzione.

Testa l'agente su un piccolo gruppo di prompt reali con il credito di prova da $0,50 prima di scalare. I nuovi utenti lo ottengono con un clic sulla pagina delle chiavi ed è valido per 7 giorni.

Insidie da controllare per prime

  • La chiamata di funzione non appare mai. Rendi il docstring specifico, abbassa la temperatura o forza la chiamata con tool_choice.
  • Argomenti non validi. Convalida all'interno dello strumento e restituisci una stringa di errore chiara, in modo che il modello possa correggersi al passaggio successivo.
  • Crescita del contesto. La finestra è di 100.000 token inclusa la risposta. Taglia i vecchi output degli strumenti prima che riempiano la finestra.

Domande e risposte

Quale classe LangChain funziona con questa API?

ChatOpenAI da langchain-openai. Imposta base_url su https://api.unlimitedaiapi.com/v1, e il modello su uncensored, passando la tua chiave come api_key.

L'API supporta la chiamata di funzioni per gli agent?

Sì. Accetta i parametri tools e tool_choice, restituisce tool_calls (anche in streaming) e accetta i risultati come messaggi con role tool.

LangChain può analizzare l'output strutturato tramite questa API?

Sì, tramite la modalità JSON: imposta response_format su un tipo json_object. Garantisce una sintassi JSON valida, quindi valida i campi tu stesso.

Quanti agenti posso eseguire in parallelo?

Una chiave completa permette 8 richieste parallele e 300 al minuto. La chiave di prova permette 2 richieste parallele e 60 al minuto.

La tua chiave è a un modulo di distanza

Crea un account, copia la chiave, modifica l'URL di base. È tutta la configurazione.

Ottieni la chiave API