v0.3.1

릴리스이전 버전

Breaking 없음 — 기존 agent/flow/orchestrator 프로젝트의 기본 동작은 그대로입니다. A2A 입력 파트 전달은 명시적으로 켠 자식 에이전트에만 적용되고, Studio AI OKF 변경은 llamon studio의 개발 보조 경로에만 영향을 줍니다.

변경 범위

한눈에 보기

Studio AI OKF 검색 안정화 — SDK 내장 OKF bundle과 프로젝트 okf/ wiki를 함께 읽고, 검색 결과·관계 문서·실제 파일 snippet을 예산 안에서 묶어 Studio AI 프롬프트에 넣습니다.
OKF Search Profile drop-in 호환 — OKF 표준 필드(resource, tags 등)와 LLaMON 선택 필드(query_examples, negative_queries, aliases, symbols, key_files)를 검색 가능한 지식 카드로 해석합니다. 기존 OKF 문서와 외부 okf-bundle/은 수정 없이 계속 소비됩니다.
프로젝트 wiki 갱신 흐름 정리 — knowledge/status와 knowledge/refresh가 coverage, stale 파일, 미문서화 파일을 구분하고, okf/*.md 제안은 preview와 서버 진단을 지난 뒤에만 저장됩니다.
OKF directory coverage 수정 — key_files: app/처럼 디렉터리를 가리키는 concept가 하위 파일을 덮도록 처리합니다. 이미 문서화한 디렉터리가 unindexed로 다시 잡히던 문제를 고쳤습니다.
Live scan과 prompt cap 보강 — 큰 프로젝트에서도 Studio AI가 실제 파일 근거를 무제한으로 프롬프트에 싣지 않도록 후보 파일, 본문 window, 최종 prompt 길이를 서버에서 제한합니다.
인프라 프로필 CLI — llamon profile list로 적용 가능한 프로필을 확인하고, llamon profile apply로 wheelhouse/package 재생성 없이 환경별 값을 다시 주입합니다.
A2A 입력 파트 전달 정책 — 부모가 받은 DataPart/FilePart를 하위 A2A 에이전트에 넘길지 AgentConfig에서 자식별로 정합니다. 기본값은 계속 never입니다.
Orchestrator DataPart 멀티턴 헬퍼 — ctx.fold_data()와 attachment 판정·key·merge·compact 헬퍼를 추가했습니다. 기존 동작은 바뀌지 않고, 필요한 워크플로우에서만 opt-in으로 씁니다.
Portable Reasoning 설정 확장 — v0.3.0의 on/off·effort에 더해 budget_tokens·summary를 추가하고, bool·문자열·dict·Reasoning(...) 네 입력 형태를 모두 동일하게 정규화합니다. reasoning=False 같은 단축 표기가 이제 정적 타입 체커에서도 오류가 없습니다.
응답 조립 헬퍼 — llamon_agent.response에 markdown_table()·data_response()·MarkdownTableColumn을 추가했습니다. 별도 서버·DB 없이 Markdown 표와 DataPart를 함께 담은 RuntimeOutput을 만듭니다.
Registry event consumer 상태 노출 — 에이전트 서버 status 응답에 Kafka registry consumer의 enabled·configured·running·assigned_partitions 등 상태가 포함됩니다.

개발자가 직접 보게 되는 변경

Studio AI OKF — wiki 기반 맥락 검색

Studio AI가 고정 파일 대신 OKF 문서(SDK 내장 bundle + 프로젝트 okf/)를 규칙 기반으로 검색해 맥락을 조립합니다.

검색·보강 — 근거가 약할 때만 모델을 1회 호출해 검색어를 확장하고(최대 3개), 관련 문서 한 단계·실제 파일 snippet·conceptDigest[]로 맥락을 더합니다.
Search Profile — query_examples는 강한 검색 근거로 쓰고, negative_queries는 비슷하지만 다른 요청이 ready로 승격되는 것을 막습니다. resource와 tags만 있는 upstream 스타일 OKF 문서도 검색됩니다.
새 응답 metadata — optional context.retrieval(confidence·actionability·topHit·suggestedQuestions)이 추가됩니다. 기존 클라이언트는 무시해도 됩니다.
단계적 edit 판단 — 근거가 약하면 prompt에 edits=[] 안전 지시를 더하고, 후보를 전혀 못 좁히면 코드 생성 없이 edits: []로 추가 정보(기능명·에러·파일명)를 요청합니다. 신규 API/비즈니스 로직처럼 OKF에 아직 없는 요구사항도 현재 프로젝트 구현 파일이 확인되면 needs_review로 코드 제안 모델을 호출합니다. 이 경로는 명시 contextBudget이 없을 때 자동 compact budget을 써서 prompt를 줄이고, Studio 로그에 budget=auto-compact와 timeout_s를 남깁니다.
서버 예산 제어 — provider truncation 대신 서버가 final prompt(기본 48k chars) 등을 제한하며, contextBudget으로 capacity 안에서 상향할 수 있습니다.

검색·점수·관계 확장·예산의 전체 동작은 Studio AI와 OKF 지식에 정리되어 있습니다.

Project wiki 갱신과 진단

Studio AI는 프로젝트 지식을 바로 저장하지 않습니다. 먼저 어떤 파일이 이미 문서화됐는지, 어떤 문서가 stale인지, 아직 wiki에 잡히지 않은 파일이 무엇인지 계산합니다. 사용자가 파일을 고르면 okf/*.md 갱신안을 만들고, preview·diagnostics·체크섬 검증을 통과한 edit만 저장합니다.

OKF edit에는 서버 진단이 붙습니다. taxonomy 밖 type, 필수 metadata 누락, 존재하지 않는 key_files, secret 파일 참조, unquoted #, okf/README.md, 자기 자신만 링크하는 concept, 과도한 aliases/symbols/query_examples/negative_queries를 저장 전에 막습니다.

.env 계열 파일은 safe key만 수정할 수 있습니다. LOG_LEVEL, PORT, UVICORN_LOG_LEVEL 같은 운영 safe key는 기존 주석과 key 순서를 보존하며 병합하고, secret/unknown key 값은 프롬프트에 <redacted>로만 들어갑니다. 모델이 proposal에 allowSecret을 넣어도 승인으로 보지 않습니다.

proposal에는 선택 metadata인 evidence ledger를 둘 수 있습니다. 형태는 {path, okfDocIds, liveFiles, reasons}로 제한되며, 설명용 metadata일 뿐 diagnostics, secret guard, checksum 검증을 우회하지 못합니다.

.llamon/studio-ai-knowledge.json은 검색 cache가 아닙니다. OKF concept가 어떤 프로젝트 파일을 덮는지와 파일 fingerprint만 저장합니다. 파일이 바뀌면 knowledge/status가 해당 concept를 stale로 표시합니다.

OKF coverage와 live file scan 수정

이 항목은 프로젝트 루트의 okf/ wiki에 적는 key_files에 관한 변경입니다. SDK wheel에 들어 있는 읽기 전용 OKF bundle의 key_files는 검색 근거 메타데이터로만 쓰이고, 에이전트 프로젝트 안에서 SDK 소스 트리를 찾으려 하지 않습니다.

프로젝트 wiki의 key_files가 디렉터리를 가리키는 경우를 실제 coverage로 인정합니다.

key_files:
  - app/

위처럼 작성한 concept는 해당 에이전트 프로젝트의 app/ 아래 파일을 덮습니다. 그래서 Studio AI가 이미 문서화된 파일을 미문서화 파일로 다시 제안하지 않습니다.

Live file context도 더 보수적으로 잘립니다. Studio AI는 프로젝트 루트 아래의 허용된 파일만 읽고, .venv, .git, .llamon, node_modules, dist, wheelhouse, secret .env 파일은 제외합니다. 사용자가 직접 언급한 path, 프로젝트 wiki의 key_files, 검색어 확장 힌트의 path를 우선 후보로 삼고, 전체 프롬프트 예산을 넘기기 전에 snippet을 줄입니다.

인프라 프로필 CLI — `profile list/apply`

오프라인 인프라 프로필을 조회하고, 값만 다시 적용하는 명령을 분리했습니다.

uv run llamon profile list ./my-agent
uv run llamon profile apply ./my-agent --profile stage
uv run llamon profile apply ./my-agent --profile prod --dry-run

profile apply는 prepare-offline의 프로필 선택·검증·env 추적을 재사용하지만, vendor-deps와 package는 실행하지 않습니다. 이미 wheelhouse/와 dist/*.tar.gz가 있고 Dockerfile·pyproject·런타임 env만 환경별 값으로 바꾸면 될 때 사용하세요.

프로필 선택 키는 파일명이 아니라 .llamon/profiles/*.toml 최상단의 name입니다. 예를 들어 .llamon/profiles/local-dev.toml에 name = "dev"라고 쓰면 --profile dev로 선택합니다.

적용 중 pyproject.toml 패치나 런타임 env 갱신이 실패하면 Dockerfile과 env 변경을 되돌리고, .llamon/offline.json의 profile/base image metadata도 새 값으로 남기지 않습니다. metadata는 모든 파일 적용이 끝난 뒤에만 기록됩니다.

A2A inbound DataPart/FilePart 전달 정책

ExtensionConfig.agent[]에 등록한 하위 에이전트가 부모의 inbound DataPart/FilePart를 받을지 자식별로 정할 수 있습니다.

from llamon_agent import AgentConfig, ExtensionConfig


ExtensionConfig(
    agent=[
        AgentConfig(
            id="document-worker",
            forward_inbound_data="allowed",
            forward_inbound_files="allowed",
        ),
    ],
)

값	동작
`never`	전달하지 않습니다. 기본값이며 기존 배포와 같습니다.
`always`	해당 자식이 선택되면 inbound `DataPart`/`FilePart`를 전달합니다.
`allowed`	LLM 기반 A2A 라우팅 또는 ReAct A2A tool-call이 그 자식을 고른 경우에만 전달합니다.

휴리스틱 pre-router가 고른 자식에게도 항상 넘겨야 하면 always를 쓰세요. allowed는 LLM이 선택한 호출에 한해 전달하도록 좁힌 정책입니다.

Flow 노드에서 직접 하위 에이전트를 부르는 경우는 기존 call_agent_auto 옵션을 그대로 씁니다.

await call_agent_auto(
    agent_url,
    query,
    state=state,
    forward_inbound_data=True,
    forward_inbound_files=True,
)

하위 에이전트의 응답에 DataPart/FilePart가 있으면 부모 런타임 출력의 output_data/output_files에 보존됩니다. 후속 노드나 최종 adapter가 구조화 결과와 파일을 그대로 이어받을 수 있습니다.

Orchestrator DataPart 멀티턴 헬퍼

ctx.fold_data(...)를 추가했습니다. 직전 user 입력 DataPart 중 필요한 항목과 이번 ctx.data를 병합해 자식 호출의 data=에 바로 넘깁니다. 기본 정책은 첨부 참조처럼 보이는 DataPart(fileSessionId, sessionId, session_id, non-empty files)만 승계하고, 현재 입력은 항상 포함합니다.

공통 헬퍼도 함께 제공합니다. is_attachment_data()와 attachment_data_key()로 첨부형 DataPart를 판정하고, merge_data_parts()로 later-wins 병합을 수행합니다. OCR 원문이나 debug 페이로드를 다음 턴 상태에 그대로 남기지 않으려면 compact_data_part()/compact_data_parts() 또는 compact_agent_result()로 줄입니다.

반복 DataPart 후속 질문 분기를 위한 ctx.has_new_data()/current_data_has_new_parts(), 직전 결과에서 재사용할 재료를 정리하는 extract_prior_work(), 빈 응답이나 일반 처리 문구를 보정하는 with_fallback_text(), decider 결과 검증용 validated_decider_label()도 옵트인 헬퍼로 추가했습니다. extract_prior_work() 결과는 그대로 공개하기보다 앱의 응답 입력·공개 DataPart 스키마로 다시 매핑하는 흐름을 권장합니다. resume 복귀가 끝난 뒤 체크포인트를 비우는 ctx.clear_resume()도 추가했습니다.

모두 결정적 헬퍼이며 LLM을 호출하지 않습니다. 기존 agent/flow/orchestrator의 입출력 형태는 그대로이고, 워크플로우 코드에서 명시적으로 호출할 때만 적용됩니다.

Portable `Reasoning` 설정 확장

v0.3.0의 reasoning=False(on/off)·reasoning="low"(effort)에 이어, 추론 강도와 예산을 더 세밀하게 표현할 수 있도록 Reasoning 설정을 확장했습니다. from llamon_agent.config import Reasoning로 가져옵니다.

effort: minimal·low·medium·high·xhigh·max
budget_tokens: 추론에 허용할 토큰 예산(≥ 1). 응답 max_tokens와 별개입니다.
summary: 추론 요약 노출 방식(auto·concise·detailed·none).

입력은 bool·effort 문자열·dict·Reasoning(...) 객체를 모두 받아 동일한 설정으로 정규화하며, 저장값과 직렬화 결과는 입력 형태와 무관하게 같습니다. 단축 표기(reasoning=False·"low"·{...})는 이제 정적 타입 체커(Pyright·mypy)에서도 오류 없이 통과합니다.

from llamon_agent.config import Reasoning

LLMConfig(id="<MODEL_ID>", reasoning=False)                              # 끄기
LLMConfig(id="<MODEL_ID>", reasoning="high")                             # effort
LLMConfig(id="<MODEL_ID>", reasoning={"effort": "high", "summary": "auto"})
LLMConfig(id="<MODEL_ID>", reasoning=Reasoning(budget_tokens=2048))      # 추론 예산

enable_thinking·reasoning_effort·extra_body는 입력 전용 legacy alias로 계속 받습니다. 입력 형태·필드·provider별 변환은 에이전트 구성 — reasoning과 트러블슈팅 — reasoning 모드 제어에 정리되어 있습니다.

응답 조립 헬퍼 — `llamon_agent.response`

여러 에이전트에서 반복되던 Markdown 표 생성과 RuntimeOutput 포장을 줄이는 self-contained 유틸리티를 추가했습니다. 별도 서버·DB·spec registry 없이 에이전트 코드 안에서 최종 응답을 조립합니다.

markdown_table(rows, columns=...) — dict row 목록을 Markdown 표로 렌더링합니다. column별 label·format(text·number·money·date_ymd·join)·align을 한 곳에서 선언합니다.
data_response(text=..., data=..., artifact_name=...) — 사람이 읽는 output_text와 기계가 읽는 DataPart를 함께 담은 RuntimeOutput을 반환합니다.
MarkdownTableColumn — column 선언용 dataclass(dict로도 가능).

from llamon_agent import MarkdownTableColumn, data_response, markdown_table

data_response()가 돌려주는 RuntimeOutput은 기존 계약 그대로라 RuntimeAdapter.postprocess()나 graph node에서 바로 사용할 수 있습니다. 자세한 사용법은 런타임 API의 응답 조립을 참고하세요.

Registry event consumer 상태 노출

Kafka registry event consumer가 status_summary()로 자기 상태를 보고하고, 에이전트 서버의 status 응답에 registry_event_consumer 블록으로 포함됩니다. enabled·configured·running·assigned_partitions·topics·마지막 오류 등을 담아, 브로커/토픽 미설정(missing_brokers_or_topics)이나 consumer 정지 상태를 운영 단계에서 바로 확인할 수 있습니다. consumer를 끈 배포에서는 {"enabled": false, ...}로만 보고되며 기존 동작은 그대로입니다.

검증

Studio AI OKF wiki 검색·갱신 lifecycle 단위 테스트 추가
OKF Search Profile(query_examples, negative_queries, resource, multi-value metadata) 회귀 테스트 추가
OKF directory coverage와 live scan cap 회귀 테스트 추가
A2A call node integration, A2A tool forwarding, config validation 테스트 추가
orchestrator fold_data·DataPart compact/merge·resume clear 테스트 추가
portable Reasoning 정규화·shorthand 타입 안전·provider별 컴파일 단위 테스트 추가
응답 헬퍼(markdown_table/data_response) 단위 테스트 추가
registry event consumer status_summary·서버 status 응답 테스트 추가