Skip to content

Runtime Flow

End-to-End Flow

현재 workflow는 아래 순서로 동작합니다.

flowchart TD
    S["START"] --> V["validate_request"]
    V --> C["collect_context"]
    C --> P["prepare_agent_work"]
    P --> H["resolve_review"]
    H -->|review enabled| R["interrupt / human review"]
    H -->|review disabled| A2["auto review"]
    R --> E["execute_action"]
    A2 --> E
    R -->|all actions rejected| X["close_request"]
    E --> X
    X --> END["END"]

Interrupt-Based Human Review

사람 검토 단계는 외부 gateway 호출이 아니라 LangGraph interrupt로 처리됩니다. 다만 이 단계 자체는 optional입니다.

위치: - src/domain_agent/orchestration/langgraph/nodes/deterministic.py

개념 흐름:

  1. ReviewPacket 생성
  2. review가 필요하면 interrupt(review_packet) 호출
  3. review가 필요 없으면 자동 PlanReviewResult 생성
  4. workflow pause 또는 즉시 진행
  5. 필요 시 외부 caller가 사람 입력을 수집
  6. Request.record_review_result(...) 적용
  7. review를 통과한 action만 실행

즉, 사람이 응답하기 전까지 graph가 멈추고, 재개 payload는 도메인적으로 의미 있는 review result입니다. 현재 기본 구현은 PlanReviewResult를 사용합니다.

Service-Level Loop

src/domain_agent/application/use_cases.py의 AgentWorkflowService.run(...)은 다음 식으로 동작합니다.

sequenceDiagram
    participant Caller
    participant Service
    participant Graph
    participant Human

    Caller->>Service: run(request_id, review_handler)
    Service->>Graph: invoke(initial_state)
    Graph-->>Service: __interrupt__ with ReviewPacket
    Service->>Human: review_handler(packet)
    Human-->>Service: PlanReviewResult
    Service->>Graph: invoke(Command(resume=...))
    Graph-->>Service: final workflow state
    Service-->>Caller: result

이 구조의 장점: - CLI, API, web UI가 모두 같은 resume 모델 사용 가능 - workflow는 pause/resume만 알고, 입력 채널은 모름 - review semantics는 domain 모델로 유지 - autonomous path와 review path가 같은 graph에서 공존

CLI Demo Flow

위치: - src/domain_agent/adapters/inbound/cli_demo.py - src/domain_agent/adapters/inbound/cli_review.py

CLI demo는 아래처럼 동작합니다.

  1. generic Request 생성
  2. in-memory dependencies 구성
  3. workflow 실행
  4. interrupt 발생 시 CLIReviewCollector가 review packet 렌더링
  5. action별 a/r 입력 수집
  6. PlanReviewResult 생성
  7. workflow resume
  8. 최종 status / execution result 출력

State Shape

workflow state는 src/domain_agent/orchestration/langgraph/state.py에 정의되어 있습니다.

주요 필드: - request - context - analysis - agent_plan - proposal - review_packet - plan_review_result - review_decision - execution_result - completed_steps

이 state는 디버깅과 테스트에 유리하지만, 일부 값은 checkpoint round-trip 과정에서 tuple이 list로 바뀔 수 있습니다.
그래서 테스트는 identity보다 semantic equality 중심으로 작성하는 편이 맞습니다.

What To Read If You Want To Change Behavior

review 규칙을 바꾸고 싶을 때: - src/domain_agent/domain/models.py - domain-model.md

review packet 모양을 바꾸고 싶을 때: - src/domain_agent/application/dto.py

workflow 단계나 분기를 바꾸고 싶을 때: - src/domain_agent/orchestration/langgraph/graph.py - src/domain_agent/orchestration/langgraph/nodes/deterministic.py - src/domain_agent/orchestration/langgraph/nodes/llm.py

실행 채널을 CLI 외 다른 것으로 바꾸고 싶을 때: - src/domain_agent/adapters/inbound/cli_review.py를 참고해 ReviewPacket -> PlanReviewResult collector를 새로 만들면 됩니다.

Code References

  • src/domain_agent/application/use_cases.py
  • src/domain_agent/orchestration/langgraph/graph.py
  • src/domain_agent/orchestration/langgraph/state.py
  • src/domain_agent/orchestration/langgraph/nodes/deterministic.py
  • src/domain_agent/orchestration/langgraph/nodes/llm.py
  • src/domain_agent/application/dto.py
  • src/domain_agent/domain/models.py
  • src/domain_agent/adapters/inbound/cli_demo.py
  • src/domain_agent/adapters/inbound/cli_review.py