콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

의존성 해석

Aggrega 의존성 해결과 구조적 토폴로지 기둥

Aggrega 아키텍처에서 토폴로지 의존성은 values 페이로드를 완전히 불투명하게 유지하기 위해 uses 스키마 기둥을 통해 명시적으로 매핑됩니다. “누가 누구와 통신하는가”를 해결하는 데에는 특정한 과제가 있습니다. 개발자에게 명시적인 네트워크 라우팅, 오케스트레이터 수준의 실행 순서, 인프라 의존성을 작성하도록 강요하지 않으면서 복잡한 다중 노드 애플리케이션 토폴로지를 매핑해야 합니다.

1. 핵심 철학: 왜 uses인가?

uses 블록은 컴포넌트 간 의존성을 순수한 토폴로지로 선언합니다. Component A는 Component B의 물리적 주소나 연결 세부 정보가 아니라 Component B의 공개 provides 계약에 의존합니다. 토폴로지는 uses에, 구성은 values에 있습니다. 이 분리 덕분에 컴파일러는 values 내용에서 추론하지 않고도 모든 컴포넌트 간 에지를 명시적으로 볼 수 있습니다.

Aggrega는 토폴로지를 uses라는 일급 스키마 기둥으로 격상하여 이 문제를 해결합니다.

  • 시맨틱 프록시 논거: 키워드 uses는 L7 시맨틱 의도를 나타냅니다. 에이전트가 데이터베이스를 uses한다면, Platform Ops가 그 사이에 투명한 Wasm 프록시 메시를 주입하더라도 이는 의미상 여전히 참입니다.
  • 수학적 중립성: Go 컴파일러는 uses 구조체를 네이티브로 파싱하여 중간 표현(IR) 그래프를 그립니다. 개발자의 애플리케이션 로직(values)을 파싱하거나 조회하려고 시도하지 않습니다.
  • Feature 원자성: uses 기둥은 Components와 Features(자격 증명 Features 포함)에 동일하게 적용됩니다. 따라서 사이드카 프록시(Feature)나 자격 증명 페처가 부모 Component의 구성을 오염시키지 않고 자체 네트워크 의존성을 자율적으로 선언할 수 있습니다.

2. 통합 스키마 계약의 메커니즘

애플리케이션 페이로드를 파싱하지 않고 운영 지침을 추출하기 위해, 시스템은 명시적으로 분리된 YAML 구조를 규정하는 엄격한 JSON Schema 2020-12 선언에 의존합니다.

도메인 2: 분할 스키마(usesSchema 및 schema) 플랫폼 카탈로그가 관리할 수 없는 스키마 파일들로 파편화되는 것을 막기 위해 Aggrega는 분할 스키마 엔진을 사용합니다. 네이티브 YAML usesSchema는 토폴로지를 엄격하게 정의하고 검증하며, schema:(JSON Schema 2020-12 — 일반적으로 축약형 단축 표기로 작성)는 values 및 infra 기둥의 내용을 검증하고 provides 기둥의 형태를 선언합니다. 개발자가 작성한 values와 운영자가 설정한 infra는 선언된 타입에 대해 검사됩니다. provides 하위 스키마는 Recipe가 생성하는 다운스트림 계약의 키 이름과 타입을 선언하며, 컴파일러는 모든 inject 참조가 선언된 provides 키를 가리키는지 검사합니다. 그러나 생성된 provides 값 자체는 컴파일러가 타입 검사하는 값이 아니라, 해석 없이 전달하는 불투명한 문자열로 다운스트림에 전달됩니다. 코어는 전달된 값이 무엇을 의미하는지 해석하지 않기 때문입니다. usesSchema는 소켓이 선언되는 곳이며, 소켓을 선언하는 것이 소켓에 계약을 부여합니다. 카탈로그 엔티티가 선언한 소켓은 해당 엔티티의 제약 조건을 지닙니다. 즉, 어떤 대상에 도달할 수 있는지를 나타내는 셀렉터, inject 허용 목록, 에지별 valueSchema / infraSchema입니다. usesSchema 안에서 Platform Architect는 selector: 필드를 사용하며 — 이는 생성된 스키마에 복사되지 않고 Architect가 작성한 문자열 그대로 읽힙니다 — 네이티브 Go 셀렉터 엔진이 이를 평가하여 선언된 소켓에 대해 노드 간 타입 안전성을 강제합니다. 이를 통해 소켓이 데이터베이스를 요구하는 경우 개발자가 웹 서버를 연결할 수 없도록 보장합니다.

