Lezione gratuita

Stato e confini di un agente locale

Stato e confini di un agente locale — LangGraph: agente locale con stato e revisione. Il contratto del laboratorio; Descrivere lo stato; Definire passaggi osservabili. Esercitazione pratica: Pratica: Stato e confini di un agente locale.

Versione demo. I materiali sono in fase di revisione editoriale.

Argomenti trattati

  • Il contratto del laboratorio
  • Descrivere lo stato
  • Definire passaggi osservabili

Il contratto del laboratorio

Costruiremo un agente che legge una di due note didattiche e prepara un'anteprima. Non invia messaggi, non esegue comandi e non collega modelli. Un pianificatore deterministico sostituisce l'inferenza: la stessa richiesta produce lo stesso percorso. Possiamo così verificare orchestrazione, checkpoint e revisione umana separatamente dalla qualità del modello. LangGraph gestisce i passaggi fra nodi; il codice e l'ambiente stabiliscono i permessi sui file e sulla rete. Crea una cartella separata, installa le dipendenze solo se vuoi eseguire il laboratorio e conserva il lockfile. Sono comandi per lo studente, non eseguiti dall'autore. Il risultato previsto è un progetto piccolo con versioni registrate. Se un import fallisce, controlla Node e il pacchetto installato prima di cambiare nomi API documentati. Non serve alcuna chiave; una richiesta di credenziali segnala una dipendenza esterna inattesa.

mkdir langgraph-readonly-lab
cd langgraph-readonly-lab
npm init -y
npm install @langchain/langgraph @langchain/core zod
npm ls @langchain/langgraph @langchain/core zod

Descrivere lo stato

Lo stato definisce il contratto dei dati fra nodi. Salva il modulo come state.mjs. request contiene identificatore e argomento consentito, note il testo selezionato, proposal la proposta, digest il suo riferimento per la revisione, approved la decisione e preview il risultato didattico. I valori iniziali distinguono un campo vuoto da un aggiornamento omesso. Usiamo le API attuali StateSchema e Zod. Un nodo restituisce un aggiornamento parziale, per esempio solo note; gli altri campi rimangono disponibili. Normalmente un nuovo valore sostituisce quello precedente. Il nostro grafo è sequenziale, senza scrittori concorrenti sullo stesso campo: un reducer personalizzato aggiungerebbe complessità inutile. Valideremo separatamente l'input prima dell'avvio. Non inserire credenziali, connessioni o descrittori di file nello stato. I checkpoint devono contenere dati serializzabili, ricostruibili anche in un processo diverso.

// state.mjs
import { StateSchema } from '@langchain/langgraph';
import * as z from 'zod';
export const Request = z.object({
  id: z.string().regex(/^lab-[a-z0-9-]{1,32}$/),
  topic: z.enum(['backup', 'permissions'])
}).strict();
export const State = new StateSchema({
  request: Request,
  note: z.string().default(''),
  proposal: z.string().default(''),
  digest: z.string().default(''),
  approved: z.boolean().default(false),
  preview: z.string().default('')
});

Definire passaggi osservabili

Prima del grafo scrivi una tabella delle aspettative. Una richiesta backup seleziona quella nota; la lettura produce proposal; l'esecuzione si ferma su review prima dell'anteprima. Un rifiuto termina senza preview. L'approvazione crea soltanto una stringa locale, mai inviata a servizi esterni. Queste osservazioni diventeranno asserzioni nell'ultima lezione. Distingui request.id, identificatore del compito, da thread_id, indirizzo della cronologia di esecuzione. In un servizio reale il server autenticato deve determinare il proprietario del thread, senza fidarsi di identificatori arbitrari del client. Includi casi negativi: argomento sconosciuto rifiutato, proposta modificata da approvare nuovamente, altro thread incapace di recuperare il primo stato. Il risultato è una tabella con condizione, nodo successivo e campo osservabile. Se manca un campo che renda verificabile il comportamento, chiarisci il contratto prima di implementare altri nodi.

Esercitazione pratica

Pratica: Stato e confini di un agente locale

Vai alla lezione

Programma del corso

  1. Stato e confini di un agente locale
  2. Pianificatore e strumento di lettura
  3. Grafo e checkpoint
  4. Interruzione e revisione umana
  5. Stato dopo un riavvio
  6. Test riproducibili dell'agente