Composable Mini-Apps

Rule

Prefer many one-job apps in a workspace over one oversized app. A headless app
can own a provider, dataset, workflow, or specialist action surface without a
full UI; the main agent composes those apps through discovery and A2A.

Shape

• Give each mini-app one clear job, a concise package.json description, and
  action names that describe the job it owns.
• Keep provider credentials and upstream API details in the app that owns that
  provider or workflow. Other apps should delegate to it instead of copying its
  integration code.
• Use a tiny status/config screen only when users need to inspect state. A
  pure headless app is fine when its job is invoked by agents, automations, or
  sibling apps.
• If two workflows only share a helper, put the helper in packages/shared;
  keep the workflow actions in separate apps.

Discovery And Invocation

The main agent should discover available siblings before assuming capability:

• Runtime agents receive an <available-apps> block built from
  discoverAgents(). Workspace siblings are layered in by
  discoverWorkspaceAgents(). It carries one line per app — enough to know a
  sibling exists, not enough to know what it can do.
• Use the built-in describe-workspace-apps tool for actual capability.
  It reads each peer's live /.well-known/agent-card.json and returns its
  purpose plus any optional stable machine contracts; pass app: "<id>" for
  one peer's full description. Call it before building something a sibling may
  already own, before telling a user what is or is not possible across apps,
  and whenever someone asks which app to use for a job.
• Never hand-maintain a markdown or code list of what each workspace app does.
  A stale catalog is worse than none: it reads as authoritative while pointing
  at capabilities that moved or vanished. An app's purpose belongs in its own
  package.json description (which flows into the workspace manifest and the
  <available-apps> block), and its capabilities belong in its exposed
  actions — both of which describe-workspace-apps reads live.
• UI shells, headless surfaces, and scripts can read the same registry through
  GET /_agent-native/agents?selfAppId=<app-id>.
• Code or CLI callers should use the first-class message-based A2A invocation
  path (invokeAgent() / agent-native invoke) when they need to ask an app
  by id, name, or URL.
• In the agent loop, use call-agent with the sibling app id when another app
  owns the work or data. Never call the current app through call-agent; use
  local actions instead.
• Send a natural-language objective by default so the sibling can apply its own
  instructions, skills, schemas, data dictionary, credentials, and tools.
  invokeAgentAction() or call-agent with action + input is only for an
  explicit stable semantic read contract whose complete input is already known.
  Never expose or call an implementation action as a workaround for slow or
  failed message delegation.

Send narrow prompts to siblings: name the exact question, relevant ids, date
ranges, and expected output shape. Preserve returned ids and URLs verbatim.

Artifact Handoff

Mini-apps should hand off compact artifacts, not giant pasted transcripts or
provider dumps. When a mini-app creates something another app may use, return
or store an artifact with:

• artifactType - what kind of output this is, such as deal-set,
  call-evidence, brief, dashboard, or report.
• artifactId - the stable app-owned id, file path, or resource id.
• createdAt - an ISO timestamp.
• source - provider/app/source ids used to create it.
• summary - a short human-readable explanation.
• items or records - the bounded structured data downstream apps need.
• links - fully qualified URLs for user-visible artifacts.

Downstream apps should receive artifact ids, URLs, and narrow follow-up
questions. If a downstream app needs more detail, it should call back to the
artifact-owning app instead of asking the orchestrator to paste the whole
corpus into a prompt.

Example: hubspot-pipeline returns { artifactType: "deal-set", artifactId: "hubspot-pipeline:deal-set:2026-06-18" }. deal-brief passes
that id to gong-evidence, which returns a call-evidence artifact id and
URLs. deal-brief then synthesizes the final brief from the artifact ids and
bounded summaries.

Provider APIs

Provider-specific actions are shortcuts, not limits. When the upstream API can
answer the question better than a first-class shortcut, call
provider-api-catalog and provider-api-docs as needed, then
provider-api-request against the real provider endpoint. For broad joins,
searches, or absence claims, stage the bounded corpus with stageAs and reduce
it with query-staged-dataset or code.

When composing apps, make the provider-owning mini-app do those
provider-api-request calls. The orchestrator should delegate a bounded job;
it should not reimplement every provider endpoint locally.

Example

For a sales-intelligence workspace, split the job into small apps:

App	Owns	Calls
hubspot-pipeline	CRM deals, contacts, companies, associations	provider-api-request with provider hubspot
gong-evidence	Calls, transcripts, snippets, speaker evidence	provider-api-request with provider gong
knowledge-base	Internal docs, pricing rules, playbooks	local search/read actions
deal-brief	Orchestration and final brief	message-based invokeAgent() or call-agent to the three apps

Flow: deal-brief asks hubspot-pipeline for the target account and open
deals, asks gong-evidence for recent transcript evidence about those deals,
asks knowledge-base for relevant playbook guidance, then synthesizes the
answer. That is a HubSpot→Gong→knowledge-base chain made of focused apps,
not a single app that clones every provider integration.

Don't

• Do not clone Mail, Calendar, Analytics, Brain, Assets, or another first-party
  app just to reuse its data. Delegate or link to the existing app.
• Do not hide a multi-provider workflow inside a giant "misc tools" app.
• Do not add one-off provider endpoints when provider-api-request can express
  the upstream API safely.
• Do not create wrapper routes that only re-export another app's action or A2A
  result.

Related Skills

• a2a-protocol - How apps expose and call A2A endpoints.
• actions - How each mini-app exposes its own operation surface.
• external-agents - How external MCP hosts route through workspace apps.
• storing-data - How app-owned data stays SQL-backed and portable.