Skip to content

Extension Guide

기본 원칙

새 도메인을 추가할 때는 generic core를 먼저 바꾸지 말고, 바깥에서 조합하는 쪽을 먼저 검토하는 게 맞습니다.

즉 우선순위는:

  1. example app 또는 별도 app 패키지에서 해결
  2. 그래도 공통 의미가 맞으면 generic core로 승격

새 도메인을 추가하는 최소 경로

  1. 새 request type 정의
  2. generic Request로 변환
  3. context 수집 방식 구현
  4. proposal/analysis 생성 방식 구현
  5. execution 방식 구현
  6. 필요하면 review collector 또는 review handler 연결

가장 자주 바꾸는 곳

1. 도메인별 request type

예: - examples/autonomous_digest/autonomous_digest_demo/models.py - examples/operational_change/operational_change_demo/models.py - examples/mock_api/mock_api_demo/models.py

패턴: - domain-specific request model을 만든다 - .to_request()로 generic Request로 변환한다

2. 컨텍스트 수집

위치: - src/domain_agent/application/ports.py

구현 예: - ContextProvider

여기에 넣을 수 있는 것: - DB 조회 - 외부 API 조회 - 파일/문서 검색 - 향후 retrieval adapter

3. planning / proposal generation

현재 포트: - AgentEngine

이 포트는 다음을 한 번에 반환합니다.

  • analysis
  • optional agent plan
  • proposal

즉 LangChain의 structured output이나 tool-calling 결과를 하나의 계약으로 연결하기 쉬운 형태입니다.

4. 실행기

포트: - ActionExecutor

실행기 구현은 "review를 통과한 action만 실행"이라는 도메인 규칙을 존중해야 합니다.

현재 참고 구현: - src/domain_agent/adapters/outbound/in_memory.py

LangGraph / LangChain을 더 적극적으로 쓰려면

현재도 human-in-the-loop orchestration은 LangGraph에 위임하고 있습니다.

다음 단계로 자연스러운 확장:

  • LangChain tool calling
  • structured output for planning
  • LangGraph checkpoint backend 교체
  • 실제 persistence + review UI 연결

추천 방향:

  • orchestration은 LangGraph에 더 위임
  • tool/planning은 LangChain에 더 위임
  • review semantics는 domain에 유지

즉, 메커니즘은 프레임워크에 맡기고 의미는 템플릿이 가진다는 원칙을 유지하면 됩니다.

현재 reference implementation:

  • src/domain_agent/adapters/outbound/langchain.py

이 adapter는 langchain_core의 prompt/model/parser 조합으로 AgentWorkResult를 만들고, tool 목록을 prompt에 포함한 뒤 planned action의 tool_name을 검증합니다.

무엇을 Generic Core로 올릴지 판단하는 기준

generic core로 올릴 가치가 큰 것:

  • 모든 도메인에서 공통인 lifecycle 규칙
  • review packet 공통 shape
  • action-level review semantics
  • 공통 workflow routing
  • optional human interaction toggle

example app에 두는 게 나은 것:

  • 특정 도메인의 request model
  • 특정 API client
  • 특정 tool set
  • 특정 policy wording

예를 들어: - examples/autonomous_digest는 review 없는 autonomous flow를 보여줍니다 - examples/langchain_digest는 LangChain-backed AgentEngine wiring을 보여줍니다 - examples/operational_change와 examples/mock_api는 review-enabled flow를 보여줍니다

Avoid

이 저장소를 무겁게 만드는 대표 패턴:

  • example-specific rule을 domain에 바로 넣는 것
  • LangChain 객체를 domain 모델에 직접 들이밀는 것
  • UI/CLI 입력 방식이 workflow node 내부에 박히는 것
  • generic core가 example-specific adapter를 import하는 것

Practical Next Steps

실무적으로 다음 확장이 자연스럽습니다.

  1. 실제 LangChain planner/tool adapter
  2. 실제 LangChain agent engine adapter
  3. review policy 기반 auto-execute 분기
  4. DB-backed repository
  5. web UI 또는 API review surface
  6. CI 기반 package/docs publishing

Code References

  • src/domain_agent/application/ports.py
  • src/domain_agent/adapters/outbound/in_memory.py
  • examples/operational_change/operational_change_demo/models.py
  • examples/mock_api/mock_api_demo/models.py