KedgeAgentic

Chinese Name (中文名称): 即见Agentic

An Agentic services platform. Developers describe business logic in Skills and connect tools via MCP; the platform manages the AgentEngine lifecycle (Claude Code / OpenCode / custom), session persistence, sandbox + workspace materialization, and tool orchestration.

For a complete codebase walk-through, start at CLAUDE.md. For phase-level status of in-flight architecture work see docs/ontology/PROGRESS.md.

Workspace packages

The monorepo is an npm workspace at the root. After cleanup C7 (2026-06-01), packages/ is grouped by layer (apps / libs-core / libs-nest / libs-client / mcp). Package-specific docs live in each package's CLAUDE.md or README.md; see docs/architecture/package-layering.md for the layering convention.

Apps (packages/apps/)

Package	Purpose	Port
@kedge-agentic/platform	NestJS platform server — sessions, skills, MCP pool, sandbox + workspace, ontology bridge, workflow engine	3001
@kedge-agentic/admin-next	React + Refine + shadcn/ui admin dashboard	5175
@kedge-agentic/chat-interface	Extensible chat UI component library (app + lib hybrid)	—

Framework-free libs (packages/libs-core/)

Package	Purpose
@kedge-agentic/ontology	Zod-first ontology schema package — ObjectTypeDef, ManifestDef, ActionDef, ObjectSetDef primitives
@kedge-agentic/workflow	Declarative workflow engine — trigger registry, cascade context, dispatch pipeline
@kedge-agentic/workflow-client	HTTP client for the platform workflow ingest + dashboard APIs
@kedge-agentic/context-layer-core	EntityRegistry, DocumentEditProvider, recommend/router/injector primitives
@kedge-agentic/harness-core	Harness orchestrator + task registry + event stream
@kedge-agentic/agent-runtime-core	Workspace + artifact + sync runtime (framework-free; renamed from agent-runtime in cleanup C3)
@kedge-agentic/observer-storage	Storage-layer types + TypeORM entities for observations (renamed from observer-engine in cleanup C4)
@kedge-agentic/entity-document	Block ↔ Markdown bidirectional transforms
@kedge-agentic/common	Shared types + Zod schemas

NestJS bindings (packages/libs-nest/)

Package	Purpose
@kedge-agentic/ontology-nest	NestJS adapter for @kedge-agentic/ontology
@kedge-agentic/workflow-nest	NestJS adapter for @kedge-agentic/workflow
@kedge-agentic/harness-nest	NestJS adapter for @kedge-agentic/harness-core
@kedge-agentic/context-layer-nest	NestJS adapter for @kedge-agentic/context-layer-core
@kedge-agentic/solution-backend-nest	Solution-side of the ontology bridge protocol — controllers + guards + broadcaster

Client bindings (packages/libs-client/)

Package	Purpose
@kedge-agentic/react-sdk	React hooks for agent integration
@kedge-agentic/vue-sdk	Vue composables for agent integration
@kedge-agentic/context-layer-react	React picker UI on top of context-layer-core

MCP subprocess servers (packages/mcp/, all stdio subprocesses bundled into platform/dist/): attach-file-server · rest-adapter-bridge · shared-context-server · tool-caller-proxy-server.

Archive: @kedge-agentic/vfs-poc — design + validation reference for agentfs overlay + just-bash sandbox.

Solution-specific code lives under solutions/. Each solution can additionally publish a workspace package of platform handlers — for example @kedge-agentic/live-lesson-platform-extension is loaded into the platform via the PLATFORM_EXTENSION_PACKAGES env var, keeping @kedge-agentic/platform solution-free.

Architecture sketch

