Salta ai contenuti
AggregaAggrega
Seleziona lingua: Italiano
Questa pagina è stata tradotta automaticamente. Leggi l’originale in inglese.

Importare un’applicazione LangGraph

Questa procedura guidata importa la configurazione di un’applicazione LangGraph — un grafo che risponde alle domande dei clienti sui loro ordini — e compila l’applicazione per Docker Compose. L’importazione produce in bozza ogni file che la build legge: il grafo, il database PostgreSQL in cui il suo checkpointer conserva lo stato, il modello che chiama, le password e la chiave come riferimenti a variabili, e le realizzazioni di ciascuno. Chiede una sola volta i due valori che nessuna configurazione contiene: il modello che il codice del grafo chiama e l’immagine in cui l’applicazione viene eseguita. Ogni file e ogni blocco di output riportati di seguito provengono da un’esecuzione reale; la configurazione e ogni fase della procedura si trovano nell’esempio import-langgraph, dove uno script di verifica esegue di nuovo l’importazione, confronta ciò che scrive, ciò che stampa e i blocchi citati in questa pagina con i file lì conservati, e convalida e compila ciò che l’importazione ha scritto.

Generare l’esempio

Puoi eseguire questa importazione con i comandi di questa pagina, oppure farla eseguire al tuo assistente AI.

Scrivi l’esempio in una nuova cartella che porta il suo nome:

Terminal window
aggrega scaffold --example import-langgraph

Poi stampa i prossimi comandi da eseguire. Il primo ti porta nella nuova cartella; quello successivo, qui sotto, ti porta nella cartella source della nuova cartella, che contiene ciò che questa pagina importa ed è dove viene eseguita l’importazione:

Terminal window
cd import-langgraph

La cartella source dell’esempio generato aperta in Visual Studio Code, che mostra la sua configurazione LangGraph, che nomina un grafo, support.

Il progetto

Un’applicazione LangGraph mantiene i propri grafi nel codice e li dichiara in langgraph.json, il file di configurazione dello strumento a riga di comando di LangGraph. Questa, scritta per questa procedura guidata, dichiara un grafo, support, tramite il percorso di importazione del grafo nel codice dell’applicazione e una descrizione:

{
"$schema": "https://langgra.ph/schema.json",
"dependencies": ["."],
"python_version": "3.12",
"graphs": {
"support": {
"path": "./src/support_agent/graph.py:graph",
"description": "Answers a question from a customer about their order, and hands it to a person when it cannot."
}
}
}

L’importazione legge langgraph.json e mai il codice dell’applicazione, quindi l’esempio contiene solo la configurazione. Accanto a essa, un .aggrega-config.yaml rende la cartella un workspace:

# The workspace key marks this directory as the workspace root, so an import run
# here writes its drafts beside langgraph.json.
workspace: {}
# The registry the importer is fetched from the first time an import needs it.
default_registry: hub.aggrega.ai

L’importazione fa riferimento ai Components del catalogo per l’agente LangGraph, per PostgreSQL e per il modello OpenAI, e --target abbozza un Manifest a partire dalle Recipes del catalogo. Lo spazio di lavoro non indica alcuna cartella di catalogo, quindi l’importazione legge il catalogo della libreria standard dal registry da cui recupera il proprio importer: uno snapshot firmato del catalogo pubblicato, che la prima importazione recupera, verifica e conserva nella cache dei contenuti dello spazio di lavoro, e che il record scritto dall’importazione accanto alle sue bozze indica tramite il suo digest. Uno spazio di lavoro che indica le proprie cartelle di catalogo — in AGGREGA_CATALOG_DIRS, oppure sotto workspace.catalog_dirs — importa invece rispetto a quelle.

Cosa chiede l’importazione

