feat: #75 PR 3 — auto-Task wrap 분기 + session/a2a_context 종료 모델 정정 (docs first)

[hagyutae]

Summary

#75 의 PR 3. 세 가지 작업 묶음:

1. auto-Task wrap 분기 — callee graph 의 LLM structured output 으로 requires_task 결정 → handler 가 hint 만 보고 Message / Task 분기
2. session 종료 개념 제거 — sessions 는 영구 namespace, ended_at / SessionEndEvent / SessionEndProcessor 폐기
3. agent graph building blocks 추출 — Primary / Librarian 의 99% 동일 graph.py 코드 정리. shared 가 ReAct building blocks 만 제공, 각 agent 가 명시적 조립 (옵션 D)

부수: 옛 디자인 (workflow.base + extensions / langgraph_base / extensions/ 디렉터리) 와 어긋난 docs 일괄 정정.

(1) auto-Task wrap 분기 — LLM 추론 기반

결정 메커니즘

callee graph 안 classify_response 노드가 llm.with_structured_output(A2AResponseDecision) 으로 LLM 강제 — 자기 응답 의도 (조회 / 위임 / long-running) 보고 requires_task 채움. handler 는 graph state 에서 hint 만 읽어 분기 (분류 / 분석 로직 0).

class A2AResponseDecision(BaseModel):
    requires_task: bool        # LLM 추론 결정
    reason: str                # 결정 근거 (관찰용)

분기 결과

결정	publish 패턴	DB
requires_task=False	a2a.context.start + a2a.message.append × 2	a2a_messages=2, a2a_tasks=0
requires_task=True	위 + a2a.task.create + a2a.task.status_update × 2 (WORKING/COMPLETED) + agent reply with task_id	a2a_messages=2, a2a_tasks=1, a2a_task_status_updates=2

Streaming 한계

SendStreamingMessage 는 SSE 형식 자체가 Task 중심 (initial Task → TaskArtifactUpdateEvent × N → TaskStatusUpdateEvent) 이라 항상 Task wrap. classify_response 는 실행되며 hint 는 graph state 에 기록되지만 (관찰용) handler 가 사용하지 않음. Message-only streaming 은 향후 확장.

Persona 가이드

Primary persona text 에 결정 가이드 단편 추가 (위임 / long-running = true, 조회 / fact = false).

Prompt 위치 — shared

A2A protocol-level 결정이라 prompt 텍스트는 shared/a2a/decision.py:DEFAULT_RESPONSE_DECISION_PROMPT 상수. 모든 agent 가 import. 코드 안 자연어 자료 박지 않는다는 root CLAUDE.md "AI 에이전트 런타임 자산" 원칙 준수.

(2) session 종료 모델 정정

session 은 사용자 대화창 metaphor 상 종료 개념 없음 (Slack DM / ChatGPT 류 — 사용자가 언제든 재개).

폐기

• SessionEndEvent 클래스 + wire session.end
• SessionEndProcessor (chronicler)
• sessions.ended_at 컬럼 (migration 005)
• SessionUpdate.ended_at / SessionRead.ended_at 필드
• (이전 PR 2 에서 이미) UG publish_session_end 호출

유지

• A2AContextEndEvent / A2AContextEndProcessor / a2a_contexts.ended_at — agent 가 결정해 발화 (PR 5 예정)

(3) agent graph building blocks 추출 (옵션 D)

Primary / Librarian 의 graph.py 가 99% 동일 (persona / tools 만 다름) 인 상태에서 새 agent 추가마다 복붙 강요되던 구조 정리. shared 가 building blocks 만 제공하고 각 agent 가 자기 graph 를 명시적으로 조립 — topology 자유 보존 + DRY.

신설 — shared/src/dev_team_shared/agent_graph/

ReAct 패턴 building blocks (Pattern B — in-process library):

• make_llm_call_node(persona, llm_with_tools) — persona + messages → LLM
• make_tool_node(tools) — tool_calls 실행 → ToolMessage
• should_continue_react(state, *, when_done) — tool_calls 분기 helper
• serialize_tool_result(value) — tool 결과 → JSON

확장 — shared/src/dev_team_shared/a2a/decision.py

A2A 프로토콜 차원 결정 (모든 agent 공유):

• A2AResponseDecision Pydantic schema
• DEFAULT_RESPONSE_DECISION_PROMPT (system prompt)
• make_classify_response_node(llm, *, system_prompt) — LangGraph 노드 factory
• format_conversation_for_classifier(messages) — Anthropic "must end with user msg" 회피용 helper

분류 원칙

