릴리스이전 버전
v0.2.2 patch 기준 Breaking 있음 — upstream_parts_policy="replace" 에서 current data/files 가 없을 때 upstream 을 자동 echo 하던 fallback 이 제거되었습니다. 기본값은 계속 "replace" 이며, upstream 을 최종 응답에 포함해야 하면 "append" 를 명시하세요.
| 영역 | 변경 |
|---|
create_server(upstream_parts_policy=...) | "replace" (기본, current only) / "append" (current + upstream) — workflow 누적분을 최종 응답에 포함할지 정책. AgentCard 미노출. 상세 |
| Flow pending recheck (A2A + MCP) | 미등록·availability=inactive ID 안전 사전 선언 가능. 호출 시점 자동 재조회, TTL 2s + asyncio.Lock 폭증 차단. PendingAgentRef / MCPHandle.try_recheck_pending() public API 제공. 상세 |
metadata.history cold-start prefill | 호스트(VoltAgent 등)가 보낸 prior turns 를 LangGraph state.messages 에 1회 시드 → cross-agent 컨텍스트 복원. checkpointer 보유 시 자동 무시, 10턴 cap. 상세 |
| A2A sub-agent streaming relay | a2a_call_node 가 get_stream_writer() 로 sub-agent chunk push → 사용자에게 chunk 단위 SSE 도달. 단일 A2A 는 즉시 relay, 다중 A2A 는 completion-order section streaming |
| Final-response artificial chunking | sub-agent 가 streaming 미지원이어도 _flush_text 가 문장/단어 경계로 분할 emit → SSE artifact-update 점진 도착. completed_task 의 final artifact 와 동일 artifactId="response" 공유 |
PendingA2ATool — pending A2A 자연어 fallback | 미배포·미등록 A2A 마다 stub tool 자동 생성. LLM 호출 → “unavailable” 메시지 → ReAct 자연어 fallback (MCP [Tool Error] UX parity). deploy 시 다음 reload 에서 real tool 로 자동 교체 |
| CLI 템플릿 · 가이드 | 9개 scaffold 의 _shared.py 에 opt-in 주석 추가. /guide/upstream-parts-policy, /guide/input-contracts 보강 |
| 영역 | 변경 |
|---|
CustomAgentExecutor.__init__ · CreateServerRequest | keyword upstream_parts_policy="replace" 추가. backward compatible |
upstream_parts_policy="replace" patch | current data/files 가 없을 때 upstream 을 자동 echo 하던 fallback 제거. replace 는 이름 그대로 current 결과만 응답 |
| 배포 Dockerfile 런타임 | uv run python main.py → venv 기준 python main.py. ENV PATH="/app/.venv/bin:$PATH" 적용으로 런타임 재동기화·네트워크 의존 회피 |
LLaMONRegistryClient.resolve_url | 항상 PendingAgentRef (str subclass) 반환. 기존 호출 코드 변경 0 |
MCPHandle.call() failure | tool 미존재 + _failures 있으면 sentinel MCPToolExecutionResult(status="error") 반환 (이전: ValueError raise) |
| Router 순서 재배치 | skill heuristic → A2A heuristic → skill LLM → A2A LLM. 명백한 A2A 매칭 시 skill LLM 호출 회피 (~1.35s + $0.0002/요청 절감) |
_rebuild_tools 위임 | registry runtime 업데이트 경로가 recompute_container_tools 호출 → pending stub 누락 갭 해소 |
| 영역 | 버그 |
|---|
MCP/A2A 실패 시 state=failed 노출 | tool wrapper / A2ATool 가 connection · ExceptionGroup · TaskGroup wrap 까지 sentinel text 변환 → LLM 자연어 응답 + state=completed |
| 배포 삭제된 에이전트 호출 우회 | A2A 카드 url 을 deployment proxy_url 로 강제 override. fallback 에서 raw target_url / server_url 제거 |
| GraphRecursionError → INTERNAL_ERROR | agent.invoke 가 특수 catch — 한국어 graceful 응답 (state=completed) |
@a2a-attachment: 마커 query 누수 | 인밴드 주입 shim 제거 — 첨부는 a2a_files / a2a_data 메타데이터 채널로만. upstream TextPart 안의 마커도 strip |
MCP ToolException / McpError escape | LangGraph ToolNode re-raise 갭 보완 — 결정적 sanitized text 변환. UrlElicitationRequiredError (OAuth) 만 raise 유지 |
| 시나리오 | 작업 |
|---|
| 기존 호출자 | 대부분 수정 불필요. 단, replace 의 text-only + upstream fallback echo 에 의존했다면 append 로 전환 |
| upstream 누적 보존이 필요한 경우 | create_server(upstream_parts_policy="append") 한 줄 추가 |
| 워크플로우가 이전 parts 를 계속 다음 agent 에 전달하는 경우 | 기본 replace 유지 권장. 중간 agent 에서 append 를 켜면 중복 누적 가능 |
| 최종 응답에 이전 agent parts 까지 포함해야 하는 경우 | 마지막 agent 에 upstream_parts_policy="append" 명시 |
| 기존 Dockerfile | 그대로 동작. 운영 배포에서는 ENV PATH="/app/.venv/bin:$PATH" + CMD ["python", "main.py"] 적용 권장 |
| Flow pending recheck | 수정 불필요 — resolve_url / MCPHandle 시그니처 무변경 |
자세한 가이드: Upstream Parts 정책 (replace/append)
| 영역 | 검증 |
|---|
| Upstream parts (append / replace) | 단위 매트릭스 4 케이스 · AgentCard 비노출 parametrized · send 경로 분기 capture · RuntimeAdapter 무영향 · 인자 검증 (ValueError) · 3-layer backstop |
| Dockerfile 런타임 | ENV PATH + CMD ["python", "main.py"] 렌더 검증, prepare-offline rewrite 후에도 보존 |
| Flow pending recheck (A2A + MCP) | test_pending_agent_flow (4) + test_flow_pending_cross_path (5) + test_flow_pending_reverse (7) — forward/reverse 사이클 |
| Availability filter · MCPHandle recheck | test_availability_filter (8) + test_mcp_handle_recheck (12) + test_a2a_facade_pending (6) — TTL/Lock · sentinel safety |
| Attachment marker 채널 분리 | test_executor::test_attachment_metadata_does_not_leak_into_query · test_request_context::TestPrimaryText 3 케이스 |
| PendingAgentRef | test_pending_agent_ref (15) — str subclass · resolve_now TTL/Lock · error narrowing |
| A2A streaming relay (single + multi) | test_routed_graph 확장 — _relay_a2a_stream · _relay_multi_a2a_sections completion-order / skip-failed / no-writer |
| Subgraph 멀티모드 unwrap | test_subgraph_event_unwrap (7) — list+subgraphs 3-tuple, legacy 2-tuple 정규화 |
| Artificial chunking | test_text_chunking (8) — 문장·단어·하드 경계 / 한국어 / invariant ("".join(chunks)==text) |
| Pending A2A stub tool | test_pending_a2a_stub_tool (8) — 결정적 unavailable 메시지 · recompute_container_tools 통합 |
| Router 순서 · Stream safety gate | test_router_order (1) · test_stream_safety_gate_auto (3) — source invariant + marker / RuntimeAdapter gate |