Agent App is a draft standard for complete installable intelligent applications in the Agent standards ecosystem. It packages real app implementation - UI bundles, workers, app backend services, storage schemas, workflows, agent entries, Skills, Knowledge bindings, tool requirements, artifact contracts, policies, evals, presentation metadata, requirement boundaries, installation metadata, and App Server bridge contracts - without moving agent execution into the cloud or forcing every user through Lime Desktop.
Agent Runtime answers how tasks execute. Agent UI answers how interaction surfaces render. Agent Context answers how context is assembled. Skills answer how reusable work is done. Knowledge answers what trusted facts are. Tools connect external capabilities; Artifacts persist deliverables; Evidence, Policy, and QC make results trustworthy. Agent App answers how all of those become a complete installable application with host capabilities, UI, data boundaries, entries, lifecycle, requirement handoff, install modes, and App Server bridge mapping.
The runtime bridge is explicit: Agent App is the product package, the Capability SDK / Host Bridge is the app-facing API, Desktop Host IPC owns shell transport, and App Server JSON-RPC / RuntimeCore is the backend fact source. Users can still install an Agent App inside Lime Desktop, download it as a standalone branded app, or run it against a shared system Lime Runtime.
Agent App follows a mini-program style host model: apps are isolated packages, but user state and platform capabilities are shared through host-governed Capability SDK handles. Apps may own UI, workflow, app-local storage, and app backend services, but identity, session, model settings, secrets, billing, policy, files, artifacts, and agent runtime remain host-governed capabilities.
Agent App is the business workspace. Lime Agent is the intelligent runtime capability that apps orchestrate. Users should be able to finish a business workflow inside the app surface instead of being forced back into a generic chat UI. Chat and expert entries are valid app surfaces, but they are optional interaction modes rather than the required container for product work.
| Standard / layer | Owns | Entry point | Runtime behavior |
|---|---|---|---|
| Agent Runtime | Task lifecycle, model routing, sessions, checkpoints, event streams, structured output. | Runtime contract | Runs under host policy; App declares intent through app.runtime.yaml. |
| Agent UI | Pages, panels, commands, viewers, Host Bridge interaction surfaces. | UI descriptors / entries | Rendered in host-controlled surfaces through lime.ui. |
| Agent Context | Context assembly, budget, priority, compression, missing-context requests. | Context descriptors | Resolved by host/runtime for each entry or task. |
| Agent Skills | Reusable procedures, scripts, rubrics, and executable process fragments. | SKILL.md |
Activated by an agent after trust checks. |
| Agent Knowledge | Source-grounded facts, status, provenance, freshness, and safe context. | KNOWLEDGE.md |
Loaded as fenced data or retrieval context; never executed. |
| Agent Tool / Connector | External callable capabilities, MCP, CLI, API, browser adapters, auth, side effects. | Tool / connector descriptor | Invoked by Host/Cloud policy and evidence surfaces. |
| Agent Artifact | Durable deliverables, schemas, viewers, exporters, state. | Artifact schema | Stored and displayed by host artifact services. |
| Agent Evidence / Policy / QC | Provenance, permissions, risk, quality gates, audits, waivers. | Evidence, policy, eval descriptors | Enforced and recorded by Host/Cloud; App declares inputs and gates. |
| Agent Expert | Chat-first entry composed from persona, context, tools, and app state. | Expert entry | Runs inside a host conversation surface; optional App entry, not the App itself. |
| Agent App | Complete installable app package: UI, workers, app backend services, storage, workflows, entries, permissions, artifacts, evals, lifecycle, boundaries, install modes, and bridge profile. | APP.md + runtime package |
Runs in a compatible host through @lime/app-sdk capability handles. |
| App Server / RuntimeCore | Agent execution, session / turn facts, storage, tools, connectors, secrets, policy, evidence, artifacts, and local governance. | App Server JSON-RPC + lime.* projections |
Shared by Lime Desktop, Lime App Shell, runtime-backed apps, and compatible hosts. |
| Lime Host / Cloud | Local shells, sandbox, registry, tenant policy, OAuth, webhook, scheduled sync. | Host shell + lime.* capabilities |
Injected into apps as authorized handles; apps do not import host internals. |
| Area | Agent App owns | Lime owns |
|---|---|---|
| Product experience | Business UI, pages, tables, forms, dashboards, review steps, and delivery views. | Host shell, navigation, theme, locale, installation, and app lifecycle. |
| Business logic | Workflow state, domain rules, app backend service code, storage schema, structured result write-back, and human confirmation. | Agent task runtime, capability enforcement, retries, cancellation, cost limits, and telemetry. |
| User and platform state | Requested user / workspace / tenant projections and setup prompts. | Identity, session, OAuth, model settings, billing, policy, secrets, and capability availability. |
| Data boundary | App-local records, package assets, overlays, and references to workspace data. | Namespaced storage, files, Knowledge binding, secrets, database placement, cleanup, and audit. |
| Agent execution | Decides when to call an agent task and how the result updates product state. | Runs lime.agent tasks, model calls, tools, traces, artifacts, and evidence through SDK contracts. |
The boundary is intentionally strict: business should not leave the app context, and agents should not leave Lime capability governance. If an app bypasses Lime to build its own model gateway, permission system, or evidence store, it is becoming an independent SaaS instead of an Agent App. If an app sends users back to generic chat for core work, it is only a chat wrapper rather than a product-level app.
my-agent-app/
├── APP.md # required: discovery manifest + app guide
├── app.manifest.json # optional: separated machine manifest
├── dist/
│ ├── ui/ # optional: UI bundle and route manifest
│ ├── worker/ # optional: business workers and background jobs
│ └── tools/ # optional: packaged tool adapters
├── services/ # optional: app-owned backend services, possibly multi-language
├── storage/
│ ├── schema.json # optional: app namespace data model
│ └── migrations/ # optional: versioned migrations
├── workflows/ # optional: business workflows and state machines
├── agents/ # optional: expert-chat personas
├── skills/ # optional: bundled or referenced Agent Skill packages
├── knowledge-templates/ # optional: required knowledge slots and starter templates
├── artifacts/ # optional: output contracts, viewers, exporters
├── evals/ # optional: readiness and quality checks
├── policies/ # optional: permissions and data boundaries
├── app.runtime.yaml # optional: agent task runtime control plane and bridge profile
├── app.requirements.yaml # optional: requirements, MVP, non-goals, acceptance
├── app.boundary.yaml # optional: App / Host / Cloud / Connector / Human boundary
├── app.integrations.yaml # optional: Host/Cloud-managed external integrations
├── app.operations.yaml # optional: side effects, approvals, evidence
├── app.install.yaml # optional: in-Lime, standalone, runtime-backed install modes
├── overlay-templates/ # optional: tenant / workspace overlay schemas
├── app.lock.json # optional: package file hashes and signatures
└── examples/ # optional: sample workspaces, prompts, outputs
APP.md is not the app implementation. It is the discovery and review surface. Product-level functionality belongs in the runtime package and calls host services through the Capability SDK.
Compatible hosts share user state and platform capabilities across installed apps, but they do not give apps raw authority. A host snapshot may expose non-sensitive user, tenant, workspace, locale, theme, model profile, billing entitlement, and capability availability. It must not expose bearer tokens, refresh tokens, provider keys, plaintext secrets, host database handles, or internal filesystem paths.
Apps can declare their own storage namespace, schema, migrations, and app backend services. Backend services must say whether they are client-local services supervised by the desktop/client host or cloud-remote services governed as explicit server-assisted backends. The host may co-locate multiple app stores in one physical database engine, but the logical boundary must remain per app and per workspace or tenant. Host core state must stay separate from app-owned migrations. On desktop, per-app SQLite databases are the preferred default; on server, shared PostgreSQL instances may use per-app schemas or dedicated databases for high-risk apps.
Compatible hosts should expose versioned, authorized, mockable capabilities such as:
lime.uifor pages, panels, commands, settings, artifact viewerslime.storagefor app namespaces, tables, indexes, migrationslime.filesfor user-selected files and parsinglime.agentfor local agent tasks, streaming, retries, traceslime.knowledgefor Knowledge Pack binding and retrievallime.toolsfor Tool Broker / ToolHub invocationlime.connectorsfor Host/Cloud-managed MCP, CLI, API, browser, OAuth, webhook, and sync adapterslime.artifactsfor persistent deliverableslime.workflowfor business state and background taskslime.policyfor permissions, cost, risk, data boundarylime.evidencefor provenance and replaylime.secretsfor credentials without plaintext app accesslime.cloudSession,lime.modelSettings,lime.branding,lime.billing, andlime.appUpdatesfor shared desktop platform capabilities
Apps must not import host internals. They declare capability requirements in the manifest and receive runtime handles from the host. The layered manifest model keeps task runtime control, requirement boundaries, installation metadata, and agentRuntime.bridge outside business UI code, so hosts can map App tasks to App Server JSON-RPC without exposing transport internals.
agentRuntime.bridge.kind=app-server-json-rpc declares that lime.agent / lime.workflow calls flow through:
@lime/app-sdk / Host Bridge
-> Desktop Host IPC
-> App Server JSON-RPC
-> RuntimeCore / services
-> ExecutionBackend
Apps see SDK tasks, events, artifacts, and evidence projections. They do not spawn sidecars, read JSONL transport, call legacy desktop commands, or access provider keys.
| Mode | User experience | Runtime relationship |
|---|---|---|
in_lime |
Install and launch from Lime Desktop. | Uses the Desktop-hosted Lime Runtime. |
standalone |
Download a branded business app directly. | Bundles a compatible Lime Runtime profile through Lime App Shell. |
runtime_backed |
Install a lightweight app package. | Requires an already installed system lime-runtime. |
web_host |
Open in a compatible hosted environment. | Host provides web capability handles and policy. |
Compatible hosts should:
- Discover apps by
APP.md. - Verify package hash, signatures, manifest shape, and capability versions.
- Install or activate an app only after user, tenant, or workspace consent.
- Resolve declared UI, storage, workers, Runtime, Context, Skills, Knowledge templates, Tools, Connectors, Artifacts, Evidence, Policy, Evals, and permissions into host catalogs.
- Inject Capability SDK handles at runtime instead of exposing host internals.
- Keep agent execution inside the host runtime; cloud registries may distribute and authorize apps but must not become a hidden Agent Runtime.
- Keep customer data in Agent Knowledge packs, workspace files, app storage namespaces, secrets, or overlays rather than official app packages.
- Record app provenance on every projected entry, task, tool call, artifact, migration, and eval.
- Specification
- What is Agent App?
- Runtime package design
- Capability SDK
- Desktop host conformance
- Agent App and Standards Ecosystem Boundary
- Runtime model
- 中文规范
npx agentapp-ref validate ./my-agent-app
npx agentapp-ref to-catalog ./my-agent-app
npx agentapp-ref project ./my-agent-app
npx agentapp-ref readiness ./my-agent-app --workspace ./workspace
npx agentapp-ref migrate-check ./my-agent-app
npx agentapp-ref migrate-generate ./my-agent-appnpm install
npm run dev
npm run build