Una configurazione LangGraph non nomina alcun modello, perché lo sceglie il codice del grafo, né alcuna immagine, perché quell’immagine la costruisci tu a partire dal tuo progetto. Perciò l’importazione chiede entrambi: il nome del modello che il grafo chiama, per il modello OpenAI che abbozza, e l’immagine in cui viene eseguita l’applicazione. In un terminale li chiede e scrive le risposte nelle bozze e nel file delle risposte, import-answers.yaml, all’interno della directory che importa — qui la radice del progetto, . — così l’importazione successiva le legge da lì e non chiede nulla. Senza terminale — in integrazione continua, o attraverso una pipe — non chiede nulla: scrive il file con le chiavi vuote e si ferma:

2 values the drafts leave empty are still owed, listed in the answers file <workspace>/import-answers.yaml: write each beside its key there, then run the import again

L’esempio contiene già il file, con le risposte: il grafo chiama gpt-4o-mini di OpenAI, e ghcr.io/example/support-agent:1.0.0 sta per l’immagine che costruisci:

# Values the import could not draft from the source, keyed by the drafted file and the key path inside
# it. Write each one beside its key; an import of the same source, and a sync, read them from here and
# ask nothing. A secret is never written here: its key asks where the secret comes from — a variable
# name, ${NAME}, or the name of a Kubernetes Secret.
aggregate.yaml:
# Left for the author, since the configuration names no model: values.model, the name of the model
# core/ai-model/openai serves.
spec.components.model.values.model: "gpt-4o-mini"
release.yaml:
# Container image running the LangGraph application code. The Docker Compose Recipe runs the catalog's
# quickstart agent when it is unset.
spec.components.support.infra.image: "ghcr.io/example/support-agent:1.0.0"
# The origin of the secret value, written by the operator in the Release. Read exactly as
# values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes
# from, never the value.
spec.components.support.uses.checkpointer_db.postgres.features.credential.infra.origin: "support-db-password"
# The origin of the secret value, written by the operator in the Release. Read exactly as
# values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes
# from, never the value.
spec.components.support.uses.model.model.features.credential.infra.origin: "openai-api-key"
# The origin of the secret value, written by the operator in the Release. Read exactly as
# values.origin is. Write it here or in values.origin, never in both. A secret: name where it comes
# from, never the value.
spec.components.postgres.features.password.infra.origin: "support-db-password"

Le tre risposte origin servono per una build per Kubernetes, con --target helm: lì la password del database e la chiave OpenAI vengono lette dai Secret di Kubernetes, e ogni risposta è il nome di un Secret — la password del database da support-db-password, su entrambe le estremità, e la chiave da openai-api-key — mai la password o la chiave. Una build per Docker Compose le legge invece dalla tua shell, quindi questa importazione non usa quelle risposte. Il file delle risposte dell’importazione descrive il file, le domande e le regole per la risposta relativa a un segreto.

aggrega import elenca ogni flag accettato dal comando, tra cui --answers, che indica un file delle risposte conservato altrove.

Entra in source:

Terminal window
cd source

Eseguire l’importazione

Indica la directory dell’applicazione. L’importazione ne legge il langgraph.json e nessun altro file:

Terminal window
aggrega import . --target compose

Sullo standard output elenca ciò che ha scritto:

wrote aggregate.yaml
wrote release.yaml
wrote manifest.yaml
wrote .aggrega-import.json

Sullo standard error, dove <workspace> sta per la cartella in cui l’hai eseguita:

[… omitted: a warning that the importer runs unverified, printed where its module is read from beside its Plugin entity in a catalog folder rather than fetched]
read as the langgraph format, with drafted paths relative to <workspace>
info: the answers file <workspace>/import-answers.yaml also answers spec.components.postgres.features.password.infra.origin in release.yaml, spec.components.support.uses.checkpointer_db.postgres.features.credential.infra.origin in release.yaml, spec.components.support.uses.model.model.features.credential.infra.origin in release.yaml, which these drafts do not leave empty; those answers are kept there and not applied
mapped support (graph) to core/ai-agent/langgraph as a reference, NONE
mapped checkpointer (checkpointer) to core/datastore/postgres as a reference, NONE
mapped model (model) to core/ai-model/openai as a reference, NONE
Pull complete: <workspace>/release.lock (entities=10, source_artifacts=0, external_inputs=0)

