agentic-runtime

agentic-runtime은 Agentic Platform의 로컬 실행 기반(runtime) 및 CLI 패키지입니다.

이 패키지는 agentic 명령을 제공하며, 설치된 domain, capability, application 패키지를 로컬 실행 프로젝트에서 조립하고 실행하기 위한 기반 역할을 합니다.

사용자 관점 요약

| 항목 | 내용 | | --- | --- | | package | agentic-runtime | | CLI | agentic | | 현재 지원 명령 | agentic help, agentic version, agentic init, agentic setup, agentic docs, agentic config, agentic run, agentic execution list/latest/show/summary, agentic hook record, agentic db init/status, agentic adapter install/status, agentic module register/list, agentic bundle install/apply/list/status, agentic seed import/apply/status, agentic agent register/context | | 예정 명령 | agentic validate, agentic render |

Agent 실행 API

Agent module은 AgentRuntimeClient 형태로 run()을 제공하고, 실행 프로젝트 또는 router는 runAgentRuntimeClient()로 실행합니다.

이 방식에서 Agent는 실제 업무 로직만 담당하고, agentic-runtime은 실행 이력, 사용자 지시, 로그, 결과 저장을 표준화합니다.

import { runAgentRuntimeClient } from "agentic-runtime";

const agent = {
  manifest: {
    agentId: "sample-agent",
    packageName: "sample-agent-package",
    packageVersion: "0.1.0",
    moduleLayer: "application",
    capabilities: [
      {
        capabilityId: "sample.review",
        description: "요구사항을 검토합니다.",
        keywords: ["요구사항", "검토"]
      }
    ]
  },
  run(input, context) {
    context.logger.info("Agent request received", {
      requestText: input.requestText
    });

    return {
      outputType: "json",
      contentJson: {
        ok: true,
        requestText: input.requestText
      }
    };
  }
};

const result = await runAgentRuntimeClient(agent, {
  requestText: "요구사항을 검토해 주세요."
});

console.log(result.runId);

Agent Routing API

agentic-runtime은 concrete domain package를 직접 의존하지 않습니다. 각 agent package가 agentic-capability-agent-client의 manifest contract를 제공하면, runtime은 등록된 manifest를 기준으로 route decision을 수행합니다.

import {
  registerAgentManifest,
  routeRegisteredAgents
} from "agentic-runtime";
import { createAgentManifest } from "agentic-capability-agent-client";

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

registerAgentManifest(manifest);

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

console.log(decision.selectedAgentId);

domain package가 agent resource index까지 함께 제공하는 경우에는 contribution을 등록합니다.

import {
  assembleRegisteredAgentContext,
  registerAgentContribution,
  routeRegisteredAgents,
  selectRegisteredAgentResources
} from "agentic-runtime";
import { documentAgentContribution } from "agentic-domain-document";

registerAgentContribution(documentAgentContribution);

const decision = routeRegisteredAgents({
  requestText: "문서 목차와 본문 초안을 작성해줘"
});

console.log(decision.selectedContribution?.resourceIndex?.title);

const bundle = selectRegisteredAgentResources({
  requestText: "문서 표 컬럼 헤더를 설계해줘"
});

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

const context = assembleRegisteredAgentContext(
  {
    requestText: "문서 표 컬럼 헤더를 설계해줘"
  },
  {
    packageRoots: {
      "agentic-domain-document": "/path/to/node_modules/agentic-domain-document"
    }
  }
);

console.log(context?.contentText);

1차 routing은 keyword/example 기반 rule scoring입니다. LLM router와 embedding router는 후속 확장 대상입니다.

Agent resource selection도 1차에서는 선택된 contribution의 keyword rule을 실행하는 방식입니다. Runtime은 각 domain package의 파일 의미를 하드코딩하지 않고, 선택된 agent contribution의 resource-selection.json 계약만 실행합니다.

Agent context assembly는 선택된 resource file을 실제 Markdown context로 조립한다. Runtime은 package 설치 경로를 임의로 추정하지 않으므로 packageRoots를 호출자가 제공해야 한다.

Consumer 프로젝트에서 CLI로 agent contribution을 등록하고 context를 조립하려면 다음 명령을 사용합니다.

npx agentic agent register agentic-domain-document
npx agentic agent context "표 컬럼 헤더를 설계하고 3열은 설명으로 해줘"
npx agentic agent context "표 컬럼 헤더를 설계하고 3열은 설명으로 해줘" --format json

CLI는 consumer 프로젝트의 node_modules에서 package root를 찾고, 등록된 module registry를 기준으로 context 조립에 필요한 package root를 연결합니다. 따라서 코드 API처럼 packageRoots를 직접 넘기지 않아도 됩니다.

