콘텐츠로 이동
LLaMON Agent SDK v0.6.0

v0.5.0

릴리스이전

이 페이지는 v0.5.0 릴리스 노트입니다. 최신 변경사항은 v0.6.0 릴리스 노트에서 확인하세요.

v0.5.0은 기존 llamon studio에 설계 | Playground 모드를 추가합니다. 별도 앱이나 직접 invoke 경로 없이 Agent·Flow·Orchestrator의 실제 A2A endpoint를 Host에서 실행하고, session·run·trace·비교·재현 bundle을 로컬에 관리합니다.

Breaking 없음 — Playground API를 사용하지 않으면 SQLite 디렉터리와 background task를 만들지 않습니다. 기존 /api/runtime JSON, Host start/stop/auto-reload, graph 문자열 ID·codegen, memory·checkpoint·guardrail·evaluator 설정은 그대로입니다. call_agent*()의 새 task_id를 생략하면 기존 wire payload에 taskId가 생기지 않습니다.

핵심 변경

섹션 제목: “핵심 변경”
  • Studio 3-pane Playground — session 이력, 대화·schema composer, Run/Trace/Compare inspector를 리사이즈 가능한 화면으로 제공합니다. 마지막 Studio 모드는 localStorage에 보존합니다.
  • server-owned run — 요청 수명과 분리된 background 실행, 프로젝트당 활성 run 한 건, durable 상태와 event sequence, SSE replay, 취소와 startup orphan 복구를 구현했습니다.
  • 실제 A2A 실행 — 일반 turn은 session contextId를 유지하고, HITL 재개는 저장한 server taskId까지 유지합니다. 격리 재실행은 같은 입력에 새 context를 사용합니다.
  • 저장·Host generation 조정 — checksum 저장의 실제 변경 파일을 기준으로 명시적 revision restart를 한 번 수행하고 새 generation Ready 뒤 전송합니다. 외부 watcher restart 중 활성 run은 재시도 없이 runtime_restarted로 끝납니다.
  • durable local history — .llamon/playground/playground.sqlite3와 content-addressed file store, forward migration·upgrade backup·newer schema 거부·blob dedup/GC를 표준 sqlite3로 제공합니다.
  • trace 격리 — Host child에만 일회성 capture token을 넣고 검증된 A2A envelope를 business metadata 전에 제거합니다. Playground가 아닐 때 TraceEvent/evaluator log는 기존과 같습니다.
  • schema composer와 소스 연결 — live Flow START node의 InputContracts skeleton, AgentCard schema-name 제안, skill example text fallback을 제공합니다. trace node는 live function_name과 AST 위치로 설계·CodeEditor에 연결합니다.
  • 비교·복사·bundle — text/JSON/file/status/duration/evaluator score를 자동 verdict 없이 비교하고, Python/curl projection과 llamon.playground.bundle/1 export/import를 제공합니다.
  • versioned API — Studio loopback에 /api/playground/v1을 추가했습니다. 기존 무버전 Studio API는 변경하지 않았습니다.
  • auto-reload 감시 범위 보강 — Host Run watcher가 [tool.llamon].env_file로 지정한 env 파일과 okf/·okf-contracts/ 아래 *.md도 감시합니다. 생성된 orchestrator는 capability catalog와 routing rule을 import 시점에 확정하므로 이 문서 변경은 재시작이 필요합니다. 그 밖의 *.md(README·docs)는 재시작 소음이라 제외합니다.
  • WorkMemory write-behind — Orchestrator의 timing="write_behind"는 summary Agent가 소유한 ResponseContractCache snapshot에서 model 호출 없이 만든 contract facts와 결정적 core summary를 child 직후 동기 저장하고, 응답 commit 뒤 고정 worker가 summary 문장만 선택적으로 개선합니다. Replica-exclusive claim lease와 validated-output write-back retry가 중복 LLM 호출과 attempt 오소진을 막습니다. facts·ID·slot·recency·lifecycle과 all·latest·relevant controller projection은 write-back 전후 동일하게 검증하며, worker startup·queue·LLM 실패는 core 응답을 막지 않습니다. 기존 세 timing은 metadata와 byte shape가 그대로입니다.
  • guarded Echo passthrough 하드닝 — EchoAdapter가 입력 DataPart·FilePart를 이미 반환하는 서버에서 출력 가드레일과 upstream_parts_policy="append"를 함께 사용해도 동일 upstream을 재첨부하지 않습니다. 기본 replace와 일반 current + upstream append 의미는 그대로이며, 중복 설정은 시작 로그로 확인할 수 있습니다.
  • OKF v0.2 안전 전환 — runtime loader는 v0.1 timestamp와 v0.2 provenance·trust·lifecycle·Attested Computation 메타데이터를 함께 읽고, 새 scaffold·contract draft·Studio AI 제안은 generated.by·generated.at만 씁니다. status와 trust tier는 관찰용이며 실행·권한 의미를 추가하지 않습니다. draft_contract_from_sample(timestamp=...)는 0.5.x deprecated alias로 유지됩니다.
  • 프롬프트 권한 분리와 provider cache — 기본 legacy_system은 기존 system binding·history 입력을 byte-identical하게 유지합니다. opt-in stable_tail은 SDK 소유 knowledge·recalled facts·summary만 비영속 runtime context로 옮기고, PromptCacheConfig는 확인된 Anthropic/OpenAI native capability에만 breakpoint·key·TTL을 전달합니다. cache read/write/miss는 provider usage로 계측하며 KnowledgeConfig(delivery="tool")은 고보안 agent용 실제 retrieval ToolMessage 경계를 제공합니다.
  • 평가 스위트(선택 설치) — llamon eval이 설치된 provider와 준비된 EvalSet을 조회하고, eval scaffold·eval prepare·eval run이 선언·데이터셋 준비·실행을 나눕니다. 실행 preset은 smoke·full·reliability이며 reliability는 대화 수와 비용을 확인하는 --yes를 요구합니다. provider는 llamon_agent.evaluation.suite.spi(SPI v1)만 import하는 신뢰 경계이며 core 런타임을 import하지 않습니다. Studio 진입은 entry point 옆에 패키징된 llamon_evaluation_provider.json manifest만 읽고 provider Python은 명시적 prepare/run/scaffold 시점에만 import합니다. 참조 구현은 별도 패키지 providers/tau3입니다. provider를 설치하지 않으면 CLI·Studio는 선택 기능 안내만 표시하고 기존 실행·배포에는 영향이 없습니다.
  • Studio 평가 탭 — evaluator 카탈로그·정책 편집·evaluator builder·suite 준비/실행을 한 화면에 모아 평가 설정의 단일 진입점으로 만들었습니다(설계 탭의 Runtime 평가 섹션 대체). evaluator만 바뀐 저장은 full codegen 대신 국소 patch 경로로 처리하며, 패처가 안전하게 고칠 수 없는 형태는 codegen으로 폴백하지 않고 evaluator_patch_failed로 저장을 거절합니다 — 사용자 graph.py 보존이 우선입니다.
  • hybrid 지식 검색 — KnowledgeConfig.retrieval(RetrievalConfig)로 검색 방식을 고릅니다. hybrid는 기존 weighted scorer에 BM25·구조·OKF 링크 채널을 RRF로 합치고, legacy는 0.4.x weighted lexical 검색·query expansion·점수 임계값을 그대로 보존하는 운영용 escape hatch입니다. 미선언(None)은 실행 시 hybrid로 해석합니다 — 기본값을 채우지 않는 것은 parse 결과와 Studio 기본값이 어긋나 codegen in-place 편집 경로가 포기되는 것을 막기 위함입니다.
  • MCP v2 drop-in — LLaMON이 쓰는 표면(연결 설정, paginated tool discovery, per-call session)만 SDK 안에 두는 client 경계를 추가했습니다. call session에 discovery 시점의 tool schema를 시드해 v2 헤더가 상태를 유지하며, 생성된 에이전트는 mcp나 외부 LangChain adapter를 직접 import하지 않고 기존 MCPHandle·MCPToolLoader를 그대로 씁니다.
  • Studio AI 에이전트 루프 접지 — 루프의 action을 provider native tool schema로 노출해 턴이 제안 강제 대신 clarification으로 끝날 수 있고, 세션의 turn 간 task grounding을 이어받아 되묻기 다음 응답이 기본 화면으로 무너지지 않습니다. compaction은 열린 항목을 자르지 않고 전사 항목 단위로 버리며 관찰이 사라진 경우 1회 재읽기를 허용하고, anchored replace edit으로 더 이상 보이지 않는 파일도 전면 재작성 없이 수정합니다. 스트리밍 응답은 디코드된 prose만 방출해 제안 파일 payload가 화면에 새지 않습니다.
  • LLM 성능 계측 — Generation에 duration_ms·ttft_ms·tpot_ms·token_usage_status를 기록합니다. token 수는 provider usage만 쓰고 누락값을 0이나 문자 수로 추정하지 않습니다 — 일부만 있으면 partial, 없으면 unavailable이며 없는 숫자 필드는 생략합니다. TTFT/TPOT는 실제 streaming callback과 provider output token이 확인된 경우에만 남기고 message/send는 timing_available=false와 non_stream 사유를 남깁니다. reasoning token은 TPOT 분모에서 제외하며, 측정 단위는 provider 내부 HTTP attempt가 아니라 call_scope=sdk_logical_call입니다. Playground Run inspector가 같은 수치를 표시합니다.
  • loop lifecycle 계측 — TraceEvent 4종(loop.iteration.start·loop.iteration.end·loop.snapshot·loop.summary)과 LoopTracker·bind_loop_tracker를 추가하고 Flow·ReAct·Agentic controller·Verification evaluator에 배선했습니다. 횟수는 iterations_started·completed·failed·cancelled·interrupted·in_flight로 분리하며 started = completed + failed + cancelled + interrupted + in_flight 불변식을 지킵니다. Agentic과 Verification은 업무 checkpoint와 분리된 sidecar ledger로 중단 재개 시 iteration·attempt 횟수를 정확히 복구하고, 복구할 수 없는 legacy·손상 sidecar에서는 추정하지 않고 count_status=unavailable과 원인을 남깁니다. 계측은 capability 기반이라 traced_invoke·build_config만 구현한 custom tracer와 TRACE_BACKEND=none no-op 계약이 그대로이고, loop 계측 실패는 본 실행을 막지 않습니다.
  • Langfuse 적재 정합화 — 구조화된 LLM trace payload를 잘라내지 않고 sanitize된 전체를 보존하며, provider usage의 상세 bucket(cache read/write·reasoning)을 중복 없이 정규화해 backend가 지원하는 kwargs만 전달합니다. message-level usage fallback도 유지해 provider가 response usage를 비우는 경우 수치가 사라지지 않습니다. 평가 스위트 실행은 격리된 trace lifecycle을 갖습니다.
  • 출력 가드레일 숫자 탐지·마스킹 정합 — 숫자 PII 패턴이 완전한 digit token만 매칭하도록 경계를 넣어 긴 소수(2.4127928614616394)를 주민등록번호·신용카드로 오탐하던 문제를 고쳤습니다. schema key나 비문자열 scalar라 안전한 mask를 투영할 수 없으면 탐지 결과를 조용히 통과시키지 않고 block으로 승격해 잔여 마스크와 정책 block 판정을 일치시킵니다.
  • Kafka consumer 복구 — consumer 재연결·재시도가 A2A serving을 막지 않습니다. 브로커 장애 동안에도 에이전트 HTTP 표면은 계속 응답합니다.