L’importazione eseguita dall’editor: l’Aggregate, la Release e il Manifest generati compaiono accanto alla configurazione LangGraph, l’output di Aggrega elenca come sono stati mappati il grafo, il suo checkpointer e il suo modello e i file scritti, e una notifica dice che l’importazione ha generato 3 file, riconosciuti come langgraph.

  • La riga info indica le risposte che le bozze per Docker Compose non usano, conservate nel file delle risposte per una build per Kubernetes.
  • Le righe mapped dicono che il grafo è un’istanza dell’agente LangGraph della libreria standard, core/ai-agent/langgraph; che il suo checkpointer, dove LangGraph conserva lo stato di ogni grafo, è un’istanza di core/datastore/postgres, poiché la configurazione non nomina alcun checkpointer e in tal caso LangGraph conserva lo stato in PostgreSQL; e che il modello che ogni grafo chiama è un’istanza di core/ai-model/openai. Il loro livello indica NONE: l’importazione LangGraph fa riferimento a questi Components in base a ciò che la configurazione dichiara anziché confrontare ciascuno con il catalogo. Una configurazione il cui checkpointer.backend è mongo viene abbozzata con core/datastore/ferretdb, che parla il protocollo di MongoDB, sopra core/datastore/documentdb, collegati tra loro come li collega l’Aggregate FerretDB del catalogo, con un’unica password per entrambi.
  • La riga Pull complete è l’import che recupera ciò da cui dipende la Release generata in bozza, come fa aggrega pull, in release.lock, così che le bozze si validino e si compilino subito. Con --offline l’import non recupera nulla e indica il comando aggrega pull da eseguire.

Cosa scrive

L’Aggregate, la Release e il Manifest si chiamano imported/support, dall’unico grafo servito da langgraph.json, support, poiché una configurazione non porta un nome proprio — una che serve più grafi prende il nome dal suo file, o dalla sua directory quando, come qui, all’importazione viene data la directory — nel namespace definito dall’impostazione target_namespace dell’importatore, imported a meno che tu non ne imposti un altro (Impostazioni).

aggregate.yaml — il grafo, il database in cui conserva lo stato e il modello che chiama, con ogni connessione che dichiara la credenziale che presenta, e con in apertura commenti che dicono cosa è stato letto e cosa no:

# LangGraph configurations read:
# - langgraph.json
# Not read: the application's code, which defines each graph; it runs in the image the Release names for each graph.
# Not carried, since they configure the server image langgraph build builds, and the image the Release names is the application's own: dependencies, python_version.
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: imported/support
version: 0.1.0
description: Draft Aggregate imported from a source in the langgraph format.
spec:
components:
support:
type: core/ai-agent/langgraph
values:
graph_entrypoint: "./src/support_agent/graph.py:graph"
description: "Answers a question from a customer about their order, and hands it to a person when it cannot."
uses:
checkpointer_db:
postgres:
target: postgres
# For the compose target, the lines below declare credential on postgres: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
features:
credential:
type: core/secret-value
values:
key: POSTGRES_PASSWORD
model:
model:
target: model
# For the compose target, the lines below declare credential on model: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
features:
credential:
type: core/secret-value
values:
key: OPENAI_API_KEY
# The database the configuration's checkpointer keeps each graph's state in, PostgreSQL.
postgres:
type: core/datastore/postgres
features:
# For the compose target, the lines below declare password on postgres: a secret the Release alone attaches arrives under the key value, so each is declared with a key of its own and no two arrive under one; the Release attaches its origin, naming this type or none.
password:
type: core/secret-value
values:
key: POSTGRES_PASSWORD
# The model every graph calls, which the configuration does not name.
model:
type: core/ai-model/openai
values:
# Left for the author, since the configuration names no model: values.model, the name of the model core/ai-model/openai serves.
model: "gpt-4o-mini"

graph_entrypoint è il percorso di importazione del grafo così come lo scrive la configurazione. La sua connessione checkpointer_db è collegata al database e la sua connessione model al modello, il cui nome è la risposta che l’importazione ha letto da import-answers.yaml. recursion_limit non è scritto, quindi vale il valore predefinito del Component, 25. Il database riceve una password, quindi la Recipe PostgreSQL non ne scrive una propria, e il grafo presenta la stessa password sulla sua connessione al database.

