# 에이전트 런타임과 모델 경계 ARTEX는 범용 Norma session을 그대로 노출하지 않고 역할별 system prompt, tool set, transcript, context/settlement, proxy와 writeback callback을 조립한다. 모델은 다음 행동과 가설을 선택하지만 task state transition, DB transaction, asset gate, runtime budget 같은 경계는 host 코드가 담당한다. ## 역할과 책임 | 역할 | trigger·입력 | 허용된 결정 | 영속 결과 | |---|---|---|---| | Goal decomposer | 새 task의 raw goal·source context | goals, constraints, task scope 초기화 | graph goal/constraint/scope | | Planner | graph overview, trigger delta, persistent Todo | intent 추가, goal proof, running work steer/kill | intent/goal/graph activity | | Worker | 하나의 intent, anchor assets, constraints, task deadline | tool을 반복 선택하고 asset/fact/finding writeback | activity, transcript, graph/assets/findings | | Main Agent | 사람 메시지와 task context | goal/hint/intent/constraint/scope 변경, work 제어 | main session/activity + task state | | Reporter | finding event/trace/evidence | Markdown report 작성/갱신 | finding report/version | | Retester | 사람이 시작한 finding retest | 제한된 재검증 후 verdict/summary/evidence | retest row + conversation | | Triggered custom agent | interval/finding/tool/task-create event | 구성 prompt와 binding tool 범위 내 행동 | conversation/activity/tool effects | | Side-question agent | parent context snapshot + 질문 | 별도 답·도구 사용 | side request/memory/events | 역할은 같은 provider/profile을 사용할 수 있지만 tool binding, prompt, runtime, transcript/session id와 writeback callback이 다르다. [Runtime 조립](evidence:assembly-agent) ## Planner session Planner는 wake-up마다 새 Norma session을 만들되 task/exploration별 TodoStore를 ARTEX memory에서 재사용하고 transcript가 있으면 session을 resume한다. graph overview는 최근/진행중/냉각 요약을 제한된 창으로 제공하며, trigger delta가 이번 변화에 주의를 돌린다. [Planner](evidence:planner) Planner 전용 tool은 goal proof, intent creation, graph/asset/finding query, work output/steer/kill 등이다. `add_intent` handler는 parent가 fact/finding인지 검사하고 top-level이면 origin fact에 연결하며 asset anchor를 gate한다. 따라서 모델의 자유로운 계획과 graph lineage 불변조건을 분리한다. [Tool handler](evidence:agent-tools) ## Worker session Worker는 intent별 work directory와 session id를 만들고 task deadline으로 wall-clock budget을 clamp한다. system prompt 끝에 task constraint, intent JSON, anchor asset JSON, graph context와 “이 intent만 수행하고 결과를 writeback한 뒤 멈춤” 규칙을 넣는다. [Worker](evidence:worker) ```mermaid sequenceDiagram participant E as Engine participant W as ARTEX Worker participant N as Norma Session participant T as Tools/Hooks participant D as DB/Files E->>W: claimed intent + deadline W->>W: role config·proxy·workdir·context 조립 W->>N: Resume(session id) loop model/tool turns N->>T: tool call T->>T: permission/intercept/asset gate T->>D: 실행·writeback D-->>T: result/evidence id T-->>N: tool result end N-->>W: terminal reason + usage W->>D: activity/result 상태 W-->>E: done/finding wake ``` Session의 자연어 최종 답보다 structured write counts와 graph/finding/tool activity가 planner와 UI에 더 강한 입력이다. 모델이 결과를 말만 하고 write tool을 호출하지 않으면 탐색 상태에는 반영되지 않는다. ## Norma 외부 경계 ARTEX에서 확인한 것은 `agentcore.Options`와 session lifecycle이다. | ARTEX가 설정 | Norma가 내부에서 수행 | ARTEX가 다시 수집 | |---|---|---| | provider/model/system prompt | model turn·tool-use loop | thinking/text/tool_use/tool_result/result event | | tools/deferred tools/unlock set | schema 노출·tool dispatch | capture callback과 activity | | permission mode/hook context | permission/hook 실행 순서 | approval metadata/terminal error | | transcript/session id | message resume/persist | 다음 ARTEX run의 resume | | compaction/Noa/settlement | context budget·마지막 정리 turn | terminal reason, summary, usage | | web fetch/search/proxy/bash env | SDK tool 실행 | tool result와 proxy에 잡힌 traffic | 한 model turn 안의 정확한 retry, streaming parse, permission 구현, transcript serialization은 ARTEX 소스만으로 확정하지 않는다. 같은 저장소에 생성되는 Norma 문서는 별도 문서 bundle이므로 이 ARTEX bundle의 내부 링크로 취급하지 않는다. [Event capture](evidence:capture) ## Provider routing과 failover Provider adapter는 Anthropic/OpenAI compatible endpoint와 env fallback을 조립한다. PostgreSQL `llm_profiles`, task별 ordered chain, agent별 profile binding, conversation binding과 active profile을 task runtime이 해석한다. profile health/pool 상태와 quota failure는 다음 profile 전환 및 blocked intent 재개에 사용된다. [Provider](evidence:provider) [Task LLM](evidence:task-llm) | 설정 | 적용 시점 | 경계 | |---|---|---| | endpoint/key/model/format | profile/provider 생성 | 연결 성공과 모델 의미 품질은 별개 | | streaming/non-streaming | session별 resolver | response mode가 tool semantics를 바꾸지는 않음 | | max tokens/custom field | request 구성 | endpoint 지원/해석은 외부 계약 | | retry connect/empty/stream | provider policy | 비멱등 tool은 model retry와 분리 | | session header | context session id가 있을 때 transport에 주입 | goal/compactor도 별도 stable id를 설정 | | task profile chain | task router | quota/health 전환 시 active profile/revision 변경 | ## Tool, MCP, Skill 조립 ARTEX는 역할 base tools에 visible Skill registry, direct-visible 또는 skill-gated MCP, traffic/custom host tools를 합친 뒤 DB `tools` row의 enabled/binding/schema override/default를 적용한다. deferred MCP/custom tool은 schema를 초기 prompt에서 숨기고 Skill 또는 search 경로로 unlock한다. 자세한 결정 순서는 [도구와 정책](tool-policy.md#assembly)을 본다. [Server assembly](evidence:assembly-server) ## Context와 장기 상태 | 층 | 보존 범위 | 소실/왜곡 가능성 | |---|---|---| | PostgreSQL graph | task 수명과 archive 범위 | payload summary 자체가 모델 write | | activity | tool/text/result/usage cursor | append 실패·보존/삭제 경계 | | transcript files | 역할/session id별 raw conversation | archive/restore와 file 일관성 필요 | | Planner TodoStore | server process의 task planner | process restart 시 DB graph보다 약함 | | built-in compaction | session context window | summary가 원 turn을 완전히 대체하지 않음 | | cold graph digest | settled graph branch 요약 | hot/cold 선정·model digest 품질 | | experimental Noa | 별도 persistent archive/context | 설정에 따라 built-in path와 다름 | | side-question memory | parent key별 PostgreSQL JSON | parent snapshot 이후 변화 | Cold compactor는 planner round에서 graph의 live branch를 제외하고 안정된 cold group을 digest로 접는다. signature/content version/round stamp로 반복 압축을 제어한다. 이것은 storage node 삭제와 같은 의미가 아니며 원 graph와 digest의 사용 경계를 확인해야 한다. [Compactor](evidence:compaction) [Noa](evidence:noa) ## 주 탐색 밖의 보조 루프 - Reporter와 retest는 finding을 중심으로 별도 session을 열며 primary worker transcript를 그대로 이어가는 구조가 아니다. - Scheduler는 interval trigger를 선택하고 agent run을 제출한다. - Notifier는 DB delivery를 lease/retry/digest하며 model agent가 아니다. - Enrichment는 DNS/HTTP 규칙 기반 worker pool이며 model reasoning을 쓰지 않는다. 이 snapshot에서는 engine 조립까지만 되고 실제 `ResolveDomain`/`ProbeSite` 호출 경로가 연결되지 않았다. - Side-question은 parent context를 bounded snapshot으로 구성하는 별도 session이다. 이 loop들의 완료·재시도·보존은 [저장·서비스 모듈](storage-runtime.md#background-loops)과 [운영](../operations.md#observability)에 연결한다. ## Runtime 실패를 해석하는 기준 - provider failover가 성공해도 이전 profile이 어떤 tool call 직전/후 실패했는지 activity와 함께 본다. - context compaction 성공은 security-relevant 세부가 보존됐다는 자동 증거가 아니다. - permission bypass mode는 ARTEX host의 Guard/asset gate가 모두 적용됐다는 뜻이 아니다. - resumed transcript와 persistent graph가 불일치하면 graph/DB를 업무 상태의 권위 원본으로 보고 transcript는 실행 맥락으로 해석한다. - tool result가 truncation되면 model이 원 출력 전체를 보지 못할 수 있으므로 artifact/output file과 structured writeback을 확인한다.