Cloud Run에 LangChain 에이전트 배포

1. 개요

에이전트 는 AI 모델과 소통하면서 보유한 도구와 컨텍스트를 사용해 목표 기반 작업을 수행하고 사실에 기반한 자율적 의사 결정을 내릴 수 있는 자율 프로그램입니다.

에이전트 개발 키트(ADK), LangChain, smolagents와 같은 에이전트 프레임워크는 에이전트를 만드는 데 사용됩니다. 이러한 프레임워크를 통해 생성된 에이전트 애플리케이션은 Cloud Run에 배포할 수 있으며 서버리스 애플리케이션으로 사용자에게 제공할 수 있습니다.

이 Codelab에서는 LangChain을 사용하여 에이전트를 빌드하고 Cloud Run에 배포합니다.

빌드할 항목

프로토타입 프롬프트에서 에이전트 빌드로 이동할 준비가 되셨나요? LangChain을 사용하여 구조화된 형식으로 역사적 인물에 관한 정보를 가져오는 에이전트를 만듭니다. 이 실습에서는 다음 작업을 수행합니다.

1. LangChain을 사용하여 구조화된 형식으로 역사적 인물에 관한 정보를 생성하는 간단한 에이전트 빌드
2. 에이전트를 로컬로 실행하고 예상대로 작동하는지 확인
3. 에이전트를 Cloud Run에 배포하고 Cloud Run URL을 사용하여 호출

요구사항

• 브라우저( Chrome 또는 Firefox 등)
• 결제가 사용 설정된 Google Cloud 프로젝트.

2. 시작하기 전에

프로젝트 만들기

1. Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트를 선택하거나 만듭니다.
2. Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다. 프로젝트에 결제가 사용 설정되어 있는지 확인하는 방법을 알아보세요.
3. 이 링크를 클릭하여 Cloud Shell을 활성화합니다. Cloud Shell에서 해당하는 버튼을 클릭하여 Cloud Shell 터미널 (클라우드 명령어 실행)과 편집기 (프로젝트 빌드) 간에 전환할 수 있습니다.
4. Cloud Shell에 연결되면 다음 명령어를 사용하여 이미 인증되었고 프로젝트가 프로젝트 ID로 설정되어 있는지 확인합니다.

gcloud auth list

5. Cloud Shell에서 다음 명령어를 실행하여 gcloud 명령어가 프로젝트를 알고 있는지 확인합니다.

gcloud config list project

6. 프로젝트가 설정되지 않은 경우 다음 명령어를 사용하여 설정합니다.

gcloud config set project <YOUR_PROJECT_ID>

7. Python 3.13 이상이 설치되어 있는지 확인합니다.

다른 gcloud 명령어 및 사용법은 문서를 참조하세요.

3. LangChain 에이전트 만들기

프로젝트 구조

Cloud Shell에서 langchain-app이라는 폴더를 만들고 그 안에 다음 파일을 추가합니다.

langchain-gemini-fastapi-app/
├── main.py
├── requirements.txt

애플리케이션 코드

requirements.txt에 추가해야 하는 종속 항목은 다음과 같습니다.

fastapi
uvicorn
langchain
langchain-google-genai
python-dotenv

main.py에서는 Gemini 모델을 사용하고 역사적 인물에 관한 정보를 가져오는 에이전트 코드를 작성합니다. 가져온 후에는 지시에 따라 구조화된 형식으로 형식을 지정합니다.

이 구현에서는 최신 LCEL (LangChain Expression Language) 구문을 사용합니다.

import os
import uvicorn
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from langchain_google_genai import ChatGoogleGenerativeAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import JsonOutputParser

# Initialize FastAPI
app = FastAPI(title="LangChain App for Historical Figures")

# 1. Setup Gemini Model
# We expect GOOGLE_API_KEY to be set in the environment variables
llm = ChatGoogleGenerativeAI(
    model="gemini-2.5-flash",
    temperature=0.7
)

# 2. Define the Prompt
prompt = ChatPromptTemplate.from_template("You are an expert Historian. For the historical personality {name}, you are able to accurately tell their birth date and birth country. Return the output in the JSON format containing name, birthDate, birthCountry. In case you are unable to retrieve birthDate or birthCountry, just have the unknown values as null. ensure the response is a valid json object only.")
output_parser = JsonOutputParser()

# Chain: Prompt -> Model -> Json Output Parser
chain = prompt | llm | output_parser

# 3. Define Request Model
class QueryRequest(BaseModel):
    name: str

# 4. Define Endpoint
@app.post("/chat")
async def chat(request: QueryRequest):
    try:
        response = await chain.ainvoke({"name": request.name})
        return response
    except Exception as e:
        raise HTTPException(status_code=500, detail=str(e))

@app.get("/")
def health_check():
    return {"status": "ok", "service": "LangChain-Gemini-FastAPI"}

4. 에이전트 테스트

배포하기 전에 로컬로 테스트할 수 있습니다.

1. AI Studio에서 Gemini API 키를 만듭니다.
2. Gemini API 키를 다음과 같이 내보냅니다.

export GOOGLE_API_KEY="AIzaSy..."

3. 서버를 실행합니다.

uvicorn main:app --port 8080 --host 0.0.0.0

4. 다음 curl 명령어를 사용하여 에이전트를 테스트합니다.

curl -X POST http://localhost:8080/chat \
     -H "Content-Type: application/json" \
     -d '{"name": "Abraham Lincoln"}'

이름, 생년월일, 출생 국가가 포함된 JSON 구조화된 출력을 가져오는지 확인합니다.

5. Cloud Run에 배포

gcloud run deploy 명령어를 사용하여 에이전트 애플리케이션을 Cloud Run에 배포합니다. 다음 명령어는 Cloud Build를 사용하여 컨테이너를 빌드하고 한 단계로 Cloud Run에 배포합니다.

YOUR_API_KEY를 실제 Gemini API 키로 바꿉니다.

gcloud run deploy gemini-fastapi-service \
  --source . \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars GOOGLE_API_KEY=<YOUR_API_KEY>

참고: 프로덕션의 경우 일반 환경 변수 대신 Google Secret Manager 를 사용하여 API 키를 처리하는 것이 좋습니다.

배포되면 터미널에 사용할 준비가 된 엔드포인트가 표시됩니다.

6. 배포 테스트

Cloud Run 엔드포인트를 사용하고 curl을 실행하여 예상되는 결과를 가져오는지 확인합니다.

curl -X POST <CLOUD_RUN_ENDPOINT> \
     -H "Content-Type: application/json" \
     -d '{"name": "Abraham Lincoln"}'

로컬에서 실행 중인 애플리케이션에서 가져온 것과 동일한 결과를 가져와야 합니다.

7. 삭제

이 Codelab에서 사용한 리소스의 비용이 Google Cloud 계정에 청구되지 않도록 하려면 다음 단계를 따르세요.

1. Google Cloud 콘솔에서 리소스 관리 페이지로 이동합니다.
2. 프로젝트 목록에서 삭제할 프로젝트를 선택하고 삭제 를 클릭합니다.
3. 대화상자에서 프로젝트 ID를 입력하고 종료 를 클릭하여 프로젝트를 삭제합니다.

8. 축하합니다

축하합니다. Cloud Run에 배포된 LangChain 에이전트를 만들고 상호작용했습니다.