Agents and Extensions

High-level guide to Aster primitives, marketplace repos, and gateway distributions.

Choose the right surface

Use agents when you want a dedicated run loop, prompts, and tool set for a specific worker. In Aster, agents are declared by extensions rather than installed as their own marketplace primitive.
Use tool packages when you want users to import standalone callable tools with normal npm dependencies and a lightweight manifest.
Use extensions when you need runtime-facing integrations such as mounts, settings, prompt hooks, long-lived runtimes inside a space, or one or more extension-owned agents.
Use plugins when the integration must live at the host/runtime layer: provider integrations, auth flows, user/runtime services, gateway routes, or extension bridging.
Use skills when you want reusable runtime prompt/instruction packs that can be enabled per user or per space.
Use gateway distributions when you want a packaged product graph that bundles spaces, plugins, extensions, tools, skills, apps, routes, auth, database, analytics, observability, and marketplace sources.

Marketplace repos and distributions

Aster publishes primitives through marketplace repos.

A marketplace repo is registered from either a local folder or a pinned GitHub ref.
The repo root can publish a marketplace.json catalog.
That catalog can expose direct-install tool packages, extensions, plugins, skills, apps, and future distribution modules.
Marketplace entries are browsable/installable sources. They do not imply installed state.
The active gateway distribution owns bundled spaces and defaults.

Agents

Aster agents run against the host runtime, but they are now owned by extensions. The runtime owns orchestration, permissions, space state, and container execution while @aster/agent defines the authoring surface and @aster/authoring declares how those agents are surfaced to spaces.

Install the agent authoring package:

npm install @aster/agent

@aster/agent provides Agent.make() for agent definitions, tool() for typed, validated tool definitions, and the underlying runtime types and turn-processing primitives.

See:

Tool packages

Tool packages are the lightweight import surface for standalone tools. They are standard npm packages with their own package.json plus a manifest.json file that Aster reads during local import or marketplace installation.

Install the agent authoring package:

npm install @aster/agent

@aster/agent provides Tool.make() for imported tool packages and the same tool() helper shape used by @aster/agent.

See:

Agent reference

Extensions

Extensions are the runtime-facing mechanism for adding capabilities and integrations. They are also the installable surface for declaring agents, skills, and subagents. @aster/authoring exposes primitives for building these safely.

Extensions can be imported from a local folder, installed from a marketplace repo, or bridged into spaces by plugins.

Install the authoring package:

npm install @aster/authoring

@aster/authoring provides Extension.make() for declaring extensions with lifecycle hooks such as filesystem mounts, tool registration, system prompt sections, raw system prompt append, full system prompt override, prompt interception, and long-lived runtimes with event ingress.

See:

Plugins and skills

Plugins live one layer above extensions. They are the host/runtime integration surface for things like model providers, auth methods, runtime services, custom gateway routes, and extension bridging. Plugin packages can be installed directly from marketplace repos just like other primitives.

Skills are reusable runtime prompt and instruction packs. Some are installed from marketplace repos, some are provided through extensions, and others are available from local package sources. Their runtime model is covered in the Aster specification.

See:

Relationship overview

@aster/agent provides the agent definition contract, low-level runtime types, and turn primitives for extension-owned agents.
@aster/agent provides standalone imported tool-package definitions.
@aster/authoring provides richer runtime integration hooks inside spaces.
@aster/authoring provides host/runtime integration and extension-bridging primitives.
Marketplace repos package primitives for installation.
Gateway distributions are the product assembly layer.
@aster/sdk is the generated gateway client and is a separate concern from authoring packages.

Operational context

When you are debugging behavior, the most useful technical references are:

These pages stay canonical in their package locations and are synced into the site so the public docs can point to them without forking the source of truth.