release.yaml — l’ambiente, l’immagine, la porta pubblicata e la provenienza della chiave e delle password, con commenti sopra il grafo che indicano qual è la sua immagine e che cosa riceve:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: imported/support
# environment is a drafted default, since no source names the environment this Release deploys to; change it to name the one it deploys to.
environment: development
version: 0.1.0
description: Draft Release imported from a source in the langgraph format.
spec:
aggregate: imported/support
manifest: imported/support
components:
# Each graph's image is the application's own, not the server image langgraph build builds: its code, with LangGraph installed.
# It is handed, for its code to read, the graph to run as LANGGRAPH_GRAPH_ENTRYPOINT, the model's name as OPENAI_MODEL, the checkpointer store's host and port as LANGGRAPH_CHECKPOINTER_HOST and LANGGRAPH_CHECKPOINTER_PORT, its user and database, where the store publishes them, as LANGGRAPH_CHECKPOINTER_USER and LANGGRAPH_CHECKPOINTER_DATABASE, and a password attached on the checkpointer_db connection as LANGGRAPH_CHECKPOINTER_PASSWORD.
# It is also handed the model's address as OPENAI_BASE_URL and a key attached on the model connection as OPENAI_API_KEY, which the OpenAI client library reads, and recursion_limit as LANGGRAPH_DEFAULT_RECURSION_LIMIT, which LangGraph reads.
# An inject: block on the graph's own instance, through an entry reading graph_entrypoint alone, replaces LANGGRAPH_GRAPH_ENTRYPOINT with the name it writes; one on the model connection replaces OPENAI_MODEL, and one on the checkpointer_db connection the store's host, port, user and database, with the names it writes.
support:
infra:
# Left for the Release, since the source cannot supply it: infra.image, the container image running the application
image: "ghcr.io/example/support-agent:1.0.0"
# Published on this machine's loopback address, 127.0.0.1: reachable from this machine only, by any process running on it. Delete this line to keep the service internal.
published_port: 8000
uses:
checkpointer_db:
postgres:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential support presents to postgres on its checkpointer_db connection, the password of postgres (the configuration names no variable for it), read from the variable POSTGRES_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${POSTGRES_PASSWORD}"
model:
model:
features:
credential:
type: core/secret-value
infra:
# Attached by reference, never as a value: the credential support presents to model on its model connection (the source names no variable for it, so it is read from the one OpenAI's client libraries read the API key from), read from the variable OPENAI_API_KEY, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${OPENAI_API_KEY}"
postgres:
features:
password:
type: core/secret-value
infra:
# Attached by reference, never as a value: the password of postgres (the configuration names no variable for it), read from the variable POSTGRES_PASSWORD, which a target substituting variable references, as Docker Compose does when the stack starts, reads from the environment, so no file carries the value.
origin: "${POSTGRES_PASSWORD}"
model: {}

L’ambiente, development, è un valore predefinito che l’importazione scrive perché nessuna configurazione ne indica uno; cambialo dove la Release viene distribuita altrove. L’immagine è la risposta che l’importazione ha letto da import-answers.yaml. Il grafo è pubblicato sull’indirizzo di loopback della tua macchina, sulla 8000, con inoltro alla porta su cui ascolta il suo programma, infra.port, 8000 se non la imposti. La chiave e la password sono riferimenti a variabili, ${OPENAI_API_KEY} e ${POSTGRES_PASSWORD}, mai valori.

manifest.yaml — la Recipe Compose di ciascun tipo e la realizzazione che scrive ogni riferimento a variabile nel file Compose così com’è scritto:

apiVersion: aggrega.ai/v1beta1
kind: Manifest
metadata:
name: imported/support
version: 0.1.0
spec:
mappings:
components:
type:
core/ai-agent/langgraph: compose/langgraph
core/datastore/postgres: compose/postgres
core/ai-model/openai: compose/openai
features:
type:
core/secret-value: compose/dotenv-secret

