LangChain deepagents용 'dcode-agent-kit' — 한 명령으로 에이전트 스캐폴드 생성(오픈소스)

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

작성자는 LangChain의 deepagents 패턴을 여러 프로젝트에서 반복해 직접 스캐폴딩하던 번거로움을 해소하기 위해 dcode-agent-kit이라는 Claude Code 스킬을 만들었다. 이 도구는 '/new-dcode-agent' 명령으로 프로젝트를 인터뷰해 agent.py, model.py, README를 바로 생성하고 create_deep_agent 호출 구조와 동일 디렉터리 import를 유지해 수동 설정을 제거한다.

생성되는 코드에는 안전 장치가 기본으로 포함되어 있다. 특히 상태를 변경하는 툴은 interrupt_on이 단독으로는 무효화되는 문제를 겪었기 때문에 스캐폴더가 항상 checkpointer(InMemorySaver 같은 구현)와 쌍으로 삽입하고, 에이전트가 상태 변경 전에 일시정지하는 검증 스니펫을 추가한다. 또한 LLM 연결은 LLM_API_KEY, LLM_BASE_URL, LLM_MODEL 같은 환경변수 기반으로 구성되어 llama.cpp·Ollama·vLLM·LM Studio 같은 OpenAI 호환 엔드포인트와 호환되도록 설계되어 벤더 종속을 최소화한다.

현재는 v0.1.0 상태로 작성자가 피드백을 구하고 있으며, 스캐폴드 출력 형식은 SDK용 독립 실행형, dcode agent 정체성(AGENTS.md용), 또는 두 가지를 모두 생성하는 세 가지 옵션을 지원한다. 실무에서는 초기 셋업 시간 절감과 안전성 확보라는 장점이 있고, 구체적 API·폴더 구조·출력 형태에 대해 커뮤니티 의견을 모으는 단계이다.

실용적 조언

뮤테이팅 툴을 에이전트에 연결할 때는 interrupt_on을 설정하되 checkpointer(InMemorySaver 등)를 함께 생성해 에이전트가 실제로 일시정지하는지 검증하는 스니펫을 코드에 포함할 것.
에이전트 스캐폴딩은 인터뷰형 위자드로 목적·툴·모델 정보를 받아 자동 생성하면 초기 설정 시간을 크게 단축하고 프로젝트별 편차를 줄일 수 있다.
LLM 연결은 LLM_API_KEY·LLM_BASE_URL·LLM_MODEL 같은 환경변수 기반으로 구성해 로컬 런타임과 클라우드 엔드포인트를 자유롭게 교체할 것.

섹션별 상세

반복적인 에이전트 스캐폴딩 비용이 문제였고 작성자는 동일한 프로젝트 구조·모델 배선·휴먼 인-더-루프 가드레일을 여러 번 복사·붙여넣기해 왔다. 이 문제를 해결하기 위해 Claude Code 스킬 형태의 한 명령 '/new-dcode-agent'를 도입해 프로젝트에서 인터뷰 방식(목적·툴·모델·뮤테이션 여부 등)을 받도록 했다. 인터뷰 결과로 agent.py, model.py, README가 생성되며 agent.py는 같은 디렉터리의 model.py에서 chat_model을 임포트하고 create_deep_agent 호출로 에이전트를 초기화한다. 이 방식은 템플릿 반복을 제거해 개발 초기 세팅 시간을 단축시키고 코드 일관성을 확보하는 실무적 이익을 제공한다.

text

/new-dcode-agent

프로젝트 루트에서 실행하는 Claude Code 스킬 명령어 예시로, 인터뷰형 위자드가 실행되어 에이전트 스캐폴드를 생성한다.

에이전트가 외부 상태를 변형하는 '뮤테이팅 툴'의 안전 처리에 구조적 문제점이 존재했고, 구체적으로 interrupt_on 옵션은 checkpointer가 제공되지 않으면 묵묵부답(no-op)으로 동작해 예기치 않은 동작을 초래했다. dcode-agent-kit는 이 관계를 고정해 항상 interrupt_on과 체크포인터(InMemorySaver 같은 구현)를 함께 삽입하는 검증 스니펫을 생성하며, 생성된 코드에 상태 변경 전 에이전트가 일시정지하는 어설션을 포함한다. 작성자는 이 문제로 실무에서 시간 손실을 경험했다고 적시했고, 도구의 기본을 읽기 전용으로 유지하고 상태 변경 시 명시적 확인을 요구하는 설계로 안전성을 높였다. 이런 처리로 운영 환경에서 무분별한 상태 변경으로 인한 사고 위험이 줄어드는 효과가 기대된다.

