@soddong/agentic-capability-agent-client

@soddong/agentic-capability-agent-client는 Agentic Platform의 Agent Client 계약 패키지입니다.

이 패키지는 @soddong/agentic-runtime, domain/application agent package, consumer project가 공유할 최소 contract를 제공합니다.

책임

@soddong/agentic-capability-agent-client
  - Agent manifest 타입
  - Agent client 타입
  - Agent resource index 타입
  - Agent resource selection 타입
  - Agent contribution 타입
  - Agent contribution resource loader
  - Agent contribution resource validator
  - Routing metadata 타입
  - Routing decision 타입
  - Rule-based candidate scoring helper

비책임

| 제외 항목 | 담당 | | --- | --- | | 실행 이력 저장 | @soddong/agentic-runtime | | SQLite schema | 각 domain/runtime package | | LLM 호출 구현 | concrete agent package | | Prompt router 실행 | @soddong/agentic-runtime 또는 runtime router package | | Document 조작 | @soddong/agentic-domain-document |

기본 사용 예시

import {
  createAgentManifest,
  scoreAgentManifest
} from "@soddong/agentic-capability-agent-client";

const manifest = createAgentManifest({
  agentId: "document-agent",
  packageName: "agentic-agent-document",
  packageVersion: "0.1.0",
  displayName: "Document Agent",
  capabilities: [
    {
      capabilityId: "document.create",
      description: "문서 초안을 생성합니다.",
      keywords: ["문서", "초안", "작성"]
    }
  ]
});

const score = scoreAgentManifest(manifest, {
  requestText: "요구사항 정의서 초안을 작성해줘"
});

console.log(score.matched);

Agent Resource Contribution 예시

각 domain package는 agent가 사용할 instruction, guide, example, validation rule, source mapping을 공통 계약으로 제공할 수 있습니다. Runtime은 이 contribution을 등록한 뒤 manifest 기준으로 routing하고, 선택된 contribution의 resource index를 agent 실행 context에 사용할 수 있습니다.

import {
  createAgentContribution,
  createAgentResourceIndex,
  createAgentManifest
} from "@soddong/agentic-capability-agent-client";

const contribution = createAgentContribution({
  manifest: createAgentManifest({
    agentId: "document-agent",
    packageName: "@soddong/agentic-domain-document",
    packageVersion: "0.6.0",
    moduleLayer: "domain",
    capabilities: [
      {
        capabilityId: "document.authoring",
        description: "문서 목차와 본문 블록 작성을 지원합니다.",
        keywords: ["문서", "목차", "본문", "블록"]
      }
    ]
  }),
  resourceIndex: createAgentResourceIndex({
    resourceIndexId: "agentic-domain-document.resources",
    title: "Document Agent Resources",
    version: "0.1.0",
    resourceGroups: [
      {
        kind: "instruction",
        title: "1. Instructions",
        order: 1,
        required: true
      },
      {
        kind: "guide",
        title: "2. Guides",
        order: 2,
        required: true
      }
    ],
    instructions: [
      {
        resourceId: "document.instruction.runtime",
        title: "Document Agent 실행 기준",
        kind: "instruction",
        path: "agent/instructions/00-runtime-behavior.md",
        priority: 100
      }
    ],
    guides: [
      {
        resourceId: "document.guide.table",
        title: "Table 작성 가이드",
        kind: "guide",
        path: "agent/guides/52-table-authoring-guide.md",
        priority: 100,
        topic: "table"
      }
    ]
  })
});

Agent Resource Selection 예시

resource index가 agent가 사용할 수 있는 전체 resource 목록이라면, resource selection은 사용자 요청에 맞춰 그중 어떤 resource 묶음을 적용할지 고르는 1차 rule입니다.

import {
  assembleAgentContextFromBundle,
  createAgentContribution,
  createAgentResourceSelection,
  selectAgentResources
} from "@soddong/agentic-capability-agent-client";

const contribution = createAgentContribution({
  manifest,
  resourceIndex,
  resourceSelection: createAgentResourceSelection({
    selectionId: "document.resource-selection",
    title: "Document Resource Selection",
    version: "0.1.0",
    alwaysResourceIds: [
      "document.instruction.runtime"
    ],
    fallbackResourceIds: [
      "document.guide.authoring",
      "document.guide.korean-writing"
    ],
    rules: [
      {
        ruleId: "document.resource-selection.table",
        bundleType: "table-authoring",
        priority: 100,
        keywords: ["표", "table", "컬럼", "헤더"],
        includeResourceIds: [
          "document.guide.authoring",
          "document.guide.korean-writing",
          "document.guide.table"
        ]
      }
    ]
  })
});

const bundle = selectAgentResources(contribution, {
  requestText: "표 컬럼 헤더를 설계해줘"
});

console.log(bundle.bundleType);
console.log(bundle.resourceIds);

const context = assembleAgentContextFromBundle(bundle, {
  packageRoot: process.cwd()
});

console.log(context.contentText);

1차 구현은 keyword 기반의 안전한 선별 기능이다. Work Mode, Target Area, Layer는 개념 분류로는 사용할 수 있지만 1차 실행 계약에는 넣지 않는다.

assembleAgentContextFromBundle()은 선택된 resource file을 읽어 LLM context에 넣을 수 있는 Markdown text로 조립한다. package root는 호출자가 제공한다. 이 helper는 특정 domain resource 의미를 하드코딩하지 않고, bundle에 포함된 path만 기준으로 파일을 읽는다.

긴 agent 지시문과 작성 기준은 TS 문자열로 직접 관리하지 않고 Markdown 파일을 원천으로 두는 것을 권장합니다. TS contribution은 resource id, kind, priority, topic, path 같은 구조 정보만 제공하고, 실제 본문은 package에 포함된 Markdown 파일에서 관리합니다.

표준 agent/ 리소스 구조를 사용하는 패키지는 디렉터리에서 contribution을 직접 로딩할 수 있습니다.

import {
  loadAgentContributionFromDirectory,
  validateAgentContributionResource
} from "@soddong/agentic-capability-agent-client";

const contribution = loadAgentContributionFromDirectory(process.cwd(), {
  validate: true
});

const issues = validateAgentContributionResource(contribution, process.cwd());
console.log(issues);

문서

| 문서 | 내용 | | --- | --- | | docs/usage.md | 사용 기준 | | docs/configuration.md | 설정 책임 | | docs/build.md | 구축 담당자 빌드/검증 | | docs/publishing.md | publish 절차 | | docs/delivery.md | 운영환경 전달 기준 | | docs/operations.md | 운영환경 설치/검증 |