라이브러리·이벤트·파일·설정 계약

상위 경로: Norma 시스템 지도 → 계약과 설정

Norma에는 제공 HTTP/RPC 서비스나 물리 DB schema가 없다. 적용되는 독립 계약은 public Go library, provider 소비 interface, event/tool schema, local files, CLI와 환경변수다. 외부 model HTTP와 MCP JSON-RPC는 Norma가 소비하는 protocol이며 endpoint의 전체 vendor schema는 이 snapshot이 소유하지 않는다.

Public surface 분모

고정 source의 production(non-test) Go 파일만 Go AST로 독립 계수한 public candidate surface는 16 SDK packages, exported types 147개, functions 180개, exported receiver의 methods 92개, variables 3개, constants 120개, exported struct fields 573개, interface methods 24개다. test declarations는 분모에서 제외했다. 별도 실행 단위는 demo CLI 1개와 examples 5개다. 이름이 export됐다는 사실만으로 호환성을 약속한 stable API라고 확정하지는 않는다.

모든 식별자와 선언/signature는 package별 전수 색인에 있다: 실행 코어, 도구·권한, 컨텍스트·지속성, 확장·조정. 각 행은 선언 source evidence로 연결된다. exact defaults/override/failure는 설정 field 참조가 보완한다. DB 객체와 inbound HTTP/RPC operation은 0이며 outbound provider/web/MCP는 소비 operation으로 분리했다.

Session options와 public lifecycle

agentcore.Options가 embedding contract의 중심이다. NewSession은 error를 반환하지 않고 일부 misconfiguration을 warning, silent tool omission 또는 runtime failure로 미룬다. 52개 field와 nested option의 exact default/consumer는 설정 field 참조에 있다. agentcore 근거

public lifecycle은 NewSession → Prompt*이며 선택적으로 Resume, Reset, Close를 호출한다. Run은 one-shot 편의 함수지만 terminal reason fidelity가 줄어든다.

Event와 terminal

host가 받는 harness.Event 종류는 text, thinking, tool_use, tool_result, progress, usage, result다. 각 kind에서 유효한 payload field가 다르다. 마지막 result의 Terminal은 reason, error, cumulative usage, main turns, full conversation snapshot, final text를 가진다. event 근거

iterator의 별도 error 값보다 terminal error가 main loop 오류의 실제 전달 경로다. consumer가 result 전에 멈추는 경우와 context cancellation terminal은 구분해야 한다.

Tool interface와 input schema

CoreTool은 Name/Description/Prompt/InputSchema/IsReadOnly/IsConcurrencySafe/CheckPermissions/Call을 구현한다. ToolContext는 WorkingDir, AgentID, ToolUseID, output cap/dir, progress emitter, task manager와 extra process env를 전달한다. Result는 content, error flag, optional extra messages를 반환한다. tool 근거

중앙 schema validator는 JSON Schema 일부만 집행한다. resource constraint는 tool self-check나 더 바깥 broker에 있어야 한다. Result.Extra는 일반 result body가 아니라 conversation에 추가 user messages로 들어간다.

Permission 계약

permission mode는 default, acceptEdits, bypassPermissions, plan, dontAsk, auto다. CanUseTool callback은 interactive ask 단계에 도달했을 때만 호출되며 Decision은 allow/deny/ask, optional rewritten input/message/suggestions를 담는다. permission 근거

allow/deny rule은 name-only matcher이므로 argument와 target authorization contract가 아니다. 판정 순서에 mode별 우선순위가 있다.

Provider와 message contract

Provider.Stream은 normalized StreamEvent iterator, Complete는 assistant Message, stop reason, Usage를 반환한다. CompletionRequest는 ordered system segments, dynamic cache boundary, messages, tool schemas, output/temperature/stop/thinking을 담는다. provider 근거

Usage는 input/output/cache-read/cache-write tokens를 합산하지만 공급자가 주지 않는 값의 정확도를 Norma가 보완하지 않는다. custom Provider는 cancellation, event ordering, tool JSON, error와 usage semantics를 이 contract에 맞춰야 한다.

파일 형식과 소유권

각 nested field, corrupt/future handling과 consumer는 지속 파일 schema에 있다. transcript 근거 memory 근거 Noa state 근거 task 근거

Demo CLI

cmd/agentcore는 SDK 배선을 보여주는 demo binary다. 주요 flags는 -provider, -model, -base-url, -api-key, -system, -dir, -yes, -max-turns, -p다. construction error 일부만 non-zero exit로 매핑한다. Prompt iterator error는 stderr에 출력한 뒤 main이 정상 return할 수 있고, terminal reason은 process status로 변환하지 않는다. SIGINT/SIGTERM은 context cancel, Ctrl-D/EOF와 /exit는 정상 return이다. transcript를 설정하지 않아 기본 실행은 durable resume을 제공하지 않는다. stdout/stderr와 정확한 exit 의미는 CLI 참조에 있다.

CLI 근거

README/examples의 wiring은 예시이고 지원되는 deployment/control policy의 완전한 contract가 아니다. 5개 예제의 실제 동작은 dependency와 examples에 있다.

환경변수와 설정 우선순위

WebFetch/WebSearch에서 CA 또는 insecure만 설정하면 새 transport의 Proxy가 nil이어서 환경 proxy를 사용하지 않는다. WebSearch backend keys/proxy/CA는 agentcore.Options fields로도 전달된다. secrets는 문서·transcript·tool output에 복제하지 않고 host secret injection 경계에서 관리해야 한다. LLM transport 근거 Web tool transport 근거

상위 영역: Norma 현재 시스템 지도

전체로 돌아가기 · Markdown 원본