저장되는 주요 정보:

| 구분 | 테이블 | 내용 | | --- | --- | --- | | 사용자 지시 | agentic_user_requests | 지시 원문, 유입 경로, context snapshot | | 실행 단위 | agentic_execution_runs | 실행 package, agent/command 식별자, 상태, 소요 시간 | | 실행 로그 | agentic_execution_logs | Agent가 남긴 단계별 로그와 구조화 payload | | 실행 결과 | agentic_execution_outputs | text/json/file/artifact 결과 |

설치

기본 registry는 공식 npm registry입니다.

npm install [email protected]

사용자 ~/.npmrc에 별도 registry가 남아 있으면 공식 registry를 명시하거나 user config를 정리합니다.

npm config set registry https://registry.npmjs.org/ --location=user
npm install [email protected] --registry=https://registry.npmjs.org/

publish 권한이 필요한 사용자는 ~/.npmrc에 npm token을 설정합니다. token 실값은 문서, source, CI log에 기록하지 않습니다.

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

실행 확인

npx agentic --version
npx agentic --help

기대 결과:

agentic-runtime 0.15.2

프로젝트 초기화

사용자 프로젝트에서 다음 명령을 실행하면 기본 설정 파일과 로컬 작업 디렉터리를 생성합니다.

npx agentic init

생성 구조:

consumer-project/
  agentic.config.json
  .agentic/
    AGENTS.md
    README.md
    bin/
      agentic-hook.mjs
    data/
    logs/
    modules/

설치된 패키지 문서 위치와 현재 프로젝트 설정 상태는 다음 명령으로 확인합니다.

npx agentic docs
npx agentic config

Codex, Kiro, Claude Code adapter까지 함께 준비하려면 통합 setup 명령을 사용합니다.

npx agentic setup --adapter codex
npx agentic setup --adapter kiro
npx agentic setup --adapter claude-code

adapter install을 먼저 실행해도 됩니다. 프로젝트가 아직 초기화되지 않았으면 adapter install이 내부에서 init과 db init을 먼저 수행한 뒤 adapter 설치까지 진행합니다.

npx agentic adapter install kiro

.agentic/AGENTS.md는 agentic-runtime managed block으로 관리됩니다. init, setup, adapter install 실행 시 managed block의 runtime version을 확인하고, 기존 block version이 현재 runtime보다 낮으면 사용자 작성 영역은 유지한 채 managed block만 갱신합니다.

<!-- agentic-runtime:start version=0.15.2 -->
...
<!-- agentic-runtime:end -->

사용자가 직접 작성한 지침은 managed block 밖에 둡니다.

Agent hook은 성능을 위해 npx를 매번 호출하지 않고 project-local wrapper를 사용합니다.

node .agentic/bin/agentic-hook.mjs --source kiro --event PromptSubmit

파일만 생성하고 Codex CLI marketplace/plugin add는 건너뛰려면 다음을 사용합니다.

npx agentic setup --adapter codex --prepare-only

Runtime Execution 기록

사용자 지시를 runtime execution으로 기록합니다.

npx agentic run "요구사항을 검토해 주세요."

현재 agentic run은 router 또는 개별 Agent module 실행 전 단계의 공통 기록 기능입니다.

저장되는 위치:

| 정보 | 테이블 | | --- | --- | | 사용자 지시 | agentic_user_requests | | 실행 단위 | agentic_execution_runs | | 실행 로그 | agentic_execution_logs | | 실행 결과 | agentic_execution_outputs |

agentic init은 .agentic/AGENTS.md 템플릿을 생성합니다. consumer 프로젝트의 루트 AGENTS.md에는 이 내용을 반영해, Agentic Platform 관련 지시가 먼저 npx agentic run "<사용자 지시문>"으로 기록되도록 운영 정책을 둡니다.

Runtime Execution 이력 조회

저장된 사용자 지시, 실행 상태, 로그, 결과는 다음 명령으로 조회합니다.

npx agentic execution list --range today
npx agentic execution latest
npx agentic execution show <run-id>
npx agentic execution summary --range 7d

Agent나 자동화 도구가 사용하기 쉬운 JSON 출력도 지원합니다.

npx agentic execution list --range 7d --format json
npx agentic execution summary --range today --format json
npx agentic execution latest --range today --status succeeded --format json

이전 지시, 이전 결과, 마지막 완료 작업을 묻는 경우에는 현재 실행 중인 자기 run을 피하기 위해 --status succeeded를 우선 사용합니다.

