콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

LangGraph 애플리케이션 가져오기

이 단계별 안내에서는 주문에 관한 고객의 질문에 답하는 그래프 하나로 이루어진 LangGraph 애플리케이션의 구성을 가져오고, Docker Compose용으로 애플리케이션을 빌드합니다. 가져오기는 빌드가 읽는 모든 파일의 초안을 작성합니다. 그래프, 그 체크포인터가 상태를 보관하는 PostgreSQL 데이터베이스, 그래프가 호출하는 모델, 변수 참조로 표현한 비밀번호와 키, 그리고 각각의 실현입니다. 어떤 구성에도 없는 두 값, 즉 그래프 코드가 호출하는 모델과 애플리케이션이 실행되는 이미지는 한 번만 묻습니다. 아래의 모든 파일과 출력 블록은 실제 실행에서 나온 것입니다. 구성과 단계별 안내의 각 단계는 import-langgraph 예제에 있으며, 그곳의 검사 스크립트가 가져오기를 다시 실행하여 작성한 내용, 출력한 내용, 이 페이지가 인용하는 블록을 그곳에 보관된 파일과 비교하고, 가져오기가 작성한 내용을 검증하고 빌드합니다.

예제 생성하기

이 페이지의 명령으로 이 가져오기를 실행하거나, AI 어시스턴트가 대신 실행하게 할 수 있습니다.

예제 이름을 딴 새 폴더에 예제를 씁니다:

Terminal window
aggrega scaffold --example import-langgraph

그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다. 그 뒤의 명령은 아래와 같으며, 새 폴더 안의 source 폴더로 이동합니다. 이 폴더에는 이 페이지가 가져오는 내용이 들어 있으며, 가져오기는 여기서 실행됩니다:

Terminal window
cd import-langgraph

Visual Studio Code에서 연 스캐폴드된 예제의 source 폴더로, 그래프 하나인 support를 지정하는 LangGraph 구성을 보여 줍니다.

프로젝트

LangGraph 애플리케이션은 그래프를 코드에 두고 langgraph.json에 선언합니다. 이 파일은 LangGraph 명령줄 도구의 구성 파일입니다. 이 단계별 안내를 위해 작성된 이 애플리케이션은 애플리케이션 코드 안에서의 그래프 임포트 경로와 설명으로 그래프 하나, support를 선언합니다:

{
"$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."
}
}
}

가져오기는 langgraph.json을 읽고 애플리케이션의 코드는 절대 읽지 않으므로, 예제에는 구성만 들어 있습니다. 그 옆의 .aggrega-config.yaml이 폴더를 워크스페이스로 만듭니다:

# 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

가져오기는 카탈로그의 LangGraph 에이전트, PostgreSQL 및 OpenAI 모델 Components를 참조하고, --target은 카탈로그의 Recipes로부터 Manifest를 초안으로 작성합니다. 작업 공간이 카탈로그 폴더를 지정하지 않으므로, 가져오기는 임포터를 받아 오는 레지스트리에서 표준 라이브러리 카탈로그를 읽습니다. 이는 게시된 카탈로그의 서명된 스냅샷으로, 첫 번째 가져오기가 받아 와서 검증한 뒤 작업 공간의 콘텐츠 캐시에 보관하며, 가져오기가 초안 옆에 작성하는 기록에 그 다이제스트로 지정됩니다. AGGREGA_CATALOG_DIRS에서 또는 workspace.catalog_dirs 아래에서 자체 카탈로그 폴더를 지정하는 작업 공간은 대신 그 폴더들을 기준으로 가져옵니다.

가져오기가 묻는 항목

LangGraph 구성은 모델을 지정하지 않습니다. 모델은 그래프의 코드가 선택하기 때문입니다. 이미지도 지정하지 않습니다. 그 이미지는 프로젝트로부터 직접 빌드하기 때문입니다. 따라서 가져오기는 둘 다 묻습니다. 즉, 초안으로 작성하는 OpenAI 모델을 위해 그래프가 호출하는 모델의 이름과, 애플리케이션이 실행되는 이미지입니다. 터미널에서는 질문을 하고, 답변을 초안과 가져오는 디렉터리(여기서는 프로젝트의 루트인 .) 안의 답변 파일 import-answers.yaml에 기록하므로, 다음 가져오기는 거기서 답변을 읽고 아무것도 묻지 않습니다. 터미널이 없으면(지속적 통합에서, 또는 파이프를 통해 실행하면) 아무것도 묻지 않습니다. 키가 비어 있는 파일을 작성하고 중지합니다:

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

