3. 제품 밖의 domain model

결론부터

Agent는 서비스의 정체성, AgentVersion은 실효 동작의 snapshot, Deployment는 이를 실행한 한 복사본이다

이 장에서 처음 나오는 말6개

aggregateDomain Aggregate: 함께 일관성을 지켜야 하는 객체 묶음. 여기서는 Agent가 version·grant·publication의 기준점이다.
immutable versionImmutable Version: 한번 승인·배포되면 내용을 바꾸지 않는 snapshot. 변경은 다음 version으로 만든다.
providerRefProvider Reference: kagent resource name이나 AgentCore ARN처럼 provider에서만 의미 있는 식별자다.
desired stateDesired State: control plane이 기대하는 배포 상태. adapter가 provider의 실제 상태를 이 값에 맞춘다.
triggerInvocation Trigger: 사람의 요청·schedule·event처럼 Agent 실행을 시작시키는 계기와 실행 정책이다.
knowledge bindingKnowledge Binding: AgentVersion이 어느 KnowledgeVersion을 어떤 검색·인용 정책으로 사용하는지 고정한 관계다.

객체 관계

Agent·Knowledge·Tool의 정체성과 immutable version이 binding을 거쳐 target별 Deployment와 providerRef로 이어지고 Publication이 준비된 Agent Deployment를 선택하는 객체 관계

이 객체들이 담을 내용 중 Agent의 종류 — 작성·활성화·상주·상태·격리·행위 위험의 여섯 요구 차원 — 는 2장에서 정의했다. 이 장은 그 구조화된 값과 권한·배포 상태를 어느 객체에 담고 어떤 불변조건으로 지키는지를 설계한다.

Agent와 AgentVersion

Agent에는 바뀌어도 정체성이 유지되는 값을 둔다.

회사 내 고유 agentId
표시 이름, 설명, owner principal
업무 data와 tool action 기준의 기본 risk tier
업무 domain과 data classification
생성·폐기 상태

실행 결과를 바꿀 수 있는 값은 AgentVersion으로 내린다. 작성 방식, artifact, prompt bundle, model policy, knowledge·tool binding, skill, execution profile, runtime contract와 resource hint가 여기에 포함된다. artifact는 OCI_IMAGE, CODE_ZIP, CONFIG_BUNDLE처럼 종류와 content digest를 함께 기록한다. target은 지원하지 않는 artifact를 validate에서 거부한다. latest tag나 mutable Git branch를 승인된 version의 근거로 쓰지 않는다.

승인 시 다음 실효 구성의 content hash를 만든다.

prompt + knowledge bindings + tool bindings + skills + model policy + policy bundle + execution profile
                                      ↓
                             effectiveConfigHash

전역 guardrail을 긴급 변경해야 한다면 기존 version을 몰래 바꾸지 않는다. 독립된 PolicyBundleVersion을 만들고 publication이 사용하는 실효 조합을 감사한다. 같은 답변을 재현할 때는 versionId뿐 아니라 이 hash와 각 binding version을 함께 사용한다.

Trigger는 Agent process가 아니다

사람이 portal에서 누르는 invoke는 즉시 trigger이고, scheduler와 event bus는 비대화형 trigger다. trigger가 실행됐다고 새 Agent process를 반드시 만드는 것은 아니다. placement policy가 상주 endpoint 호출, sandbox 복원, 일회성 Job 생성 중 target이 지원하는 방식을 고른다.

triggerId: trg_daily_finance
agentId: agt_finance_report
publication: production
type: SCHEDULE
schedule:
  cron: "0 8 * * 1-5"
  timezone: Asia/Seoul
principalRef: svc_finance_reporter
taskTemplate: "전 영업일 비용 보고서를 생성한다."
concurrencyPolicy: FORBID
timeout: 15m
retry:
  maxAttempts: 2

schedule에는 timezone, missed run 처리, 동시 실행 정책이 필요하다. event trigger에는 source, event schema, deduplication key와 acknowledgment policy가 필요하다. 둘 다 호출 사용자의 권한을 빌리지 않고 명시적인 service principal로 실행하며, 시작한 trigger ID를 trace와 audit event에 남긴다.

Grant와 Publication

Grant는 (agentId, principal, role)의 관계다. role은 처음에는 세 개면 충분하다.

role	허용할 대표 action
`INVOKER`	Agent 검색·호출, 자신의 conversation 조회
`EDITOR`	새 version 작성·제출, metadata 변경
`OWNER`	grant 변경, owner 이전, 폐기 요청

Publication은 배포와 다르다. runtime에 정상 배포됐어도 보안 승인과 smoke test가 끝나기 전에는 catalog에서 호출 가능 상태가 아니다. 반대로 새 배포가 실패해도 이전 published version은 계속 서비스할 수 있어야 한다.

DeploymentTarget과 Deployment

DeploymentTarget은 단순 provider 이름이 아니라 placement policy가 판단할 capability 묶음이다.

id: onprem-restricted-a
provider: kagent
zone: restricted
capabilities:
  protocols: [a2a, mcp]
  architectures: [amd64]
  internetEgress: false
  sessionIsolation: pod
  localModelAccess: true

Deployment는 특정 version을 특정 target에 실행한 결과다. 여기에서만 provider 정보를 가진다.