현재 실행 중인 작업을 묻는 경우에는 --status running, 실패 이력을 묻는 경우에는 --status failed를 사용합니다.

주요 조회 옵션:

--range 1h|6h|24h|today|yesterday|7d|30d|this-week|last-week|this-month|last-month
--from YYYY-MM-DD
--to YYYY-MM-DD
--source codex|kiro|claude-code
--status succeeded
--limit 20
--format text|json

Execution timestamp는 UTC 기준으로 저장합니다. SQLite CURRENT_TIMESTAMP로 저장된 timezone 없는 DATETIME 문자열도 UTC로 해석합니다.

조회 range는 rolling range와 calendar range를 구분합니다.

| range | 기준 | | --- | --- | | 1h, 6h, 24h | 현재 시각 기준 rolling range | | 7d, 30d | 현재 시각 기준 rolling range | | today, yesterday | KST calendar day | | this-week, last-week | KST calendar week, 월요일 시작 | | this-month, last-month | KST calendar month |

예를 들어 today가 2026-06-26 KST이면 SQL 비교 boundary는 2026-06-25 15:00:00 UTC부터 2026-06-26 15:00:00 UTC까지입니다.

Codex Adapter

Codex adapter는 Codex UserPromptSubmit, Stop hook을 통해 사용자 지시와 turn 결과를 agentic-runtime execution DB에 기록합니다.

Codex adapter는 전역 Codex plugin bridge를 사용합니다. 표준 selector는 agentic-runtime-codex@agentic-runtime이며, 실제 기록은 현재 작업 디렉터리에 agentic.config.json과 .agentic/bin/agentic-hook.mjs가 있는 프로젝트에서만 수행합니다.

설치:

npx agentic adapter install codex

상태 확인:

npx agentic adapter status codex

이미 설치된 Codex adapter 파일을 현재 agentic-runtime 버전 기준으로 갱신하려면 --force를 사용합니다.

npx agentic adapter install codex --force
codex plugin list

생성 구조:

consumer-project/
  plugins/
    agentic-runtime-codex/
      .codex-plugin/
        plugin.json
      hooks/
        hooks.json
      skills/
        agentic-runtime-usage/
          SKILL.md
  .agents/
    plugins/
      marketplace.json

Codex가 hook 신뢰 승인을 요구하면 사용자가 내용을 확인하고 승인해야 합니다.

Codex hook command는 프로젝트 로컬 wrapper인 .agentic/bin/agentic-hook.mjs가 있을 때만 기록을 수행합니다. wrapper가 없는 프로젝트에서는 성공 상태로 no-op 처리하므로, Codex plugin 등록이 남아 있어도 agentic-runtime 미초기화 프로젝트의 turn이 hook 실패로 중단되지 않습니다.

같은 agentic-runtime-codex plugin을 여러 marketplace에서 동시에 활성화하지 않습니다. 중복 등록이 있으면 hook이 중복 실행될 수 있으므로 agentic-runtime-codex@agentic-runtime 하나만 전역 bridge로 유지합니다.

Kiro Adapter

Kiro adapter는 Kiro CLI/IDE에서 사용자 지시와 Agent turn 종료를 agentic-runtime execution DB에 기록하기 위한 설정을 생성합니다.

지원 범위:

| 대상 | 생성/수정 파일 | 비고 | | --- | --- | --- | | Kiro CLI V3 Early Access | .kiro/hooks/agentic-runtime.json | standalone hook 파일, UserPromptSubmit/Stop trigger 사용 | | Kiro CLI V2 | .kiro/agents/kiro_with_hooks.json | agent config의 embedded hooks 필드 사용 | | Kiro IDE | .kiro/hooks/*.kiro.hook | IDE 호환용 보조 파일 |

설치:

npx agentic adapter install kiro

상태 확인:

npx agentic adapter status kiro

이미 생성된 Kiro adapter 파일을 현재 agentic-runtime 버전 기준으로 갱신하려면 --force를 사용합니다.

npx agentic adapter install kiro --force

Kiro CLI V2에서 hook agent를 기본값으로 지정하려면 --set-default를 명시합니다. 이 옵션은 사용자 Kiro 설정을 변경할 수 있으므로 기본 설치에서는 실행하지 않습니다.

npx agentic adapter install kiro --set-default

--set-default는 내부적으로 kiro-cli agent set-default kiro_with_hooks를 실행합니다. kiro 명령이 아니라 kiro-cli 명령이어야 하며, agent 이름은 kito_with_hooks가 아니라 kiro_with_hooks입니다.

직접 확인:

kiro-cli agent set-default kiro_with_hooks
kiro-cli --agent kiro_with_hooks

생성 구조:

consumer-project/
  .kiro/
    agents/
      kiro_with_hooks.json
    hooks/
      agentic-runtime.json
      agentic-runtime-prompt-submit.kiro.hook
      agentic-runtime-agent-stop.kiro.hook
    steering/
      agentic-runtime.md
  plugins/
    agentic-runtime-kiro/
      README.md
      hooks/
        kiro-hook-guide.md

등록되는 command:

| 구분 | Event/Trigger | Command | | --- | --- | --- | | Kiro CLI V3 | UserPromptSubmit | node .agentic/bin/agentic-hook.mjs --source kiro --event PromptSubmit | | Kiro CLI V3 | Stop | node .agentic/bin/agentic-hook.mjs --source kiro --event AgentStop | | Kiro CLI V2 | userPromptSubmit | node .agentic/bin/agentic-hook.mjs --source kiro --event PromptSubmit | | Kiro CLI V2 | stop | node .agentic/bin/agentic-hook.mjs --source kiro --event AgentStop | | Kiro IDE | Prompt Submit | node .agentic/bin/agentic-hook.mjs --source kiro --event PromptSubmit | | Kiro IDE | Agent Stop | node .agentic/bin/agentic-hook.mjs --source kiro --event AgentStop |

Kiro CLI V3는 현재 Early Access이며 kiro-cli --v3로 opt-in 하는 구조입니다. CLI V2는 기존 agent config embedded hook을 사용합니다. Kiro IDE에서 .kiro/hooks/*.kiro.hook 파일을 인식하지 못하면 Kiro UI에서 생성된 파일 내용을 기준으로 hook 등록 상태를 확인합니다.

Kiro CLI V2에서 hook을 적용하려면 다음 중 하나로 실행합니다.

kiro-cli --agent kiro_with_hooks
kiro-cli agent set-default kiro_with_hooks

상세한 Kiro CLI/IDE hook 설명은 consumer 프로젝트에 생성되는 다음 파일을 확인합니다.

cat plugins/agentic-runtime-kiro/hooks/kiro-hook-guide.md

검증:

npx agentic adapter status kiro
npx agentic execution latest --source kiro --format json

Claude Code Adapter

Claude Code adapter는 .claude/settings.json에 UserPromptSubmit, Stop command hook을 자동 병합하여 사용자 지시와 turn 종료를 agentic-runtime execution DB에 기록합니다.

설치:

npx agentic adapter install claude-code

상태 확인:

npx agentic adapter status claude-code

이미 생성된 Claude Code adapter 파일을 현재 agentic-runtime 버전 기준으로 갱신하려면 --force를 사용합니다.

npx agentic adapter install claude-code --force

생성/수정 구조:

consumer-project/
  .claude/
    settings.json
    rules/
      agentic-runtime.md
  plugins/
    agentic-runtime-claude-code/
      README.md

등록되는 hook:

| Claude Code hook | Command | | --- | --- | | UserPromptSubmit | node .agentic/bin/agentic-hook.mjs --source claude-code --event UserPromptSubmit | | Stop | node .agentic/bin/agentic-hook.mjs --source claude-code --event Stop |

SQLite 초기화

사용자 프로젝트의 로컬 실행 DB를 초기화합니다.

npx agentic db init
npx agentic db status

기본 DB 파일:

.agentic/platform.sqlite

Module Registry

실행 프로젝트에서 사용할 Agentic package는 프로젝트 DB에 명시적으로 등록합니다.

npx agentic module register sample-agent-package 0.0.1 application
npx agentic module list

module layer 값:

runtime
domain
capability
application
support

Project Bundle Registry

methodology seed bundle provider package가 설치되어 있으면 runtime에 bundle 설치 상태를 등록할 수 있습니다.

npx agentic bundle install agentic-methodology-ai-agent-sdlc --bundle ai-agent-sdlc-build-planning
npx agentic bundle apply agentic-methodology-ai-agent-sdlc --bundle ai-agent-sdlc-build-planning
npx agentic bundle apply agentic-methodology-ai-agent-sdlc --bundle ai-agent-sdlc-build-planning --install-required
npx agentic bundle list
npx agentic bundle status

bundle install은 bundle manifest와 validation 결과를 runtime DB에 등록합니다. 실제 methodology, artifact, document domain DB 반영은 seed import로 계획을 만든 뒤 seed apply에서 target package handler를 통해 수행합니다.

bundle apply는 다음 단계를 한 번에 수행합니다.

- 프로젝트 runtime init/db init
- --install-required 지정 시 bundle provider package npm install
- bundle install
- --install-required 지정 시 bundle manifest의 requires.packages npm install
- bundle manifest의 requires.packages 자동 module register
- seed import
- seed apply

기본 bundle apply는 npm package를 자동 설치하지 않고, 이미 설치된 package만 등록/적용합니다. 사용자 편의 설치까지 포함하려면 --install-required를 사용합니다.

npx agentic bundle apply agentic-methodology-ai-agent-sdlc \
  --bundle ai-agent-sdlc-build-planning \
  --install-required

수동 설치를 선호하면 다음처럼 먼저 packages를 설치한 뒤 bundle apply를 실행할 수 있습니다.

npm install agentic-methodology-ai-agent-sdlc agentic-domain-methodology agentic-domain-artifact-standard agentic-contract-validation agentic-domain-artifact
npx agentic bundle apply agentic-methodology-ai-agent-sdlc --bundle ai-agent-sdlc-build-planning

Seed Import Plan

installed bundle을 기준으로 domain package 반영 계획을 dry-run으로 생성합니다.

npx agentic seed import --bundle ai-agent-sdlc-build-planning
npx agentic seed apply --bundle ai-agent-sdlc-build-planning
npx agentic seed status

seed import는 target package 준비 상태를 점검하고 agentic_seed_import_runs, agentic_seed_import_items에 import plan을 저장합니다. target package가 설치 또는 등록되지 않았으면 해당 item은 blocked로 표시합니다.

Bundle: ai-agent-sdlc-build-planning
Target: agentic-domain-methodology
Status: blocked
Reason: package not installed or not registered

seed import 단계는 dry-run이며 domain DB에는 쓰지 않습니다. seed apply는 생성된 import plan을 기준으로 target package의 applyAgenticSeed handler를 호출합니다. target package가 설치 또는 등록되지 않았거나 handler가 없으면 해당 item은 blocked로 남습니다.

문서 구분

패키지 사용자는 필요한 문서만 보면 됩니다.

공통 패키지 개발 기준은 구축 저장소의 docs/standards/package-development-standard.md를 따릅니다.

| 대상 | 문서 | 내용 | | --- | --- | --- | | 운영환경 사용자 | docs/usage.md | 설치, 실행 확인, 기본 사용법 | | 운영환경 사용자 | docs/configuration.md | 외부 실행 프로젝트의 환경 설정 원칙 | | 운영환경 담당자 | docs/operations.md | 운영환경 설치, 검증, 장애 확인 | | 구축 담당자 | docs/build.md | 개발, 빌드, 로컬 검증 | | 구축 담당자 | docs/publishing.md | npm pack, publish, publish 검증 | | 구축 담당자 | docs/delivery.md | 구축 환경에서 운영환경으로 전달할 패키지별 기준 | | 구축 담당자 | docs/schema/generated/README.md | tbls가 생성한 SQLite 테이블 설계 문서 | | 구축 담당자 | docs/schema/generated/schema.svg | tbls가 생성한 SQLite 테이블 가시화 다이어그램 | | 구축 담당자 | docs/schema/migrations.md | SQLite migration 적용 순서와 의도 |

환경 정보 제공 원칙

agentic-runtime은 환경 정보를 직접 소유하지 않습니다.

registry, 인증, 네트워크, 중앙 DBMS, Agent profile 같은 환경 정보는 이 패키지를 설치해서 사용하는 외부 실행 프로젝트가 제공합니다.

agentic-runtime
  - 환경 정보의 형식과 로딩 규칙을 정의
  - package 내부에 특정 환경 값을 고정하지 않음

consumer project
  - .npmrc
  - .env
  - agentic.config.*
  - CI/CD variables
  - network/profile 설정

역할

agentic-runtime
  - CLI entrypoint
  - package/module registry
  - module composition
  - lifecycle execution
  - Codex adapter bootstrap
  - SQLite migration composition
  - execution project scaffold
  - runtime context

agentic-runtime은 Agentic Platform 전체가 아닙니다. Agentic Platform은 전체 제품/체계명이고, agentic-runtime은 로컬 실행 기반 패키지입니다.

MVP 범위

초기 agentic-runtime의 범위는 의도적으로 작게 유지합니다.

1. workspace/package skeleton
2. local CLI entrypoint
3. project-local SQLite initialization
4. package migration composition
5. module registry
6. execution project scaffold

다음 항목은 초기 runtime 패키지 범위에 포함하지 않습니다.

- full workflow engine
- PostgreSQL sync implementation
- multi-agent orchestration
- web UI
- DOCX/PPTX/PDF rendering