셀렉터는 평가되는 시점, 즉 소켓을 통해 연결된 각 에지마다 한 번씩 문법에 따라 검사됩니다. 엔진이 여섯 가지 요구 조건 형식 중 하나로 읽을 수 없는 셀렉터 — 잘못 들어간 쉼표로 생긴 빈 요구 조건, 공백이나 문법이 형식을 구분하는 데 사용하는 문자(=, !, (, ) 및 쉼표) 중 하나를 포함한 키, 닫는 괄호가 없는 집합 — 는 다른 셀렉터로 읽히는 대신 해당 요구 조건을 지목하며 그 에지에서 빌드를 중단시킵니다. 이러한 엄격함이 검사를 정직하게 유지합니다. 관대하게 읽으면, 프런트엔드를 배제하려고 작성한 !tier=frontend는 tier=frontend라는 이름의 레이블이 없기만을 요구하게 되어, 프런트엔드를 포함한 모든 대상이 통과하게 됩니다. 동일한 문법이 연결 슬롯 셀렉터와 Feature의 appliesTo에도 적용됩니다. 셀렉터 문법에 모든 형식과 모든 거부 사례가 나열되어 있습니다. 빌드는 어떤 에지도 연결되지 않은 소켓을 평가하지 않으므로, aggrega validate는 — 카탈로그 전체에 대해서든, 소켓을 선언하는 Component나 Feature에 대해서든 — 선언된 모든 소켓의 셀렉터를 읽고 잘못된 셀렉터를 그 단계에서 거부하며, 이때 소켓을 연결하는 빌드가 사용하는 것과 같은 코드와 문구를 사용합니다.

하지만 소켓 선언이 에지를 그리는 유일한 방법은 아닙니다. Aggregate 작성자는 카탈로그 엔티티가 선언하지 않은 소켓을 자신의 컴포넌트에 지정할 수 있으며 — usesSchema를 전혀 선언하지 않은 컴포넌트 타입에서도 마찬가지입니다 — 에지는 생성됩니다. 소켓 항목을 선언하지 않은 카탈로그는 그 연결을 예상하지 않았을 뿐 금지한 것이 아니며, 애플리케이션의 토폴로지는 개발자가 소유합니다. 이러한 소켓을 애드혹(ad-hoc) 소켓이라고 하며, 그 대가는 정확히 선언으로 얻는 것만큼입니다. 카탈로그 항목이 없으므로 셀렉터도 에지별 계약도 없고, 노드 간 타입 안전성은 평가할 대상이 없습니다. 에지가 전달할 수 있는 것은 변하지 않습니다. 주입하는 모든 키는 여전히 대상의 provides가 선언한 키를 가리켜야 하며, 대상은 여전히 존재해야 합니다. 출력된 그래프의 모든 에지는 둘 중 어느 쪽인지를 기록하므로 소비자가 추측할 필요가 없습니다. 운영자가 애드혹 소켓을 전면 금지하는 방법은 governance-and-compliance를 참조하십시오.

두 가지 표면은 애플리케이션의 토폴로지를 작성하지 않기 때문에 의도적으로 이런 방식으로 열려 있지 않습니다. Feature 연결의 uses는 연결된 Feature가 선언한 소켓만 지정할 수 있고, Release의 에지별 uses는 소비하는 컴포넌트의 카탈로그 엔티티가 usesSchema에 선언한 소켓만 지정할 수 있으며, Aggregate가 애드혹으로 작성한 소켓은 지정할 수 없습니다. 운영자는 아키텍처 안에서 구성하고 연결하며, Feature는 자신의 카탈로그 엔티티가 선언한 토폴로지에 참여합니다. 또한 카탈로그에서 소켓을 선언하는 것이 여전히 더 나은 방법이며 표준 라이브러리 카탈로그도 그렇게 합니다. 애드혹 소켓은 탈출구이지 새로운 기본값이 아닙니다.

도메인 1: 개발자 경험(다형성) 개발자는 uses:를 values: 및 features:와 같은 수준에 작성합니다. 매끄러운 UX를 보장하기 위해 스키마는 다형성을 네이티브로 지원합니다.

  • 문자열 배열: 표준 라우팅으로 충분한 단순한 논리적 컴포넌트 참조에 사용됩니다(예: tools: ["search-api"]).
  • 객체 맵: 엄격한 전달 계약이 필요할 때 사용됩니다(예: databases: { hr_db: { target: "corporate-hr", inject: { env: [{ in: DB_URL, from: "host" }] } } }).
  • 와일드카드 없음: 와일드카드 형식은 존재하지 않으며, 이로써 “유령 의존성”과 승인되지 않은 자동 연결을 방지합니다. 모든 항목은 하나의 컴포넌트를 지정하므로 ["*"]는 존재하지 않는 대상으로서 빌드를 중단합니다. 어떤 컴포넌트 이름에도 *를 포함할 수 없습니다.

도메인 3: 운영 현실(정규화) 예측 가능한 Go 템플릿을 유지하기 위해 Go 컴파일러는 다형적인 uses 입력을 정규화합니다. 논리적 컴포넌트 참조 배열은 .context.uses라는 엄격하고 평탄한 딕셔너리로 전달되기 전에 표준 객체로 변환됩니다.