python

from model import chat_model

agent = create_deep_agent(model=chat_model, tools=[tool1, tool2], system_prompt="...")

# 예: mutating tool을 사용할 때는 interrupt_on과 checkpointer를 함께 전달해야 안전하게 동작함
agent.run(interrupt_on=[...], checkpointer=InMemorySaver())

생성되는 agent.py의 핵심 구조 예시로, 같은 디렉터리의 model.py로부터 모델을 임포트하고 create_deep_agent 호출로 에이전트를 초기화하며, 상태 변경 툴은 interrupt_on과 체크포인터를 통해 게이트한다.

생성된 스캐폴드는 특정 벤더에 종속되지 않도록 환경변수 기반의 ChatOpenAI 커넥터를 사용해 유연성을 확보했다. 구체적으로 LLM_API_KEY, 선택적 LLM_BASE_URL, LLM_MODEL 환경변수를 통해 OpenAI 호환 엔드포인트(예: llama.cpp, Ollama, vLLM, LM Studio 포함)에 연결할 수 있게 설계되어 있다. 생성 코드는 어떤 특정 호스트도 하드코딩하지 않으며, SDK용 독립 실행형 에이전트, dcode agent 정체성(AGENTS.md용), 또는 두 형태를 모두 생성하는 세 가지 출력 형태를 지원한다. 이 접근은 로컬 실행과 클라우드 엔드포인트 간 전환을 쉽게 해 벤더 락인 위험을 낮춘다.

실무 Takeaway

프로젝트 초기 반복 작업을 줄이려면 인터뷰 기반 스캐폴더를 통해 agent.py·model.py·README를 자동 생성해 일관된 구조와 가드레일을 자동으로 주입해야 한다.
뮤테이팅 툴은 interrupt_on과 checkpointer를 항상 짝지어 전달해 에이전트가 상태 변경 전 실제로 일시정지·검증하도록 구현해야 안전 사고를 줄일 수 있다.
LLM 연결은 환경변수(LMM_API_KEY, LLM_BASE_URL, LLM_MODEL) 기반으로 구성해 OpenAI 호환 로컬·원격 런타임을 교체 가능하게 만들면 벤더 종속을 피할 수 있다.
스캐폴드는 SDK용 독립 실행 형태와 AGENTS.md 아이덴티티 형태를 분리해 필요에 따라 헤드리스 실행 또는 대화형 디버깅 환경을 선택할 수 있게 하면 개발·배포 유연성이 증가한다.

언급된 도구

LangChain추천

에이전트·체인 구성과 create_deep_agent 같은 유틸을 통해 에이전트 스캐폴딩에 사용되는 라이브러리

Claude Code중립

인터뷰형 스킬로 명령 실행 시 프로젝트에 대해 질의하고 스캐폴드를 생성하는 코드 자동화 인터페이스

ChatOpenAI (env-driven connector)중립

환경변수로 구성되는 OpenAI 호환 LLM 커넥터(LLM_API_KEY, LLM_BASE_URL, LLM_MODEL)로 다양한 엔드포인트와 호환되도록 사용

llama.cpp / Ollama / vLLM / LM Studio중립

OpenAI 호환 엔드포인트 예시로, 로컬 또는 자체 호스팅된 런타임에서 생성된 코드를 실행하는 옵션

언급된 리소스

GitHubdcode-agent-kit (GitHub)

문서AGENTS.md (referenced identity format)

from model import chat_model agent = create_deep_agent(model=chat_model, tools=[tool1, tool2], system_prompt="...") # 예: mutating tool을 사용할 때는 interrupt_on과 checkpointer를 함께 전달해야 안전하게 동작함 agent.run(interrupt_on=[...], checkpointer=InMemorySaver())

LangChain deepagents용 'dcode-agent-kit' — 한 명령으로 에이전트 스캐폴드 생성(오픈소스)

TL;DR

실용적 조언

섹션별 상세

실무 Takeaway

언급된 도구

언급된 리소스

LangChain deepagents용 'dcode-agent-kit' — 한 명령으로 에이전트 스캐폴드 생성(오픈소스)

TL;DR

실용적 조언

섹션별 상세

실무 Takeaway

언급된 도구

언급된 리소스

관련 토론

댓글

관련 피드

관련 토론

댓글

관련 피드