deploymentId: dep_01J...
agentId: agt_finance_report
versionId: ver_7
targetId: onprem-restricted-a
desiredState: RUNNING
observedState: READY
providerRef:
  namespace: agent-finance
  name: finance-report-v7
endpointRef: ep_01J...

같은 version을 AgentCore에 배포하면 providerRef가 runtime ARN과 endpoint qualifier로 바뀔 뿐 agentId, versionId, Grant는 그대로다.

Knowledge와 Tool은 version에 binding한다

KnowledgeBinding은 검색 계약이다

KnowledgeSource는 문서 저장소·업무 DB·승인된 upload 묶음의 회사 정체성이다. owner, data classification, 원본 위치의 logical reference와 삭제 책임을 가진다. 새 문서를 수집하거나 source revision·ACL·chunking·embedding model·index build가 바뀌면 immutable KnowledgeVersion을 만든다.

knowledgeVersionId: knv_hr_policy_2026_08
knowledgeSourceId: kns_hr_policy
sourceRevision: git:8f6c2d1
accessPolicyVersion: kap_14
indexBuild:
  chunkerVersion: semantic-v3
  embeddingModelVersion: text-embedding-3-large@2026-07
  artifactDigest: sha256:...
deletionLineage:
  supersedes: knv_hr_policy_2026_07
  removedDocumentIds: []

KnowledgeBinding은 AgentVersion이 이 snapshot을 어떻게 조회할지 고정한다. top-k, metadata filter, citation 필수 여부와 query principal 전달 방식을 담는다. vector DB collection이나 provider index ID는 environment별 KnowledgeDeployment.providerRef에 둔다. source 문서 삭제나 ACL 축소가 생기면 영향받는 KnowledgeVersion과 publication을 찾아 재색인·중지하고, 이전 index의 retention과 삭제 증거를 남긴다.

ToolBinding은 endpoint 목록이 아니다

tool을 URL만으로 연결하면 실행 권한의 의미가 사라진다. binding에는 다음을 함께 둔다.

논리적 toolId와 승인된 schema version
read·write·destructive risk
필요한 OAuth scope 또는 workload permission
user delegation, service identity 중 어느 auth mode인지
허용 data zone과 egress destination
human approval이 필요한 action

실제 cluster Service URL이나 AgentCore Gateway target ARN은 environment별 ToolDeployment.providerRef에 둔다. 사용자가 만든 MCP는 Tool·ToolVersion·ToolDeployment로 먼저 등록·검증한 뒤 binding한다. 이 공급 lifecycle은 사용자 MCP를 플랫폼에 올리기에서 이어서 설계한다.

식별자와 표시값을 분리한다

이메일과 부서명은 바뀐다. OIDC의 sub는 issuer 안에서만 유일하므로 ACL의 unique key는 (identityProviderId, subject)로 둔다. identityProviderId에는 검증된 issuer를 매핑하고, Entra ID라면 (tenantId, objectId)를 같은 구조로 정규화한다. 화면에는 현재 email과 display name을 붙인다. Agent 이름도 rename할 수 있으므로 URL과 audit event에는 agentId를 쓴다.

principalKey: prn_01J...
identityProviderId: idp_corp_keycloak
issuer: https://id.company.example/realms/employees
subject: 4f0f7f1d-...
display:
  email: kim@example.com
  name: 김사원

모든 trace와 audit event에는 최소 다음 correlation field가 있어야 한다.

agentId · versionId · deploymentId · targetId · triggerId
principalKey · sessionId · traceId · effectiveConfigHash

tool event에는 toolVersionId·capabilityName·policyDecisionId, retrieval event에는 knowledgeVersionId·knowledgeDeploymentId를 추가한다.

지켜야 할 불변조건

승인된 version과 binding은 수정하지 않는다. 변경은 새 version으로 만든다.
하나의 production publication은 하나의 active version을 가리킨다.
provider resource를 삭제해도 Agent와 audit 기록은 삭제하지 않는다.
owner가 사라지기 전에 group owner 또는 successor에게 이전한다.
deployment READY와 publication AVAILABLE을 같은 상태로 취급하지 않는다.
secret value를 version spec과 audit payload에 넣지 않는다.
AgentVersion, Deployment, Publication 상태는 서로 독립적으로 전이한다.
invocation은 당시의 effectiveConfigHash와 knowledge·policy version을 재구성할 수 있어야 한다.
source 삭제·ACL 축소는 index 재생성, publication 영향 판정과 삭제 증거까지 이어진다.

3장 요약

Agent·Knowledge·Tool은 정체성, Version은 실행 가능한 불변 snapshot, Deployment는 target별 실행·연결 결과다.
2장의 여섯 요구 차원은 AgentVersion·Trigger·DeploymentTarget에 나눠 담고, schedule과 event는 Trigger로 표현한다.
knowledge는 source·version·deployment·binding으로 나눠 ingestion·ACL·index lineage를 재현한다.
Grant와 Publication을 provider resource 밖에 두어 호출 권한과 공개 상태를 유지한다.
provider-specific ID·URL·secret은 공통 객체의 중심으로 들어오지 않고, 실효 구성 hash를 trace에 남긴다.

4. 등록부터 폐기까지version이 어떤 검사를 거쳐 배포·공개되고, 실패하면 어느 상태로 돌아가는지 잇는다.