┌──────────────────────┐    ┌────────────────────────────┐    ┌──────────────────────┐
│ Frontend clients     │◄──►│ @kedge-agentic/platform     │◄──►│ AgentEngine subproc  │
│ (admin-next /        │    │ - sessions / skills / MCP  │    │ (claude / opencode / │
│  solution frontends) │    │ - sandbox + workspace      │    │  custom)             │
│  via react-sdk /     │    │ - ontology + workflow      │    │                      │
│  vue-sdk / SSE       │    │ - PLATFORM_EXTENSION_PACKAGES│    │                      │
└──────────────────────┘    │   loads per-solution mods  │    └──────────────────────┘
                            └────────────────────────────┘
                                       ▲
                                       │ HTTP / shared types
                                       │
                            ┌──────────┴───────────────────┐
                            │ Solution backends (e.g.      │
                            │ live-lesson :3007), platform │
                            │ handler packages, MCP servers│
                            └──────────────────────────────┘

For the platform/sandbox runtime detail (workspace provider, materializer, sandbox bash, REST API), start at gitbook → Runtime 架构. For ontology + workflow rewrite detail, see docs/ontology/PROGRESS.md and the Ontology & Workflow gitbook section.

Quick start

Prerequisites

• Node.js >= 18
• npm >= 9
• Claude CLI installed + authenticated (claude --version)

Install + build

npm install
npm run build           # builds all packages in dependency order via build:libs → build:backend → build:admin

build:libs chains common → agent-runtime-core → ontology → workflow-client. Build order matters — those four ship .d.ts consumed by every other package.

Develop

npm run dev:backend     # NestJS on :3001
npm run dev:admin       # admin-next on :5175

To boot the platform with a solution's handler bundle loaded:

PLATFORM_EXTENSION_PACKAGES=@kedge-agentic/live-lesson-platform-extension \
  npm run dev:backend

Test

npm test                # all workspaces
cd packages/apps/platform && npx jest --no-coverage      # platform only (fast feedback)

API key + multi-tenant model

KedgeAgentic uses a two-tier API key system: a bootstrap admin key (platform operator) creates per-solution builder keys (sk-<slug>-…, SHA-256 hashed, scoped + rate-limited + audited). Builders use their key server-side to register skills + MCP servers + create end-user API keys; the browser never holds the master key.

For the full step-by-step (bootstrap key, creating a tenant/solution, creating a builder key, registering skills, calling chat), follow docs/BUILDER_TUTORIAL.md. The shell helpers in tools/solution-lib.sh wrap the bootstrap flow.

The ccaas-proxy pattern (browser → solution backend → ccaas backend, key held server-side) is canonical for solution frontends; the live-lesson backend's CcaasProxyController + CcaasChatProxyController are the worked example — see solutions/business/live-lesson/CLAUDE.md.

Documentation

Codebase navigation

• CLAUDE.md — monorepo map, build order, conventions, per-package guides
• packages/apps/platform/CLAUDE.md — platform backend internals (solution-free boundary, AppModule factory, handler package loading)
• packages/apps/admin-next/CLAUDE.md — admin dashboard (Refine + shadcn/ui)

Architecture + status

• docs/ontology/PROGRESS.md — phase status tracker (ontology, workflow rewrite, platform decoupling)
• docs/CHANGES_2026-05.md — runtime + sandbox sprint catch-up (Stage-1 sandbox, asset materialization, agent-runtime extraction)
• docs/AGENT_RUNTIME_DESIGN.md — full design vision for the runtime layer
• docs/CONVENTIONS.md, docs/WORKFLOW.md, docs/DEVELOPMENT_PRINCIPLES.md
• docs/adr/ — Architecture Decision Records

Deployment + integration

• docs/DEPLOYMENT.md — on-prem deployment guide
• docs/BUILDER_TUTORIAL.md — solution builder onboarding
• docs/SOLUTION_TEMPLATE.md + docs/SOLUTION_BEST_PRACTICES.md
• packages/apps/platform/docs/AUTHENTICATION_AND_AUTHORIZATION.md
• packages/apps/platform/docs/ERROR_HANDLING.md

GitBook

• docs/gitbook/zh/ — comprehensive Chinese reference (platform, ontology, runtime API, solution authoring)
• docs/gitbook/en/ — English parallel

Landing page

• landing/ — 即见 Agentic marketing site source (single-page + 5 methodology detail pages + 1 case study). Vanilla HTML/CSS/JS, no build step. Preview locally with cd landing && python3 -m http.server 8080. See landing/README.md.

License

MIT