v0.4.0

릴리스이전 버전

v0.4.0은 orchestrator가 child 결과의 schema와 capability를 읽어 다음 단계를 고르고, 명시적으로 설정한 AgenticProgram 안에서 bounded tool loop를 실행할 수 있게 한 릴리스입니다. Direct·Rules·Adaptive·Hybrid recipe와 code-first run_turn은 그대로 유지됩니다.

Breaking 없음 — 기존 agent/flow/orchestrator 프로젝트는 그대로 동작합니다. AgenticProgram, 경계 가드레일, human review, WorkMemory는 코드나 orchestrator.toml에서 명시적으로 설정할 때만 적용됩니다.

핵심 변경

동적 워크플로우 — child 결과의 schema, 응답 계약, capability catalog로 다음 child를 고릅니다.
응답 계약 — okf/contract__*.md에 facts, 공개 필드, WorkHistory 요약, 축약 정책을 둡니다.
OKF CLI — llamon okf contract draft/preview로 계약을 만들고, llamon okf route validate/preview로 다음 child 입력을 확인합니다.
Routing rule — okf/routing_rule__*.md에 schema/facts 기반 분기를 선언하고 run_turn에서 적용합니다.
Hybrid·AgenticProgram — 구조적으로 확정된 첫 child는 규칙으로 고정하고, 의미 판단이 필요한 범위만 controller·tool 호출 상한이 있는 loop에 맡깁니다.
Agentic 결과 전이 — read-only 도구의 exact-schema DataPart를 순서 있는 result_transitions로 판정해 complete 또는 continue를 선택합니다. 일치하지 않으면 기존 controller 흐름을 유지합니다.
입력·출력 가드레일 — Registry ID 또는 기존 guardrail Agent를 경계에 설정하며, block·mask·data/text 정책과 typed domain error를 유지합니다.
Human review — HumanReviewPort가 인증된 담당자의 검수 대기·결정을 durable checkpoint와 A2A input_required 재개에 연결합니다. Side-effecting 도구의 사용자 승인은 별도의 구조화 checkpoint로 처리합니다.
트랜잭션 WorkMemory — provisional·committed·quarantine 상태와 실행 소유권을 분리하고, 응답·checkpoint·기억을 같은 커밋 경계에서 확정합니다.
Capability와 discovery — .set_capability_metadata(...), okf/capability__*.md, DiscoveryPolicy를 같은 catalog로 묶습니다.
계획 실행 — plan_steps()와 run_plan()이 allowed alias 안에서 짧은 선형 plan을 검증하고 실행합니다.
스트리밍 — ctx.call_stream()이 child 텍스트 청크를 부모 message/stream으로 전달합니다.
Child 연결 장애 처리 — raw 연결 오류 대신 result.is_unavailable로 분기할 수 있는 결과를 돌려줍니다.
Outcome evaluator scaffold — outcome-evaluator가 VerificationEvaluatorAdapter로 ORCH verification 요청과 판정을 fail-closed로 검증합니다. Prompt seed 재생성과 drift 검사 절차도 함께 제공합니다.
Runtime Evaluator Framework v1 — Agent 최종 응답, Flow node, Orchestrator 최종 응답에 OutputReadyEvaluator·RubricEvaluator·GroundednessEvaluator와 @evaluator 함수를 같은 계약으로 연결하고 Numeric score를 자동 기록합니다.
Evaluator DX — Studio가 app.evaluation named ref와 timeout을 왕복하며, Agent·Flow·Orchestrator scaffold는 observability·rubric-judge·groundedness starter를 evaluators=[...]로 생성합니다.
스캐폴드 DX — llamon scaffold list와 Studio가 Agent 8종·Flow 4종(Registry/local)·Orchestrator 2종을 같은 카탈로그에서 읽습니다. Studio는 preview/readiness가 있는 새 프로젝트 Wizard와 recipe gallery를 제공하고, 생성된 Orchestrator는 code-first read-only 요약으로 엽니다.

동작 기준

동적 워크플로우는 새 agent를 즉석에서 생성하는 기능이 아닙니다. 이미 설정한 child나 registry에서 정책으로 발견한 child 중 다음 호출 대상을 고르는 방식입니다.

반복되는 분기는 okf/routing_rule__*.md에 둘 수 있습니다. 규칙으로 고르기 어렵다면 plan_next()나 plan_steps()를 보조로 씁니다. planner는 allowed_aliases 밖으로 나갈 수 없고, run_plan()은 실행 전에 alias와 schema 호환성을 다시 확인합니다.

Adaptive preview의 LogicalPlan/BoundPlan v1은 재개 가능한 완전한 선형 체인만 받습니다. 첫 step은 input_from="request", 이후 step은 바로 앞 step의 ID를 사용합니다. 최초 요청을 여러 step이 다시 참조하면 input_required 뒤의 보충 turn과 의미가 섞일 수 있기 때문입니다. 기존 code-first run_turn과 plan_steps()/run_plan()에는 이 제한을 추가하지 않습니다. 최초 요청 fan-out은 향후 plan IR v2에서 initial_request와 resume_input을 별도 source로 나누고, bounded durable artifact를 도입하는 방향으로 확장합니다.