• ReAct 일반 building blocks → agent_graph/
• A2A 프로토콜 결정 → a2a/decision.py
• agent 정체성 / 도메인 워크플로 → 각 agent 의 config/ (persona) + resources/*.md

결과

각 agent graph.py 는 building blocks 조립만:

• Primary: 217 → 107 줄 (50% 감소)
• Librarian: 187 → 84 줄 (55% 감소)
• Librarian 도 자동으로 classify_response 포함 (protocol-level 일관)

LangGraph subgraph feature 는 사용 가능

위 결정은 config 가 dispatch 하는 패턴 (workflow.base + extensions) 거부일 뿐, LangGraph 자체의 subgraph (StateGraph 안 StateGraph) composition 은 자유롭게 사용 가능. 향후 Architect 의 three-stage design 같이 자연스러운 subgraph 단위는 build_graph() 안에서 명시적으로 끼움 — config 가 아닌 코드가 결정.

변경 파일

코드 — A2A response decision

• shared/src/dev_team_shared/a2a/decision.py (신설) — schema + prompt + factory + helper
• shared/src/dev_team_shared/a2a/__init__.py — export
• agents/primary/config/base.yaml — persona 결정 가이드

코드 — handler 분기

• shared/src/dev_team_shared/a2a/server/graph_handlers/send_message.py — hint 보고 Message / Task 분기
• shared/src/dev_team_shared/a2a/server/graph_handlers/factories.py — trivial Message helper 신설
• shared/src/dev_team_shared/a2a/server/graph_handlers/stream.py — classify_response token 필터

코드 — agent graph building blocks

• shared/src/dev_team_shared/agent_graph/__init__.py (신설)
• shared/src/dev_team_shared/agent_graph/react.py (신설) — ReAct building blocks
• agents/primary/src/primary_agent/graph.py — shared blocks 조립으로 슬림화
• agents/librarian/src/librarian_agent/graph.py — 동일 패턴 + classify_response 자동 포함

코드 — session 종료 cleanup

• shared/src/dev_team_shared/event_bus/events.py — SessionEndEvent 폐기
• shared/src/dev_team_shared/event_bus/__init__.py — exports 정리
• shared/src/dev_team_shared/doc_store/schemas/session.py — ended_at 필드 제거
• chronicler/src/chronicler/processors/__init__.py — SessionEndProcessor 등록 제거
• chronicler/src/chronicler/processors/session_end.py — 삭제
• mcp/doc-store/migrations/005_drop_session_ended_at.sql (+ rollback) — 컬럼 drop

문서

• shared/CLAUDE.md — §3 카탈로그에 agent_graph/ 추가, a2a/decision.py 역할 명시
• shared/src/dev_team_shared/a2a/messaging.md — trace 시작점 셋, context lifecycle, Task/Message 분기 (LLM 추론 + streaming 한계 + prompt 위치)
• docs/proposal/architecture-chat-protocol.md — chat lifecycle 표 + tier 비교 표 (session.end 제거)
• docs/proposal/architecture-event-pipeline.md — chat / a2a layer 이벤트 표 (session 종료 개념 없음 명시 + a2a.context.end agent 결정)
• docs/proposal/architecture-user-gateway.md — UG publish 항목
• docs/proposal/architecture-role-config.md — workflow 필드 = 현재 미사용 명시
• docs/proposal/architecture-agent-internals.md — building blocks 조립 패턴 + LangGraph subgraph 사용 가능성 명시
• docs/proposal/knowledge-model.md — sessions / a2a_contexts schema 설명
• docs/proposal/project-structure.md — 옛 구조 → 현 구조 전면 재작성

테스트

• chronicler/tests/test_handler.py — SessionEnd 관련 제거 (13 → 12)
• shared/tests/test_event_bus.py — chat layer 검증 갱신 (3 → 2 events)

검증

• 단위: shared 57/57 · chronicler 12/12 · doc-store 24/24 pass
• e2e (SendMessage 직접 — Primary):
  • 정보 조회 prompt → LLM requires_task=False → a2a_messages=2, a2a_tasks=0 ✅
  • 위임 시도 prompt → Primary 가 미구현 인식 → Message 응답 (정확) ✅
• e2e (UG /api/chat = SendStreamingMessage):
  • 단순 인사 → LLM requires_task=False 기록 + 실제론 Task wrap (streaming 제약) ✅
• e2e (Librarian): 부팅 정상, classify_response 자동 포함 확인
• migration 005 적용 후 sessions.ended_at 컬럼 drop 확인

후속

• PR 4 (확장 — PR 4 + 옛 PR 5 합침) — UG↔P/A chat protocol end-to-end 도입:
  • chat protocol wire (Primary chat endpoint REST POST + SSE)
  • UG 전환 (A2A → chat protocol)
  • FE multi-chat UI
  • Primary graph 의 chat session 통합 (session_id ↔ thread_id)
  • agent-side chat.append (role=agent) publish
  • Assignment 라이프사이클 publish (P 가 chat 중 합의된 work item)
  • A2AContextEndEvent 발화 위치 결정 (agent 가 inter-agent 대화 마무리 판단)
  • 작업 큼 — commit 분리로 리뷰. 머지 시점엔 chat protocol 이 wire + graph + UG + FE 모두 정합 단위
  • 자세한 인계: memory/pr4_chat_protocol_followups.md

🤖 Generated with Claude Code