예제에는 답변이 채워진 파일이 이미 들어 있습니다. 그래프는 OpenAI의 gpt-4o-mini를 호출하고, ghcr.io/example/support-agent:1.0.0은 빌드하는 이미지를 나타냅니다:

# 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"

세 개의 origin 답변은 --target helm을 사용한 Kubernetes용 빌드를 위한 것입니다. 이 경우 데이터베이스의 비밀번호와 OpenAI 키는 Kubernetes Secret에서 읽으며, 각 답변은 Secret의 이름입니다. 데이터베이스의 비밀번호는 양쪽 모두 support-db-password에서, 키는 openai-api-key에서 읽으며, 비밀번호나 키 자체는 결코 답변이 되지 않습니다. Docker Compose용 빌드는 대신 셸에서 이를 읽으므로, 이 가져오기는 그 답변들을 사용하지 않습니다. 가져오기 답변 파일은 파일, 질문, 그리고 시크릿 답변에 대한 규칙을 설명합니다.

aggrega import에는 다른 곳에 보관된 응답 파일을 지정하는 --answers를 비롯하여 이 명령이 받는 모든 플래그가 나열되어 있습니다.

source로 이동합니다:

Terminal window
cd source

가져오기 실행

애플리케이션의 디렉터리를 지정합니다. 가져오기는 그 안의 langgraph.json만 읽고 다른 파일은 읽지 않습니다:

Terminal window
aggrega import . --target compose

표준 출력에는 작성한 것을 나열합니다:

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

표준 오류에는 다음과 같이 출력합니다. 여기서 <workspace>는 명령을 실행한 폴더를 나타냅니다:

[… 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)

편집기에서 실행한 가져오기: 초안으로 작성된 Aggregate, Release, Manifest가 LangGraph 구성 옆에 나타나고, Aggrega 출력에는 그래프, 체크포인터, 모델이 어떻게 매핑되었는지와 작성된 파일이 나열되며, 알림은 가져오기가 langgraph로 인식되어 3개의 파일을 초안으로 작성했음을 알려 줍니다.

  • info 줄은 Docker Compose 초안이 사용하지 않고 Kubernetes용 빌드를 위해 답변 파일에 보관된 답변을 알려 줍니다.
  • mapped 줄은 그래프가 표준 라이브러리의 LangGraph 에이전트 core/ai-agent/langgraph의 인스턴스이고, LangGraph가 각 그래프의 상태를 보관하는 곳인 체크포인터가 core/datastore/postgres의 인스턴스이며(구성이 체크포인터를 지정하지 않으면 LangGraph는 상태를 PostgreSQL에 보관하기 때문입니다), 모든 그래프가 호출하는 모델이 core/ai-model/openai의 인스턴스임을 나타냅니다. 이들의 티어는 NONE으로 표시됩니다. LangGraph 가져오기는 각각을 카탈로그와 비교해 평가하는 대신 구성이 선언하는 내용에 따라 이 Components를 참조하기 때문입니다. checkpointer.backend가 mongo인 구성은 MongoDB의 프로토콜을 사용하는 core/datastore/ferretdb를 core/datastore/documentdb 위에 두는 형태로 초안이 작성되며, 두 항목은 카탈로그의 FerretDB Aggregate가 연결하는 방식대로 연결되고 둘 다 하나의 비밀번호를 사용합니다.
  • Pull complete 줄은 가져오기가 초안으로 작성된 Release가 의존하는 것을 aggrega pull처럼 release.lock으로 가져오는 것으로, 초안을 즉시 검증하고 빌드할 수 있게 합니다. --offline에서는 가져오기가 아무것도 가져오지 않고 실행할 aggrega pull을 알려 줍니다.

작성하는 내용

Aggregate, Release, Manifest의 이름은 imported/support입니다. 구성 파일에는 자체 이름이 없으므로 langgraph.json이 제공하는 단 하나의 그래프 support를 따릅니다. 여러 그래프를 제공하는 구성 파일은 파일 이름을 따르거나, 여기처럼 가져오기에 디렉터리를 넘긴 경우에는 디렉터리 이름을 따릅니다. 네임스페이스는 임포터의 target_namespace 설정이 정하며, 다른 값을 설정하지 않으면 imported입니다(설정).