PostgreSQL과 개인정보

섹션 제목: “PostgreSQL과 개인정보”

PostgreSQL backend를 감지하면 진입 시점부터 외부 서비스 필요 경고를 표시합니다. Host 실패 시 SQLite/in-memory로 바꾸거나 DB를 초기화하지 않고 로그와 uv run llamon run .을 안내합니다.

실제 입출력과 trace는 프로젝트 로컬 SQLite에 저장됩니다. .env, capture token과 내부 metadata는 저장·export하지 않고 secret 형태의 사용자 metadata는 redaction합니다. 자유 형식 본문에는 개인정보가 남을 수 있으므로 bundle 공유 전 확인해야 합니다.

공개 API 변경

섹션 제목: “공개 API 변경”
await call_agent(url, query, context_id="conversation-1", task_id="task-1")
await call_agent_stream_result(
    url,
    query,
    context_id="conversation-1",
    task_id="task-1",
)

task_id는 세 A2A facade(call_agent, call_agent_stream_result, call_agent_stream)의 optional keyword-only 인자입니다. None이면 기존 Message 직렬화와 동일합니다.

추가된 공개 표면은 모두 additive입니다.

표면내용미사용 시
llamon_agent.observabilityLoopTracker, bind_loop_tracker, TraceEvent 4종(loop.*)기존 8 event 카테고리 schema 무변경
KnowledgeConfig.retrievalRetrievalConfig(mode="hybrid" | "legacy", embedding=…, reranker=…)미선언은 hybrid로 해석, legacy로 0.4.x 동작 고정
llamon_agent.evaluation.suite.spiprovider SPI v1 + llamon_evaluation_provider.json manifestprovider 미설치 시 안내만 표시
llamon evalscaffold · prepare · run 하위 명령기존 CLI 명령 무변경

사용법은 Studio Playground, HTTP 표면은 Playground API를 참고하세요.

제외 범위

섹션 제목: “제외 범위”

Docker/Kubernetes 격리 실행, 관리자 웹, 자동 pass/fail, replay CLI, GitLab·배포 API 변경은 v0.5.0에 포함하지 않습니다.