LangChain 프로젝트 (agents-cli)
에이전트는 app/agent.py에서 root_agent로 내보낸 컴파일된 LangGraph 그래프입니다.
google.adk 의존성이 없고 ADK 러너도 없습니다. 다른
google-agents-cli-* 스킬은 ADK를 가정합니다. 에이전트 자체를 설명하는 부분에서는 이 스킬이 우선합니다.
실험적이며 Agent Runtime은 성능이 저하됩니다. cloud_run 또는 gke에 배포하세요.
agent_runtime에서는 앱이 서비스되지만, publish gemini-enterprise가 거부되고,
Console 플레이그라운드가 호출할 수 없으며, Console 세션/추적이 비어 있습니다. 세 가지 모두 이 프로젝트가 제공하지 않는 ADK reasoning_engine 라우트를 필요로 합니다.
권장하기 전에 이 점을 알리세요.
ADK 안내의 매핑
| ADK 안내 | 이 프로젝트 |
|---|---|
LlmAgent, Agent, google.adk.tools | langchain.agents.create_agent, 일반 Python 함수(도구), 또는 컴파일된 StateGraph |
adk web, adk run | agents-cli playground (langgraph dev 실행) |
agents-cli run 뒤의 ADK 러너 | agents-cli run은 그래프를 인프로세스로 호출 |
agents-cli eval dataset synthesize, eval optimize | 사용 불가: 둘 다 ADK를 통해 에이전트를 구동합니다. 명령어가 이렇게 말하고 종료됨 |
app/agent.py에 LlmAgent 추가 | app/agent.py에서 그래프를 변경하고, 이름 root_agent 유지 |
계약
다음 두 가지는 유지하세요. 내부에 무엇을 구축하든 상관없습니다:
app/agent.py는root_agent를 내보냅니다. 이는messages상태를 가진 컴파일된 그래프입니다. 호출자는root_agent.invoke({"messages": [...]})와root_agent.astream(stream_mode="messages")만 사용합니다.app/fast_api_app.py는app을 노출합니다. 모든 배포 대상은uvicorn app.fast_api_app:app을 실행합니다.
도구를 추가한다는 것은 독스트링이 있는 타입이 지정된 함수를 작성하고 tools=[...]에 전달하는 것을 의미합니다.
프레임워크 전환(LangGraph StateGraph,
deepagents.create_deep_agent)은 app/agent.py만 다시 작성하면 됩니다.
Pre-1.0 LangChain(LCEL 체인, AgentExecutor)은 지원되지 않습니다. (컴파일된 그래프가 아님)
명령어
agents-cli install # uv sync
agents-cli playground # langgraph dev, 포트 8080
agents-cli run "hello" # 그래프를 인프로세스로 호출
agents-cli eval generate --dataset tests/eval/datasets/basic-dataset.json -o tests/eval/output/
agents-cli eval grade --traces tests/eval/output/<dataset>.json --config tests/eval/eval_config.yaml
agents-cli deploy # 변경 없음
agents-cli scaffold enhance -d cloud_run --cicd-runner github_actions # 나중에 인프라 추가
playground, run, eval generate는 프로젝트 루트의 agents-cli-extension.yaml에 의해 재정의됩니다.
모든 명령어 앞에 AGENTS_CLI_DISABLE_OVERRIDES=1을 붙이면 내장 명령어를 사용합니다.
서빙
A2A 전용: JSON-RPC (POST /a2a/app), 카드 (/a2a/app/.well-known/agent-card.json), 헬스 체크 (/health).
토큰 스트리밍은 astream(stream_mode="messages")에서 제공됩니다.
흔한 실수
root_agent또는app이름 변경은run, 평가 및 배포를 망가뜨립니다.eval dataset synthesize또는eval optimize사용: ADK가 필요합니다.tests/eval/datasets/에 케이스를 작성하고eval generate+eval grade를 사용하세요./run_sse또는 ADK 세션 라우트를 기대함: 이 서버는 A2A를 제공합니다.- 배포된 에이전트에 대해
AGENTS_CLI_DISABLE_OVERRIDES=1없이agents-cli run --url ...실행: 로컬 그래프를 대신 호출합니다. run및eval generate는 ADC를 통해 Vertex AI에서 Gemini를 호출하므로,GOOGLE_CLOUD_PROJECT와 자격 증명, 또는.env의GOOGLE_API_KEY/GEMINI_API_KEY가 필요합니다.
참조
references/langchain.md— 프레임워크 계약 및 명령어별 세부 사항.references/samples.md— 형태별로 복사할 가치가 있는 에이전트.