Upstream Parts 정책 (replace / append)

이 페이지는 create_server(upstream_parts_policy=...) 의 두 정책 (replace / append) 과 다른 옵션 (InputContracts, RuntimeAdapter) 과의 조합을 정리합니다.

기본 원칙

정책 위치: create_server(upstream_parts_policy=...) — 각 에이전트 서버가 자체 결정
기본값: "replace" (인자 생략 시 자동 적용)
활성화: "append" 명시 — upstream 누적 보존
AgentCard 비노출 — 서버 내부 정책, 클라이언트는 정책 설정을 추론 불가
중복 제거 없음 — 같은 dict 가 중복되어도 SDK 가 자동으로 거르지 않음

정책 비교

정책	current data 있을 때	current data 없을 때 (text only)
`replace` (기본)	current 만 응답 (upstream 제외)	data/files 없음 (upstream 제외)
`append`	current + upstream 둘 다 응답	upstream 그대로 통과

append 순서: current 가 먼저, upstream 이 나중. data[0] 는 항상 “이 에이전트가 생산한 결과” invariant 유지.

사용법

from llamon_agent.server import create_server

# 기본 (replace) — 인자 생략
app = await create_server(card=card, agent=graph)

# append — 누적 보존
app = await create_server(card=card, agent=graph, upstream_parts_policy="append")

CLI scaffold 가 생성한 main.py 의 주석 한 줄을 해제해도 활성화됩니다.

InputContracts 와의 직교성

입력 선별 (InputContracts) 과 응답 구성 (upstream_parts_policy) 은 독립 축입니다. 입력 단계와 응답 단계를 따로 보면 4 조합 모두 명확합니다.

입력 선별	응답 정책	agent 가 사용하는 입력	응답 `data` 배열
없음	`replace`	upstream 전체 (raw)	`[자기 결과]`
없음	`append`	upstream 전체 (raw)	`[자기 결과, ...upstream 전체]`
선언	`replace`	`InputContracts` 가 선별한 payload	`[자기 결과]`
선언	`append`	`InputContracts` 가 선별한 payload	`[자기 결과, ...upstream 전체]`

중요: append 정책은 원본 upstream 전체 를 응답에 누적합니다 — InputContracts 가 선별한 일부가 아니라 raw upstream 그대로. InputContracts 는 agent 가 입력으로 쓸 것을 고르는 도구이고, append 는 응답에 무엇을 보존할지 결정하는 별개 옵션입니다.

선별 자체는 입력 선별 (InputContracts) 참고.

RuntimeAdapter 경로 제약 (옵션 B)

RuntimeAdapter 서브클래스를 사용하는 경우 본 정책은 적용되지 않습니다. _should_preserve_upstream() 게이트가 분기 진입을 차단하기 때문입니다. RuntimeAdapter 사용자는 postprocess() 안에서 직접 병합하거나, LangGraphAgent 직접 사용으로 전환해 SDK 정책으로 마이그레이션할 수 있습니다.

워크플로우 중복 누적 주의

Edge Cases

케이스	동작
upstream 모두 비어있음	early return (오버헤드 0)
current 비어있음 (text only) + upstream 있음	`replace` 는 data/files 없음, `append` 는 upstream 통과
잘못된 정책 값	`create_server()` 진입부에서 `ValueError`
HITL 경로 (`invoke_with_hitl`)	정책 영향 없음 (현행 유지)