aggregate.yaml — 그래프, 그 상태를 보관하는 데이터베이스, 그리고 그래프가 호출하는 모델이며, 각 연결은 자신이 제시하는 자격 증명을 선언하고, 무엇을 읽었고 무엇을 읽지 않았는지 알려 주는 주석으로 시작합니다:

# 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는 구성에 적힌 그대로의 그래프 임포트 경로입니다. 그 checkpointer_db 연결은 데이터베이스에, model 연결은 모델에 배선되며, 모델의 이름은 가져오기가 import-answers.yaml에서 읽은 답변입니다. recursion_limit은 작성되지 않았으므로 Component의 기본값인 25가 유지됩니다. 데이터베이스는 비밀번호를 받으므로 PostgreSQL Recipe는 자체 비밀번호를 작성하지 않으며, 그래프는 데이터베이스에 대한 연결에서 같은 비밀번호를 제시합니다.

release.yaml — 환경, 이미지, 게시된 포트, 그리고 키와 비밀번호의 출처이며, 그래프 위의 주석은 그 이미지가 무엇이고 무엇을 전달받는지 설명합니다:

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: {}

환경 development는 어떤 구성도 환경을 지정하지 않기 때문에 가져오기가 작성하는 기본값입니다. Release를 다른 곳에 배포하는 경우 변경하십시오. 이미지는 가져오기가 import-answers.yaml에서 읽은 답변입니다. 그래프는 머신의 루프백 주소의 8000에 게시되며, 그 프로그램이 수신 대기하는 포트인 infra.port로 전달됩니다. 이 포트는 설정하지 않으면 8000입니다. 키와 비밀번호는 변수 참조인 ${OPENAI_API_KEY}와 ${POSTGRES_PASSWORD}이며, 결코 값이 아닙니다.

manifest.yaml — 각 유형의 Compose Recipe와, 각 변수 참조를 작성된 그대로 Compose 파일에 기록하는 실현입니다:

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은 Release가 해석된 카탈로그 엔터티를 다이제스트로 기록하며, .aggrega-import.json은 가져오기가 작성한 내용의 기록으로, 이후의 aggrega import --sync가 이를 읽습니다.

검증 및 빌드

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

검증 후 편집기에서 연 초안 Release로, Aggrega 출력과 알림이 모두 발견된 문제가 없다고 보고합니다.

초안 Release의 빌드: 탐색기에 dist 폴더가 나타나고, Aggrega 출력에는 작성된 Docker Compose 파일이 나열되며, 알림은 1개의 파일이 작성되었음을 알려 줍니다.

검증 결과는 다음과 같습니다:

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)

그리고 빌드는 다음과 같습니다. 여기서 <workspace>는 실행한 폴더를 나타냅니다:

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

notice 줄은 권고 사항입니다. 시크릿 Feature는 origin을 Aggregate의 values 또는 Release의 infra에서 받으며, 이 알림은 한 리프가 양쪽에 모두 선언되어 있음을 보고합니다. 어떤 판정도 바꾸지 않습니다.

빌드는 그래프용 서비스 하나, 데이터베이스용 서비스 하나, 그리고 데이터베이스를 기다리는 서비스 하나를 포함한 dist/compose/docker-compose.yaml을 작성합니다. 그래프의 서비스는 다음과 같습니다:

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

그래프는 모델의 주소, 이름, 키와 데이터베이스의 호스트, 포트, 사용자, 데이터베이스 이름, 비밀번호, 그리고 자체 그래프 진입점을 받습니다. 사용자와 데이터베이스 이름은 PostgreSQL Component의 기본값인 appuser와 appdb이며, 아래의 데이터베이스 서비스도 이 값으로 생성됩니다. 그래프가 이를 받는 것은 PostgreSQL Recipe가 둘 다 게시하기 때문이며, Valkey처럼 둘 다 게시하지 않는 저장소라면 그래프는 둘 다 받지 않습니다. 모델의 이름, 데이터베이스의 호스트, 포트, 사용자, 데이터베이스 이름, 그래프 진입점은 LangGraph Component가 기본으로 전달하는 이름으로 도착하며, 연결에 두거나 자체 값에 대해서는 컴포넌트 자체에 두는 inject: 블록이 이를 코드가 읽는 이름으로 바꿉니다. 모델의 주소, 키, 데이터베이스의 비밀번호는 블록에 적힌 이름 그대로 유지되며, LANGGRAPH_DEFAULT_RECURSION_LIMIT도 마찬가지입니다. LangGraph는 구성에서 단계 한도를 설정하지 않은 실행의 단계 한도로 이 변수를 스스로 읽습니다. 데이터베이스 자체의 서비스도 같은 비밀번호를 받습니다:

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]