AgenticProgram의 result_transitions는 response_data_schema가 있는 read-only 도구에만 선택적으로 적용됩니다. 각 전이는 child가 schema를 직접 반환한 exact-schema DataPart 하나 안에서 조건을 평가하며, 부모의 schema fallback은 자동 완료 근거로 쓰지 않습니다. 이후 선언 순서상 첫 일치만 사용합니다. complete는 non-empty TextPart를 최종화 초안으로 넘기고, continue와 미일치는 controller를 계속 실행합니다. 기존 completion·completion_when은 하위 호환 설정으로 남지만 같은 도구에서 새 전이와 섞을 수 없습니다. fixed-first와 side-effecting 도구, WorkMemory, HumanReviewPort, output guardrail의 동작은 바뀌지 않습니다. input_required 재개 시에는 schema와 HumanReview 경계까지 포함한 전이 정책 digest가 같을 때만 자동 완료하며, drift가 있으면 이미 실행한 child 결과를 controller가 다시 판단합니다. BoundPlan v1은 계속 선형이고, 향후 조건부 plan IR은 이 전이 조건 모델을 재사용할 수 있습니다.

자세한 패턴은 동적 워크플로우에 정리했습니다.

child는 기존 DataPart에 "schema": "invoice.ocr.v1" 같은 schema 이름을 함께 담습니다. 별도 schema 전용 DataPart를 추가하지 않습니다.

{
  "schema": "invoice.ocr.v1",
  "confidence": 0.92,
  "docType": "invoice",
  "fileId": "file_123"
}

ExtensionConfig.output_schema는 기본값을 첫 DataPart에만 붙입니다. text/file part는 바꾸지 않고, DataPart에 이미 schema가 있으면 덮어쓰지 않습니다. 새 flow scaffold는 같은 FLOW_OUTPUT_SCHEMA를 서버 fallback과 with_output_schema(...)에 함께 쓰고, 새 orchestrator scaffold는 build_orchestrator_app(extension=build_extension())로 boundary 메타를 받습니다. structured agent는 payload_schema_name을 사용합니다. .set_capability_metadata(...)는 discovery/catalog용 선언이며 응답 payload를 수정하지 않습니다.

오케스트레이터는 okf/contract__*.md를 보고 필요한 facts만 뽑습니다. confidence, docType, fileId는 오케스트레이터가 만든 필드가 아니라 child 응답의 필드입니다.

fields:
  - key: confidence
    public: true
  - key: docType
    public: true
  - key: fileId
    public: true
compact:
  drop_key_fragments: [ocr, raw, fulltext, pages, blocks, lines, tokens]

drop_key_fragments는 WorkHistory에 저장할 때 큰 OCR 원문·debug·trace 계열 key를 줄이는 안전장치입니다. key를 소문자화하고 _를 제거한 뒤 포함 여부로 판단합니다. 클라이언트로 나가는 응답은 줄이지 않습니다.

계약 작성법과 CLI 초안 생성은 응답 계약, 저장 규칙은 상태·기억·재개를 보세요.

새 child라면 코드에 .set_capability_metadata(...)를 먼저 넣고, Studio AI와 orchestrator가 읽을 짧은 OKF를 okf/에 함께 둡니다.

agent repo/
  okf/
    capability__invoice-ocr.md
    contract__invoice-ocr-result.md

중앙 OKF 서버는 필수가 아닙니다. 운영에서 여러 orchestrator가 같은 지식을 써야 하면 배포 과정에서 OKF bundle이나 catalog 파일로 함께 넘기는 방식을 권장합니다.

Flow graph는 마지막 노드가 스트리밍 child를 호출하면 스트리밍 응답을 이어받을 수 있습니다. Orchestrator는 ctx.call_stream()을 써야 child 청크를 부모 스트림으로 내보냅니다.

ExtensionConfig.output_schema 자동 부착은 스트리밍을 막지 않습니다. 단, SchemaValidatedRuntimeAdapter는 Pydantic 검증을 위해 전체 JSON을 모은 뒤 단일 청크로 응답합니다. 토큰 스트리밍이 필요하면 일반 streaming agent나 StructuredOutputAgent 경로를 쓰세요.

새 스캐폴드

llamon orchestrator ...로 만든 새 프로젝트는 recipe 조립과 capability admission을 app/orchestrator.py 한 파일에서 시작합니다. orchestrator.toml [work_memory]를 켜면 routing/capability는 orchestrator가 소유하고 summary contract는 summary agent가 소유합니다.

새 스캐폴드는 run_turn 시작부에서 ctx.record_request()를 기본 호출하지 않습니다. build_orchestrator_app(auto_record_request=True)가 성공한 턴 끝에 user 입력을 안전하게 기록합니다. 원본 DataPart/FilePart를 그대로 state에 남겨야 하는 특수 앱만 ctx.record_request(...)를 직접 호출하세요.

마이그레이션

시나리오	작업
기존 agent/flow	수정 불필요. runtime 평가는 `evaluators=[...]`를 명시한 경로에만 적용
기존 orchestrator	수정 불필요. 동적 라우팅은 `run_turn`에 직접 추가
새 child 추가	`.set_capability_metadata(...)`를 먼저 넣고, 필요하면 `okf/capability__.md`와 `contract__.md`를 추가
큰 JSON 응답	샘플 응답으로 `llamon okf contract draft`를 실행한 뒤 공개 facts만 사람이 확인
반복 라우팅 분기	`okf/routing_rule__*.md`를 추가하고 `llamon okf route preview`로 적용 결과 확인
스트리밍 child 노출	`ctx.call()` 대신 `ctx.call_stream()` 사용
pending child 예외를 직접 처리하던 커스텀 앱	미등록·미배포 child의 pending 응답은 이제 `ChildUnresolvedError`를 던지지 않고 `result.is_unavailable` 결과로 돌아옵니다. `ctx.call`을 `try/except ChildUnresolvedError`로 감싸던 앱은 `if result.is_unavailable:` 분기로 바꾸세요. (`registry:<id>` 타깃 + resolver 미주입은 여전히 첫 호출에 예외.)

검증

ctx.call_stream(), response contract, routing rule, capability catalog, discovery, scaffold 생성 프로젝트를 회귀 테스트에 포함했습니다.