release.lock registra, per digest, le entità del catalogo in cui la Release si è risolta, e .aggrega-import.json è il registro di ciò che l’importazione ha scritto, che un successivo aggrega import --sync legge.

Convalidare e compilare

Terminal window
aggrega validate --release release.yaml
aggrega build --release release.yaml

La Release generata aperta nell’editor dopo la validazione, con l’output di Aggrega e una notifica che segnalano entrambi che non sono stati trovati problemi.

La build della Release generata: una cartella dist compare in Esplora risorse, l’output di Aggrega elenca il file Docker Compose scritto, e una notifica dice che è stato scritto 1 file.

La convalida stampa:

notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
release dependency validation passed: release.yaml (schema-pillar + dependency pillars)

e la build, dove <workspace> indica la cartella in cui l’hai eseguita:

notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)
[… omitted: a total build time, which differs per run]
Build completed: 1 file written to <workspace>/dist

La riga notice è informativa: la Feature del segreto accetta il suo origin dai values dell’Aggregate o dall’infra della Release, e l’avviso segnala che una foglia è dichiarata in entrambi. Non cambia alcun verdetto.

La build scrive dist/compose/docker-compose.yaml, con un servizio per il grafo, uno per il database e uno che attende il database. Il servizio del grafo:

support:
image: ghcr.io/example/support-agent:1.0.0
environment:
LANGGRAPH_DEFAULT_RECURSION_LIMIT: "25"
OPENAI_BASE_URL: https://api.openai.com/v1
OPENAI_MODEL: gpt-4o-mini
LANGGRAPH_CHECKPOINTER_HOST: postgres
LANGGRAPH_CHECKPOINTER_PORT: "5432"
LANGGRAPH_CHECKPOINTER_USER: appuser
LANGGRAPH_CHECKPOINTER_DATABASE: appdb
LANGGRAPH_GRAPH_ENTRYPOINT: ./src/support_agent/graph.py:graph
OPENAI_API_KEY: ${OPENAI_API_KEY}
LANGGRAPH_CHECKPOINTER_PASSWORD: ${POSTGRES_PASSWORD}
ports:
- 127.0.0.1:8000:8000
[… omitted: the labels the build writes on every service, naming the Aggregate, the component, the environment and the compiler's version]
networks:
- compose
depends_on:
support--wait-for-store:
condition: service_completed_successfully
postgres:
condition: service_started

Il grafo riceve l’indirizzo del modello, il suo nome e la sua chiave, l’host, la porta, l’utente, il nome e la password del database, e il proprio punto di ingresso del grafo. L’utente e il nome del database sono i valori predefiniti del Component PostgreSQL, appuser e appdb, con cui viene creato il servizio del database riportato più sotto; il grafo li riceve perché la Recipe PostgreSQL li pubblica entrambi, e con uno store che non pubblica né l’uno né l’altro, come Valkey, non riceve né l’uno né l’altro. Il nome del modello, l’host, la porta, l’utente e il nome del database e il punto di ingresso del grafo arrivano con i nomi che il Component LangGraph fornisce per impostazione predefinita, che un blocco inject: sulla connessione, o sul componente stesso per i suoi valori, sostituisce con i nomi che il tuo codice legge. L’indirizzo del modello, la sua chiave e la password del database mantengono i nomi riportati nei blocchi, e così anche LANGGRAPH_DEFAULT_RECURSION_LIMIT, che LangGraph legge da sé come limite di passi di un’esecuzione la cui configurazione non ne imposta alcuno. Il servizio proprio del database riceve la stessa password:

postgres:
image: postgres:16
environment:
POSTGRES_USER: appuser
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
POSTGRES_DB: appdb
[… omitted: the labels the build writes on every service, the network, and a health check running PostgreSQL's pg_isready]

Il servizio del grafo si avvia solo dopo che il terzo servizio è stato completato. Quest’ultimo viene eseguito una sola volta, nell’immagine dell’agente quickstart del catalogo anziché in quella del grafo, e attende che l’indirizzo del database accetti una connessione TCP, riprovando ogni 2 s per un massimo di 300 s; se entro quel termine non ottiene alcuna connessione, termina indicando l’indirizzo, e il grafo non viene avviato. Riceve l’host e la porta del database e nient’altro:

support--wait-for-store:
image: hub.aggrega.ai/tools/quickstart-agent:1.0.1@sha256:a5f8dcfbb670d86a0cae0aadd2844bec93221a651238f8be3863873e261ee168
[… omitted: the command and the entrypoint, a bash loop that opens a connection to the address]
environment:
STORE_HOST: postgres
STORE_PORT: "5432"
[… omitted: the labels the build writes on every service, and the network]
restart: "no"

La chiave e la password sono riferimenti a variabili, valorizzati dalla tua shell all’avvio dello stack. Il modello non ha un servizio proprio: il grafo raggiunge l’API di OpenAI all’indirizzo di quest’ultima. Il servizio del grafo pubblica la sua porta solo su 127.0.0.1, e la porta propria del database è raggiungibile sulla rete dello stack, senza nulla di pubblicato.

Con un assistente AI

Un assistente AI configurato con gli strumenti di Aggrega può fare lo stesso: incollaci questo prompt.

Usa solo gli strumenti di Aggrega e non creare tu alcuna cartella. Se la cartella del Workspace non contiene ancora una cartella `import-langgraph`, chiama una volta lo strumento `scaffold` con `example` impostato a `import-langgraph` e nessun `dir`: scrive l’esempio in una nuova cartella `import-langgraph`, la cui cartella `source` contiene ciò che questa pagina importa. Poi chiama lo strumento `import` con `workspace_root` impostato a `import-langgraph/source`, `source` impostato a `.` e `target` impostato a `compose`: legge le risposte di cui ha bisogno da `import-answers.yaml` accanto a `langgraph.json`, scrive le sue bozze in `import-langgraph/source` e scarica ciò di cui hanno bisogno. Poi chiama lo strumento `validate` con `workspace_root` impostato a `import-langgraph/source` e `release` impostato a `release.yaml`, e lo strumento `build` con `workspace_root` impostato a `import-langgraph/source`, `release` impostato a `release.yaml` e `write` impostato a true. Dimmi quali file ha scritto la build; si trovano in `import-langgraph/source/dist/`.

Aprilo in VS Code

Con l’estensione Aggrega per Visual Studio Code installata, apri in VS Code la cartella import-langgraph/source, dove l’importazione ha scritto le sue bozze. La cartella contiene una sola Release, il release.yaml generato, quindi l’editor la seleziona per te e controlla le bozze rispetto a quella Release mentre le modifichi, segnalando ciò che trova nel file e nel pannello Problemi. Aggrega: Show topology graph, nel riquadro comandi, disegna i componenti della Release e le connessioni tra di essi. Aggrega: Build, Aggrega: Preview build e Aggrega: Pull agiscono sulla stessa Release, e ciascuno è anche un pulsante nel pannello Commands della vista Aggrega nella barra delle attività; Build scrive i propri file in dist/ della cartella. Usare Aggrega in Visual Studio Code copre il resto.

Esecuzione

Costruisci l’immagine a partire dal progetto, con un Dockerfile tuo: il codice del grafo, con LangGraph installato. Docker Compose esegue il comando proprio dell’immagine come servizio del grafo, poiché la Recipe non ne imposta alcuno, quindi quel comando deve restare in esecuzione e deve servire le richieste se vuoi raggiungere il grafo. Trova il grafo, il modello e il database tramite le variabili riportate sopra. È il tuo programma a decidere l’indirizzo, la route e la risposta.

L’esecuzione riportata di seguito ha usato un’immagine di questo tipo: il grafo nel percorso indicato da langgraph.json, src/support_agent/graph.py, un nodo che risponde tramite il modello indicato da OPENAI_MODEL e, come comando dell’immagine, un piccolo server HTTP proprio del programma sulla porta 8000. L’immagine mantiene la struttura del progetto nella sua directory di lavoro, quindi il percorso indicato da LANGGRAPH_GRAPH_ENTRYPOINT, relativo a essa, trova il grafo. Il server carica quel grafo, conserva lo stato di ogni conversazione nel database tramite il checkpointer PostgreSQL di LangGraph, aperto con host, porta, utente, nome e password del database, ciascuno letto dalla variabile LANGGRAPH_CHECKPOINTER_ con cui arriva, così che il programma non ne scrive nessuno da sé, ed esegue il grafo una volta per ogni POST /threads/<thread>/runs. Il servizio del grafo si avvia non appena il database accetta connessioni, quindi un server che apre il checkpointer al proprio avvio trova il database già pronto ad accettare connessioni. Costruisci la tua immagine nella radice del progetto, scrivi il suo nome al posto di ghcr.io/example/support-agent:1.0.0 in import-answers.yaml e importa di nuovo con --sync, che scrive la nuova risposta nelle bozze ed esegue di nuovo il pull; poi esegui la build:

Terminal window
docker build -t order-support:local .
aggrega import . --sync
aggrega build --release release.yaml

Poi imposta la chiave e la password del database nella tua shell e avvia lo stack:

Terminal window
export OPENAI_API_KEY='your OpenAI key'
export POSTGRES_PASSWORD='a password of your own'
docker compose -p order-support -f dist/compose/docker-compose.yaml up -d --wait

-p assegna il nome al progetto, come spiega il passo di esecuzione di Come si svolge un’importazione. --wait ritorna quando il database risulta integro, l’attesa del database è terminata e il servizio del grafo è in esecuzione.

Eseguire il test

La richiesta qui sotto raggiunge il programma eseguito dall’immagine di questa procedura guidata: il grafo dietro un piccolo server HTTP sulla porta 8000, che risponde a POST /threads/<thread>/runs. Il tuo programma decide la propria route e la propria risposta. Inviala a http://127.0.0.1:8000, l’indirizzo che published_port pubblica:

Terminal window
curl -sS -X POST http://127.0.0.1:8000/threads/order-1234/runs -H 'Content-Type: application/json' \
-d '{"message": "Where is my order 1234? It has not arrived yet."}'
{
"thread": "order-1234",
"error": "the run failed: OpenAIAuthenticationError: Error code: 401 - Incorrect API key provided: sk-place************-key. [… omitted: where to find an API key]"
}

L’esecuzione ha impostato OPENAI_API_KEY su un segnaposto, quindi la risposta è il rifiuto di OpenAI, inoltrato dal programma. La richiesta del grafo ha raggiunto l’API di OpenAI con la chiave fornita dalla build, da un programma che aveva aperto il proprio checkpointer nel database con le credenziali fornite dalla build.

Arresta lo stack con:

Terminal window
docker compose -p order-support -f dist/compose/docker-compose.yaml down -v

-v rimuove il volume in cui il database conserva i propri dati, e con esso le conversazioni.

Su Kubernetes, esegui l’importazione con --target helm e invia l’immagine a un registry da cui il tuo cluster esegue il pull, indicandola in import-answers.yaml. Poi crea i Secret openai-api-key e support-db-password e applica la build, come descrive il passo di esecuzione di Come si svolge un’importazione. Il Deployment del grafo non ha alcun Service. Il suo pod si riavvia finché il database non accetta connessioni, perché il programma apre il proprio checkpointer all’avvio. Inoltra una porta locale verso di esso; il comando resta in esecuzione finché non lo interrompi:

Terminal window
kubectl port-forward deploy/support 8000:8000
Forwarding from 127.0.0.1:8000 -> 8000
Forwarding from [::1]:8000 -> 8000

Da un altro terminale, invia la stessa richiesta alla porta inoltrata:

Terminal window
curl -sS -X POST http://127.0.0.1:8000/threads/order-1234/runs -H 'Content-Type: application/json' \
-d '{"message": "Where is my order 1234? It has not arrived yet."}'
{
"thread": "order-1234",
"error": "the run failed: OpenAIAuthenticationError: Error code: 401 - Incorrect API key provided: sk-place************-key. [… omitted: where to find an API key]"
}