3. 엔드투엔드 예제

다음 두 예제는 명시적 토폴로지 기둥의 서로 다른 두 가지 속성을 보여 줍니다. 예제 A는 연결이 승인되었는지 여부(노드 간 타입 안전성)를, 예제 B는 연결 데이터가 어떻게 물리적으로 전달되는지(다형성 및 정규화)를 입증합니다.

예제 A: 토폴로지 검증과 노드 간 타입 안전성

이 시나리오는 선언된 소켓의 셀렉터가, AI 에이전트가 필수 컴플라이언스 레이블이 없는 데이터베이스에 연결하려는 것을 감지하고 빌드를 중단하는 과정을 따라갑니다. 컴파일러는 아키텍트가 작성한 레이블 셀렉터를 문자열로서 대상의 레이블에 대해 평가합니다. 레이블의 의미는 해석하지 않으며, 정책 플러그인도 관여하지 않습니다.

1. 표준 라이브러리(카탈로그의 통합 schema:) Platform Architect가 스키마 구조를 정의하며, 인지 로직과 토폴로지 대상을 네이티브로 분리합니다.

apiVersion: aggrega.ai/v1beta1
kind: Component
metadata:
name: core/enterprise-agent
version: 1.0.0
labels:
component.aggrega.ai/type: "worker"
spec:
usesSchema:
datastores:
selector: "component.aggrega.ai/type=stateful-server, compliance.aggrega.ai/data-class=restricted"
schema:
# 1. The Cognitive Intent
values:
system_prompt: { type: string, required: true }

2. 개발자의 의도(Aggregate) 개발자는 에이전트가 하는 일(values)과 에이전트가 연결되는 대상(uses)을 깔끔하게 분리합니다.

components:
my_secure_vector_db:
type: core/qdrant-secure:1.0.0
values:
collection_name: finance_data
auditing_agent:
type: core/enterprise-agent:1.0.0
values:
system_prompt: "You are a financial auditing AI..."
uses:
datastores:
finance_memory: { target: "my_secure_vector_db" }

3. 컴파일러 실행과 토폴로지 검증

  1. 로컬 검증: Go 컴파일러는 해석 단계에서 객체 전체를 해석된 JSON Schema에 대해 평가합니다. my_secure_vector_db의 기반 카탈로그 레이블을 확인합니다. 데이터베이스에 restricted 레이블이 없다면 컴파일러는 타입 안전성 위반으로 즉시 빌드를 중단합니다.
  2. 그래프 작성: 토폴로지 구성 단계에서 Go 컴파일러는 스키마로 검증된 내용을 전혀 보지 않습니다. YAML에서 uses.datastores.finance_memory.target을 네이티브로 읽어 IR 그래프에 명시적인 간선을 그립니다.

예제 B: 다형성과 정규화된 .context.uses

이 시나리오는 컴파일러가 블랙박스 AI 도구(배열로 전달됨)와 레거시 관계형 데이터베이스(inject 계약이 있는 맵이 필요함)를 모두 처리하는 방식을 보여 줍니다.

1. 카탈로그(도메인 2): schema: 선언 Architect는 도구에 대해서는 다형적 배열을 허용하지만, 데이터베이스에 대해서는 엄격한 객체를 요구합니다.

spec:
usesSchema:
# Polymorphic Array Socket (No injection needed)
tools:
selector: "tool.aggrega.ai/impact=read-only"
# Strict Map Socket (Requires delivery contract)
databases:
selector: "component.aggrega.ai/type=stateful-server"
inject: ["env", "file"]
schema:
values:
system_prompt: { type: string, required: true }

2. 개발자 의도(도메인 1): Aggregate 개발자는 도구에는 간결한 배열을, 데이터베이스에는 명시적인 맵을 사용합니다.

components:
my-agent:
type: core/python-worker:1.0.0
values:
system_prompt: "You are an HR bot."
uses:
# 1. Polymorphic Array: Simple logical component reference
tools:
- "corporate-search-api"
# 2. Strict Map: Dictating the environment variable delivery
databases:
hr_db:
target: corporate-hr-db
inject:
env:
- in: HR_DATABASE_URI # Local env var
from: "host" # Target provides key

3. Ops 현실(도메인 3): Recipe Go 컴파일러가 다형성을 정규화합니다. Ops는 평탄하고 예측 가능한 .context.uses 딕셔너리를 받습니다. 템플릿의 관련 섹션에서 .context.inject 파이프를 순회하기만 하면 됩니다.

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: generic-worker
version: 1.0.0
spec:
capability: helm
implements: core/python-worker:1.0.0
source: "./charts/internal/python-runner"
locals:
primary_compute: worker-container
valuesMapping: |
env:
# Ops uses the pre-resolved inject map, kept apart from values and topology loops
{{- range $key, $value := .context.inject.env }}
- name: {{ $key }}
value: "{{ $value }}"
{{- end }}