그래프의 서비스는 세 번째 서비스가 완료된 뒤에야 시작됩니다. 세 번째 서비스는 그래프 자체의 이미지가 아니라 카탈로그의 quickstart 에이전트 이미지에서 한 번만 실행되며, 데이터베이스의 주소가 TCP 연결을 받아들일 때까지 2초마다 최대 300초 동안 시도하며 기다립니다. 그때까지 연결되지 않으면 주소를 알리며 종료하고, 그래프는 시작되지 않습니다. 이 서비스는 데이터베이스의 호스트와 포트만 전달받으며, 그 밖에는 아무것도 받지 않습니다:

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"

키와 비밀번호는 변수 참조이며, 스택이 시작될 때 셸에서 채워집니다. 모델에는 자체 서비스가 없습니다. 그래프는 OpenAI API 자체의 주소로 API에 도달합니다. 그래프의 서비스는 127.0.0.1에서만 포트를 게시하며, 데이터베이스 자체의 포트는 아무것도 게시하지 않은 채 스택의 네트워크에서 접근합니다.

AI 어시스턴트 사용

Aggrega의 도구로 설정된 AI 어시스턴트도 같은 일을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.

Aggrega 도구만 사용하고, 폴더를 직접 만들지 마세요. Workspace 폴더에 아직 `import-langgraph` 폴더가 없으면, `example`을 `import-langgraph`로 설정하고 `dir`은 지정하지 않은 채 `scaffold` 도구를 한 번 호출하세요. 이 도구는 예제를 새 `import-langgraph` 폴더에 작성하며, 그 `source` 폴더에 이 페이지에서 가져오는 내용이 들어 있습니다. 그런 다음 `workspace_root`를 `import-langgraph/source`로, `source`를 `.`로, `target`을 `compose`로 설정하여 `import` 도구를 호출하세요. 이 도구는 필요한 답변을 `langgraph.json` 옆의 `import-answers.yaml`에서 읽고, 초안을 `import-langgraph/source`에 작성하며, 초안에 필요한 것을 가져옵니다. 그런 다음 `workspace_root`를 `import-langgraph/source`로, `release`를 `release.yaml`로 설정하여 `validate` 도구를 호출하고, `workspace_root`를 `import-langgraph/source`로, `release`를 `release.yaml`로, `write`를 true로 설정하여 `build` 도구를 호출하세요. 빌드가 어떤 파일을 작성했는지 알려 주세요. 파일은 `import-langgraph/source/dist/` 아래에 있습니다.

VS Code에서 열기

Visual Studio Code용 Aggrega 확장을 설치한 상태에서, 가져오기가 초안을 작성한 폴더 import-langgraph/source를 VS Code에서 엽니다. 이 폴더에는 Release가 하나, 즉 초안으로 작성된 release.yaml만 있으므로 편집기가 이를 자동으로 선택하고, 초안을 편집하는 동안 그 Release를 기준으로 검사하여 발견한 내용을 파일과 문제 패널에 표시합니다. 명령 팔레트의 Aggrega: Show topology graph는 Release의 컴포넌트와 그 사이의 연결을 그립니다. Aggrega: Build, Aggrega: Preview build, Aggrega: Pull은 같은 Release에 대해 동작하며, 각각 작업 표시줄의 Aggrega 보기에 있는 Commands 패널의 버튼으로도 제공됩니다. Build는 폴더의 dist/에 파일을 작성합니다. 나머지 내용은 Visual Studio Code에서 Aggrega 사용하기에서 다룹니다.

실행하기

이미지는 직접 작성한 Dockerfile로 프로젝트에서 빌드합니다. 그래프의 코드에 LangGraph가 설치된 이미지입니다. Recipe가 명령을 설정하지 않으므로 Docker Compose는 이미지 자체의 명령을 그래프의 서비스로 실행합니다. 따라서 그 명령은 계속 실행되어야 하며, 그래프에 접근하려면 요청을 처리해야 합니다. 명령은 위의 변수를 통해 그래프, 모델, 데이터베이스를 찾습니다. 주소, 경로, 응답은 사용자의 프로그램이 결정합니다.

아래 실행에서는 이러한 이미지를 사용했습니다. langgraph.json이 지정하는 경로 src/support_agent/graph.py에 있는 그래프, OPENAI_MODEL이 지정하는 모델을 통해 응답하는 노드 하나, 그리고 이미지의 명령으로서 포트 8000에서 동작하는 프로그램 자체의 작은 HTTP 서버입니다. 이미지는 작업 디렉터리에 프로젝트의 구조를 그대로 유지하므로, LANGGRAPH_GRAPH_ENTRYPOINT가 지정하는, 그 디렉터리 기준의 상대 경로로 그래프를 찾습니다. 서버는 그 그래프를 로드하고, LangGraph의 PostgreSQL 체크포인터를 통해 각 대화의 상태를 데이터베이스에 보관하며, POST /threads/<thread>/runs마다 그래프를 한 번 실행합니다. 체크포인터는 데이터베이스의 호스트, 포트, 사용자, 데이터베이스 이름, 비밀번호로 열리며, 각 값은 그 값이 도착하는 LANGGRAPH_CHECKPOINTER_ 변수에서 읽으므로 프로그램은 그중 어느 것도 직접 적지 않습니다. 그래프의 서비스는 데이터베이스가 연결을 받아들이게 되면 시작되므로, 시작할 때 체크포인터를 여는 서버는 연결을 받아들이고 있는 데이터베이스를 만나게 됩니다. 프로젝트 루트에서 이미지를 빌드하고, import-answers.yaml에서 ghcr.io/example/support-agent:1.0.0 자리에 그 이름을 적은 다음, --sync로 다시 가져오십시오. 이 명령은 새 답변을 초안에 기록하고 다시 풀합니다. 그런 다음 빌드합니다:

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

그런 다음 셸에서 키와 데이터베이스 비밀번호를 설정하고 스택을 시작합니다:

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는 가져오기 실행 방식의 실행 단계에서 설명하듯이 프로젝트 이름을 지정합니다. --wait는 데이터베이스가 정상 상태를 보고하고, 데이터베이스 대기가 완료되고, 그래프의 서비스가 실행되면 반환됩니다.

테스트하기

아래 요청은 이 안내의 이미지가 실행하는 프로그램에 도달합니다. 그 프로그램은 포트 8000의 작은 HTTP 서버 뒤에 있는 그래프로, POST /threads/<thread>/runs에 응답합니다. 직접 만든 프로그램은 자체 경로와 응답을 스스로 정합니다. published_port가 게시하는 주소인 http://127.0.0.1:8000으로 보냅니다:

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]"
}

실행에서는 OPENAI_API_KEY를 자리 표시자로 설정했으므로, 응답은 그 키에 대한 OpenAI의 거부이며 프로그램이 이를 전달합니다. 그래프의 요청은 빌드가 전달한 키로 OpenAI API에 도달했으며, 요청을 보낸 프로그램은 빌드가 전달한 자격 증명으로 데이터베이스에 체크포인터를 열어 둔 상태였습니다.

다음 명령으로 스택을 중지합니다:

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

-v는 데이터베이스가 데이터를 보관하는 볼륨을 제거하며, 대화도 함께 제거합니다.

Kubernetes에서는 --target helm으로 가져오고, 클러스터가 풀하는 레지스트리에 이미지를 푸시한 뒤 import-answers.yaml에 그 이름을 적습니다. 그런 다음 Secret openai-api-key와 support-db-password를 만들고, 가져오기 실행 방식의 실행 단계에서 설명하는 대로 빌드를 적용합니다. 그래프의 Deployment에는 Service가 없습니다. 프로그램이 시작할 때 체크포인터를 열기 때문에, 그 pod는 데이터베이스가 연결을 받을 때까지 재시작합니다. 로컬 포트를 그곳으로 포워딩합니다. 명령은 중지할 때까지 실행됩니다:

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

다른 터미널에서 포워딩된 포트로 같은 요청을 보냅니다.

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]"
}