Appspec reference

Every field of an Appspec (schema: loop.app/v1), what it means, its default, and an example taken from an application of the catalogue. Nothing is written for a field at its default.

The application

Field	Type	Meaning	Default
schema	loop.app/v1	The version of the spec itself	"loop.app/v1"
id (required)	text	Unique application identifier	—
version	text	Application version	"0.0.1"
name (required)	text	Display name	—
kind (required)	AppKind	chat, widget, decision or worker	—
description	text	What it does, in a sentence	empty
owner	text	Who answers for it	empty
agent	text	The agent or the Cog that does the work, id or id:version	empty
team	text	Or a team of them, id or id:version	empty
instructions	text	What this application tells its agent, on top of its own	empty
model	text	The model, when it is not the organization's default	empty
skills	list of text	Skills it adds to its agent's	—
backend_tools	list of text	Backend tools of the catalogue it adds to its agent's	—
tools	list of AppTool	Tools of its own, written in its code (@app.tool): the agent calls them, rules decide them	—
context	list of text	The Frames it works under: the catalogue's, or its organization's own (org-…)	—
contents	list of text	The documents and datasets it answers from	—
connections	list of AppConnection	What it reaches	—
protocols	list of text	The agent protocols it speaks, ids of the protocols catalogue: its pap, pact, signed_fetch and a2a blocks, and each merchant of commerce, are refused unless their protocol is listed, and a planned protocol only while it is not offered	—
ui	list of UiChoice	Its UI plugins, each {plugin, renderer}: a plugin of agentspecs/ui, each once, and the renderer of agentspecs/ui-renderers it is exposed through, when it is — one the plugin may be exposed through, and one that is not enabled only while the application is not offered	—
pap	AppPap	Personal Agent Protocol: companies it works with, or being one	—
pact	AppPact	PACT: businesses it asks for each person	—
commerce	AppCommerce	UCP and ACP: merchants it shops at for each person	—
signed_fetch	AppSignedFetch	Web Bot Auth: the sites it reads pages of, GET only, each request signed with its key	—
pair	AppPair	One of a pair of examples: a PACT business, or the personal agent that asks it	empty
a2a	AppA2A	A2A: the extensions its Agent Card advertises	—
rules	list of AppRule	When it acts alone, and when it asks	—
permissions	AppPermissions	What else it may reach: Spaces, its computer. Nothing, unless said	—
interface	AppInterface	What the user sees	—
tests	AppTests	How it is verified	—
record	AppRecord	What is kept of what it did	—
checks	AppChecks	Optional checks from the catalogue	—
deployment	AppDeployment	Where it goes	—
goal	text	For a worker: what it works toward	empty
triggers	list of AppTrigger	For a worker: what starts its work	—
memory	text	A memory of the catalogue, when it remembers	empty
notifications	list of text	Where an approval reaches a person	—
decision	AppDecision	For a decision: what it decides	empty
samples	AppSamples	What it is tried on before it is anybody's: published with it by Datalayer, read only	—
enabled	true or false	Whether it is offered today	true
unavailable_because	text	Why it is not offered today, in a sentence its page shows: said when enabled is false, and only then	empty
tags	list of text		—
icon	text	Icon identifier	"apps"
emoji	text	Its face: one emoji, shown wherever the application appears	"👀"
avatar	text	Its avatar, as people keep theirs on their profile: emoji:<emoji>, or @datalayer/icons-react:<Name>Icon for a drawing of the set. Its emoji stands for it when unsaid, and where only text goes	empty
banner	text	Its banner, by name, from the set people choose theirs from on their profile. The one its id seeds when unsaid	empty

Examples

Each from an application of the catalogue, as its file writes it.

schema

schema: loop.app/v1

id

id: accounting

version

version: 0.0.2

name

name: Accounting

kind

kind: chat

description

description: Answers requests for financial reports, such as open invoices, aged balances,
  a trial balance or a customer's ledger, from the Odoo books, which it only reads.

owner

owner: Datalayer <info@datalayer.io>

agent

agent: worker-accountant:0.0.1

instructions

instructions: 'You answer requests for financial reports. They usually come from the
  Sales application over A2A, and you answer them from the Odoo books, which you reach
  through the odoo-accounting tools and only read. Use the tools for every figure:
  list, get, trial balance, general ledger, partner ledger, aged balance, open balances.
  Answer with the report itself: its period, its currency, the company it is for,
  the figures as the books hold them, and the tool each figure came from. When a request
  does not say its period or whom it is about, take the current fiscal year and the
  default company and say that you did. When the books do not hold the answer, or
  a tool is refused, say so plainly and do not fill the gap. Never write to Odoo:
  never create, post, reconcile, book, match, lock or delete anything, and do not
  offer to. A request to change the books is answered with what a person would have
  to do, not done.'

connections

connections:
- server: odoo-accounting:0.0.1
  access: read
  as: owner

rules

rules:
- action: Read the books
  applies_to: read
  behaviour: do_it
- action: Change the books
  applies_to:
  - write
  - delete
  behaviour: ask_first

ui

ui:
- plugin: chat
- plugin: a2ui-surface
  renderer: a2ui

interface

interface:
  layout: chat
  accent: green
  avatar: wizard
  welcome: 'Ask me for a report from the books: open invoices, aged balances, a trial
    balance or a customer''s ledger. I read Odoo; I change nothing.'
  outputs:
  - text/markdown
  - application/x-ipynb+json
  - application/json+a2ui
  starters:
  - label: Open invoices
    message: List the customer invoices that are still open, with the total due.
  - label: Aged receivables
    message: Give the aged receivables as of today, by customer.
  - label: Trial balance
    message: Give the trial balance for last month.

tests

tests:
  ready_at: 0.8
  cases:
  - ask: List the customer invoices that are still open, with the total due.
    expect: It reads the open invoices with the odoo-accounting tools and answers
      with each invoice, its amount due, the total and the currency.
  - ask: Give the trial balance for last month.
    expect: It answers with the trial balance for the previous month and says the
      company it is for.
  - ask: Post the draft invoice INV/2026/0042.
    expect: It does not post it. It says that it only reads the books and what a person
      would have to do.
  - ask: What is the revenue of a company that is not in Odoo?
    expect: It says the books do not hold it, and invents nothing.
  verified:
    live:
    - 'Answered live over A2A on a developer''s machine (2026-10-06), asked for the
      open customer invoices: it read the aged receivables from the Odoo books and
      said that the list of invoices had failed. One column total of its table was
      wrong, so its first test does not pass yet.'
    recorded: []
    unverified:
    - 'Its tests have not been run as a set: no validation run is attached to it.'

record

record:
  keep_for: 30_days
  include:
  - conversations

deployment

deployment:
  hosted:
    visibility: private

tags

tags:
- example
- accounting
- finance
- odoo
- a2a
- team

icon

icon: book

emoji

emoji: 🧾

tools

tools:
- name: read_books
  description: Reads a signed-in client's books.
  parameters:
    type: object
    properties:
      period:
        type: string
    required:
    - period
  does:
  - read

protocols

protocols:
- pap

pap

pap:
  profile: draft-01
  company:
    enabled: true
    signed_out: false
    interfaces:
    - agent
    scopes:
    - name: books:read
      description: Read your books and balances
      changes: none
      personal_data: true
    personal_agents: any
  connections:
  - id: northwind
    company: northwind.example
    access: write
    as: user
    scopes:
    - accounts:read
    - payments:write
    interfaces:
    - agent
    sign_in:
    - device
    extensions:
    - operations

enabled

enabled: false

unavailable_because

unavailable_because: It is one of the Personal Agent Protocol's recorded journeys
  written as an application, and it has not run in the Studio against a company yet.

contents

contents:
- The repository it is lent, read only

permissions

permissions:
  computer:
    files: true
    repository:
      url: https://github.com/datalayer/jupyter-kernel-client
      revision: 69a6f130189ab9229fb888ca48755c76e99ccf39

context

context:
- customer-research:0.0.1

decision

decision:
  question: Which anomalies in this dataset should we fix first?
  decision_model: cloudflare:wrk/typesafe/jev
  min_confidence: 0
  criteria:
  - name: Rows affected
    kind: metric
    weight: 2
    instructions: How many rows the anomaly touches, from a validation run in the
      sandbox.
    direction: higher
  - name: Effect on the result
    kind: metric
    weight: 3
    instructions: How far the headline figures move when the anomaly is corrected.
    direction: higher
  - name: Kind of anomaly
    kind: choice
    weight: 0
    instructions: What is this anomaly?
    options:
    - 'Genuine: a real extreme, to keep'
    - 'Outlier: a value far from the rest, to check'
    - 'Unit: a unit mismatch'
    - 'Missing: a missing value'
    - 'Duplicate: the same row twice'
    direction: higher
  - name: Safe to correct automatically
    kind: noul
    weight: 1
    instructions: Can the proposed correction be applied without a person checking
      each row?
    direction: higher

samples

samples:
  alternatives:
  - name: Prices in cents
    evidence: In the sample orders dataset (12,480 rows), 38 rows from the EU shop
      carry a unit price one hundred times the catalogue price — 1999 for an item
      listed at 19.99 — all imported by the same job on 4 March. Divided by one hundred,
      each matches its catalogue price to the cent. Corrected, total revenue falls
      by 6.1%.
    metrics:
      Rows affected: 38
      Effect on the result: 6.1
  - name: Duplicate orders
    evidence: 96 order ids appear twice with identical lines, timestamps and amounts,
      all from a retried upload on 19 April. No order id appears three times. Removing
      the second copies lowers total revenue by 0.9%.
    metrics:
      Rows affected: 96
      Effect on the result: 0.9
  - name: Missing region
    evidence: 1,032 rows have an empty region, all imported on 2 March from the partner
      channel; their shipping addresses are filled in and name a country in every
      case. Total revenue does not move; revenue by region moves by up to 4.5% once
      the region is read from the address.
    metrics:
      Rows affected: 1032
      Effect on the result: 4.5
  - name: Very large orders
    evidence: 11 orders exceed 40,000 in value, the largest at 182,000. Each is from
      an account marked as a reseller, and each has an invoice and a delivery record
      that match its amount. Left out, total revenue would fall by 9.8%, but nothing
      suggests they are wrong.
    metrics:
      Rows affected: 11
      Effect on the result: 0

backend_tools

backend_tools:
- decide:0.0.1

pair

pair:
  id: guest-desk
  role: personal_agent

pact

pact:
  business:
    enabled: false
    scopes:
      profile:read: See who you are here

goal

goal: Keep my inbox sorted, draft the replies, and never send without my approval.

triggers

triggers:
- type: event
  event: email_received
  description: When a message arrives
  prompt: A message arrived. Read it, sort it — label it, archive it when it needs
    no answer — and draft the reply it needs. Send nothing yourself.
- type: schedule
  cron: 0 8 * * *
  description: Every morning at 8
  prompt: Give me the digest of what arrived, what you sorted, and what waits for
    me.

memory

memory: mem0

notifications

notifications:
- email

checks

checks:
  guards:
  - required-frame-guard:0.0.1
  - permission-guard:0.0.1
  - data-source-authorization-guard:0.0.1
  - tool-use-policy-guard:0.0.1
  - sensitive-data-guard:0.0.1
  - confidence-guard:0.0.1
  - schema-guard:0.0.1
  - source-grounding-guard:0.0.1
  - consensus-guard:0.0.1
  - expert-sampling-guard:0.0.1
  - regression-guard:0.0.1
  - outcome-guard:0.0.1
  gates:
  - configuration-check:0.0.1
  - sensitive-data-stop:0.0.1
  - tool-violation-retry:0.0.1
  - low-confidence-review:0.0.1
  - unsupported-claims-revision:0.0.1
  - consensus-disagreement-review:0.0.1
  - release-approval:0.0.1
  - quality-drift-review:0.0.1
  track: financial-reporting:0.0.1

commerce

commerce:
  merchants:
  - id: example-store
    protocol: ucp
    merchant: store.examples.datalayer.run
    access: write
    limit:
      amount: '50'
      currency: USD
  - id: example-outfitters
    protocol: acp
    merchant: outfitters.examples.datalayer.run
    access: write
    limit:
      amount: '150'
      currency: USD

signed_fetch

signed_fetch:
  sites:
  - id: example-verifier
    site: verify.examples.datalayer.run

team

team: analyze-support-tickets:0.0.1

a2a

a2a:
  extensions:
  - uri: https://shop.example/extensions/gift-wrap/v1
    description: Wraps an order as a gift.
    required: false
    params:
      papers:
      - red
      - gold

model

model: bedrock:us.anthropic.claude-sonnet-4-6

skills

skills:
- crawl:0.0.1

avatar

avatar: '@datalayer/icons-react:AstronautIcon'

banner

banner: SvgTutorialsHero

Parts

AppA2A

A2A: what the application's Agent Card says beside its name and skill.

Field	Type	Meaning	Default
extensions	list of AppA2AExtension	Extensions its card advertises, besides the runtime's own	—

AppA2AExtension

An A2A extension the application's Agent Card advertises (A2A 1.0 Extensions), beside the runtime's own. Named by its URI, as capabilities.extensions writes it; its params are published on the card as they are, so they never hold a credential. Datalayer's own extensions (orchestration, the face) are the runtime's, never declared here.

Field	Type	Meaning	Default
uri (required)	text	The extension's URI: https://example.com/ext/gift-wrap/v1	—
description	text	What it adds, for whoever reads the card	empty
required	true or false	Whether a client must support it to talk to the application at all	false
params	mapping	Its parameters on the card, as the extension defines them; public	—

AppAction

An action of its code a person presses (@app.action, RU-5). What its payload is, typed: the JSON Schema of an object, written from the pydantic model its code declares (@app.action(name, payload=Model)); an action declaring none takes nothing. The runtime offers it only where a display showed it, or to the session that runs it, each press with a token; a press of an action not declared here is refused, and its payload is checked against this schema before its code runs.

Field	Type	Meaning	Default
name (required)	text	Its name, as its button presses it	—
description	text	What it does, in a sentence	empty
payload	mapping	The JSON Schema of what it is pressed with, an object; none when it takes nothing (a press with anything is then refused)	empty

AppChecks

Optional: checks from the catalogue, for a builder who wants them — and its code's own.

Field	Type	Meaning	Default
guards	list of text	Guards, id or id:version	—
gates	list of text	Gates, id or id:version	—
track	text	A Track, id or id:version	empty
code	list of AppCodeCheck	Checks written in its code (@app.check), each run at its stage	—

AppCodeCheck

A check written in the application's code: @app.check. Run at its stage beside the built-in checks and the catalogue's Guards; what it refuses is said in its own sentence. Without its file nothing runs it, and validation says so.

Field	Type	Meaning	Default
name (required)	text	The function of its code that checks, by name	—
on (required)	CheckStage	answer or tool_call: where it runs	—
description (required)	text	What it checks, in a sentence a person reads	—

AppCommand

A slash command the user picks in the composer. Typing / lists the application's commands; picking one sends its prompt, {input} replaced by the words typed after the command.

Field	Type	Meaning	Default
name (required)	text	What follows the slash: lower-case letters, digits and hyphens, a letter first (summarise)	—
description (required)	text	What the composer's menu says it does	—
prompt (required)	text	What is sent when it is picked: {input} stands for the words typed after it; without {input}, those words follow the prompt. An application's code answers /<name> {input} itself (@app.command)	—

AppCommerce

Commerce: the merchants it shops at for each person.

Field	Type	Meaning	Default
merchants	list of AppCommerceMerchant	Merchants, over UCP or ACP: test merchants only for now	—

AppCommerceMerchant

A merchant the application shops at for each person, over UCP or ACP. Decided 2026-10-13: test merchants only, with no real payment — a purchase is always asked of the person first (Ask me first), as the exact checkout, and made at most once; Datalayer's gateway pays with a test instrument and refuses any merchant it does not know as a test one. Named by its domain (its profile at /.well-known/ucp, or /.well-known/acp.json), always in each person's own name. No credential is ever part of a spec.

Field	Type	Meaning	Default
id (required)	text	Stable within the application: example-store	—
protocol (required)	CommerceProtocol	ucp or acp	—
merchant (required)	text	The merchant's domain: store.example	—
access	Access	How far: read (searches and reads its checkouts), or write (also fills a checkout and buys, each purchase asked of the person)	"read"
limit	AppSpendLimit	The most one purchase may cost there: required for write	empty

AppComputer

What the application may do on its own computer. Each is off until it is turned on.

Field	Type	Meaning	Default
browse	true or false	Open pages in a browser	false
files	true or false	Read and write files	false
shell	true or false	Run commands	false
repository	AppRepository	A repository lent to it, checked out as its workspace	empty

AppConnection

Something the application reaches.

Field	Type	Meaning	Default
server (required)	text	An MCP server of the catalogue, id or id:version	—
access	Access	How far: read, or write	"read"
as	ActsAs	In whose name: owner (the builder's account) or user (each user's own)	"owner"
only	list of text	The tools of the server the application may use, by name or pattern (*gmail*: * is any run of characters, ? any one); all of them when empty. A tool left out is not reached at all	—

AppCriterion

What an alternative is weighed on.

Field	Type	Meaning	Default
name (required)	text	Its name	—
kind	CriterionKind	metric, noul, choice, score	"metric"
weight	number	How much it counts	1
instructions	text	What a decision model is asked, or how a metric is computed	empty
options	list of text	For a choice or a score: from the worst to the best	—
direction	text	Whether more counts for, or against	"higher"
measure	text	For a metric: what a benchmark run fills it from	empty

AppCustomComponent

A component the developer writes, an A2UI component of this application only: the catalog grows for it, it does not open. Reviewed like any component of the catalog — its properties a JSON Schema, what it shows and sends bindings into the page's data — and drawn in a sandboxed frame of no origin, its module loaded from source and nothing else: what it is given is its properties and data, and what it gives back is what it sends.

Field	Type	Meaning	Default
name (required)	text	Its name on a surface, as a catalog component's (Gauge); none of the catalog's own	—
description (required)	text	What it is for, in a sentence: what the palette says	—
props	mapping	Its properties, as the JSON Schema of an object: each typed string, integer, number, boolean, array or object, or an enum of words, with its title, description and default; required among them	—
shows	list of text	What it shows from the page's data: each a binding, given a path or a value in place	—
sends	list of text	What it sends back: each a binding it writes, then its action dispatched	—
source (required)	text	Its module, a built ES module whose default export draws it (export default function (root, {props, send})): an address over https://, or http://localhost while it is written; or a file of the application's folder, by its path in it (gauge.js), packaged with the application and served by the server its package is installed beside	—
integrity	text	The module as it was reviewed: its Subresource Integrity hash (sha384-…); a module that differs is not drawn. Any module at the address when unsaid	empty
height	integer	Its height on the page, in pixels	240
example	mapping	A configuration of it its schema accepts: what the palette previews	empty

AppDecision

What a decision application decides.

Field	Type	Meaning	Default
question (required)	text	The question it answers	—
alternatives	list of text	What is chosen between	—
criteria	list of AppCriterion	What each is weighed on	—
min_confidence	number	An answer less confident than this is put to the reader	0
scenarios	list of AppScenario	Named sets of weights	—
decision_model	text	The model that answers the decision's typed questions	empty

AppDeployment

Where the application goes.

Field	Type	Meaning	Default
hosted	HostedDeployment	At an address of its own	empty
embedded	EmbeddedDeployment	Inside another product	empty

AppFieldTranslation

A field of the settings in another language.

Field	Type	Meaning	Default
title	text	Its title	empty
description	text	What it is for	empty
options	mapping of text	What each value of its enum (or of its items') reads as, by the value; the value is sent	—

AppInterface

What the user sees.

Field	Type	Meaning	Default
layout	Layout	chat, page or split; the kind's own when unsaid	empty
accent	Accent	The application's one colour, over whichever theme it runs in; unsaid, it wears the theme's own colours	empty
theme	AppTheme	The theme it runs in by default, at its address, embedded, in the Studio's Preview and as an example: a variant and, optionally, a colour mode. The person's own when unsaid. Its accent, when it names one, colours it, whichever theme it is	empty
welcome	text	What the application says first	empty
starters	list of AppStarter	First messages offered to the user	—
commands	list of AppCommand	Slash commands the user picks in the composer: typing / lists them	—
modes	list of AppMode	Mode switches in the composer: the option picked goes with every run, its instructions told to the agent and its model run on	—
actions	list of AppAction	The actions of its code a person presses (@app.action, RU-5), each with the JSON Schema of its payload: what its buttons offer, with a token, and nothing else	—
profiles	list of AppProfile	Several assistants in one application, two at least: the person picks one before the conversation starts — the first unless they do — and keeps it to the end; its instructions, model and starters go with every run. None when unsaid	—
settings	mapping	What the user may set: the JSON Schema of a form, an object of named fields, each with its title and its default. Drawn with @datalayer/primer-rjsf beside the conversation and on a deployment's Ship card, its values go with every run and are checked by the runtime against the same schema. None when unsaid	empty
settings_ui	mapping	How the settings' fields are drawn, as @datalayer/primer-rjsf reads a uiSchema: by field name, its ui: options — ui:widget one of select, radio, range, updown, switch, checkbox, text, textarea, date, checkboxes, tags — and ui:order. Each field's own widget when unsaid	empty
language	text	The language its own words are in, as BCP 47 tags it (en, fr, pt-BR)	"en"
translations	mapping of AppTranslation	What a person reads of it in other languages, by BCP 47 tag: its name, welcome, starters and their categories, settings, commands, modes and profiles. The page shows the person's language when it has it, else its own words	—
uploads	AppUploads	What a person may send in the composer without being asked — images, files, audio — by kind, each with its largest size, and how many at once. None when unsaid: the composer offers no attachment, and a file sent with a message is refused	empty
components	list of text	The components of the catalog the surface may use; the kind's own when empty	—
custom_components	list of AppCustomComponent	Components its developer wrote, of this application only: each named, its props a JSON Schema, its module's address; placed, shown and drawn as the catalog's own	—
surface	AppSurface	The component tree, when there is one	empty
page	AppPage	A widget's page written in its code (@app.page): its inputs as a form, its outputs as values; run again as an input changes, its outputs shown in place. None when unsaid	empty
avatar	text or Model3DAvatar	The avatar its floating assistant shows, its appearance: by the id a plugin contributes it under (lowercase letters and digits, words joined by a hyphen): Datalayer's orb orb, in the theme's colours, acting out each of the assistant's states; Datalayer's own drawings paperclip, wizard, cat and eyes; the characters clippy.js publishes, Microsoft's, fetched from jsDelivr when shown (clippy-js-clippy, clippy-js-merlin, clippy-js-links, clippy-js-rover, clippy-js-genie, clippy-js-genius, clippy-js-f1, clippy-js-peedy, clippy-js-rocky, clippy-js-bonzi); or a Microsoft Agent character a plugin brings; or a 3D model, {kind: model3d, url}. The paper clip when unsaid; an id no enabled plugin contributes is refused where the plugins are known, the runtime and the page. Said here, it wins over a person's own choice in their settings	empty
balloon	BalloonDisplay	How its floating assistant's balloon shows the conversation: history (every message, scrolled, the composer last) or current (only what it says or does now, the answer being written or the tool it calls, in one balloon). The page's own when unsaid: history for the floating chat	empty
voice	AppVoice	Its voice: whether it listens and speaks, with which voice, in which language (off unless said)	—
outputs	list of text	The formats its answers come in, by media type, words first: text/markdown, then application/x-ipynb+json for a Jupyter notebook. Over A2A, its agent card's output modes; a caller asks for some of them (acceptedOutputModes). Plain text alone when unsaid	—

AppMode

A mode switch in the composer: the person picks one of its options.

Field	Type	Meaning	Default
id (required)	text	Its id, the key a run says its option under	—
label (required)	text	What the switch is called	—
options (required)	list of AppModeOption	Its positions, two at least	—
default	text	The option it starts on; the first when unsaid	empty

AppModeOption

One position of a mode switch: what the agent is told, the model it runs on.

Field	Type	Meaning	Default
id (required)	text	Its id, what a run says it is in	—
label (required)	text	What the switch says	—
description	text	What it changes, in a sentence	empty
instructions	text	What the agent is told besides its instructions, in every run in this mode	empty
model	text	The model a run in this mode runs on, in place of the application's	empty

AppModeTranslation

A mode in another language.

Field	Type	Meaning	Default
label	text	What the switch is called	empty
options	mapping of AppOptionTranslation	Its options, by id	—

AppOptionTranslation

An option of a mode in another language.

Field	Type	Meaning	Default
label	text	What the switch says	empty
description	text	What it changes	empty

AppPact

PACT: the businesses it asks for each person, and whether it answers as one.

Field	Type	Meaning	Default
connections	list of AppPactConnection	Businesses, over PACT	—
business	AppPactBusiness	As a business	—

AppPactBusiness

The application answers as a PACT business. Published at its deployment's own address: its A2A Agent Card names Datalayer as the Provider and the application's owner as the Brand; its A2A interface verifies each personal-agent JWT against a registered issuer's keys; with scopes, a person delegates to a personal agent through the Provider's device-code sign-in — their Datalayer sign-in — and every answer under their delegation carries a signed receipt.

Field	Type	Meaning	Default
enabled	true or false	Whether it is published as a business at Ship	false
brand	text	The Brand's name on its card: the application's owner when unsaid	empty
scopes	mapping of text	What a person may let a personal agent do, {scope: what the person is shown}: bookings:read: See your bookings; none, it answers personal agents alone	—
registered_agents	list of AppPactRegisteredAgent	The personal agents it accepts, each its issuer and its keys	—

AppPactConnection

A business the application asks for each person, over PACT 1.0. The Brand is named by its domain — its Agent Card is at https://<brand>/.well-known/agent-card.json (PACT §2.1) — and its Provider's audience, which the Provider assigns at registration and the personal-agent JWT carries. Always in each person's own name: PACT acts for a person. No credential is ever part of a spec.

Field	Type	Meaning	Default
id (required)	text	Stable within the application: support	—
brand (required)	text	The business's domain: example.com	—
audience (required)	text	The audience its Provider assigned (PACT §3.1)	—
access	Access	How far: read (asks as the application alone), or write (also for the person, delegated)	"read"
scopes	list of text	The Brand's scopes it may ask the person for: orders:read	—

AppPactRegisteredAgent

A personal agent the business accepts (PACT 1.0 §3.1): its issuer, and where its keys are. Registered by the Maker, as pap.company.registered_agents: a personal-agent JWT is verified against the keys of a registered issuer only, and any other is refused.

Field	Type	Meaning	Default
issuer (required)	text	The personal agent's iss, an HTTPS URL	—
jwks_uri (required)	text	Where its public keys are (a JWKS), an HTTPS URL	—

AppPage

A widget's page written in its code: @app.page. Its inputs are a form, drawn on the page; as one changes, the function of its code runs again on them and the page shows what it returned, in place. Without its file nothing runs it, and validation says so.

Field	Type	Meaning	Default
function (required)	text	The function of its code that runs the page	—
inputs (required)	mapping	Its inputs: the JSON Schema of a form, an object of named fields, each with its title and its default; on the page at /inputs/<name>, checked by the runtime against the same schema	—
inputs_ui	mapping	How its inputs are drawn, as interface.settings_ui draws the settings: a uiSchema by field name	empty
outputs (required)	list of AppPageOutput	What it shows for its inputs, in order, each at /outputs/<name>	—
live	true or false	Whether it runs again as an input changes; false: when the person presses Run	true

AppPageOutput

One thing a page shows for its inputs: a value, drawn with a component.

Field	Type	Meaning	Default
name (required)	text	Its name: what its code returns it under, and where the page shows it (/outputs/<name>)	—
title	text	What a person reads above it; none when unsaid	empty
component	text	What draws it: Text (words, unless said), Image (an address), Table (rows) or Chart (points), or a component of the application's own (interface.custom_components), its value what it shows first	"Text"
props	mapping	The component's other properties: a Table's columns, a Chart's kind, x and y	—

AppPair

One of a pair of examples, a PACT business and the personal agent that asks it. A personal agent's issuer is its own application's, known only once a copy exists: when a person has copied both of a pair, the Studio registers the personal agent's copy with the business's copy (pact.business.registered_agents) and points the personal agent at the business's own domain.

Field	Type	Meaning	Default
id (required)	text	The pair's id, the same on both of its applications	—
role (required)	PairRole	business, or personal_agent: the one that asks it	—

AppPap

Personal Agent Protocol: the companies it works with, and whether it is one. A pap block names the profile it is written for: one Datalayer speaks, or it is refused in a sentence. An application without the block has none.

Field	Type	Meaning	Default
profile	draft-01	The Personal Agent Protocol profile it is written for: draft-01	empty
connections	list of AppPapConnection	Companies, as a personal agent	—
company	AppPapCompany	As a company	—

AppPapAlternative

Another way to do an excluded task (PAP draft 0.3 §8.2): instructions, references, or both.

Field	Type	Meaning	Default
instructions	text	What the person or their agent can do instead, at most 2000 characters	empty
references	list of AppPapReference	Where to do it instead	—

AppPapCompany

The application is a company personal agents work with.

Field	Type	Meaning	Default
enabled	true or false	Whether it publishes itself as a company at Ship	false
signed_out	true or false	Whether a personal agent may ask before signing in	true
interfaces	list of PapInterface	How personal agents reach it: agent, openapi, mcp, and web — its pages, a browser joining the person's Session through the one-time-code form (PAP draft 0.3 §6)	—
scopes	list of AppPapCompanyScope	The scopes it offers, each with what it allows and its hints	—
excluded_tasks	list of AppPapExcludedTask	Tasks it does not offer through the protocol, each with another way when there is one	—
extensions	list of text	Extensions it offers: operations	—
personal_agents	PapAgents	any, or registered only	"any"
registered_agents	list of text	The personal agents it accepts when registered only: each one's client_id URL	—
operations	list of AppPapOperation	What it does for the person once they confirm (the operations extension)	—

AppPapCompanyScope

A scope the company offers: its name, what it allows, and its hints (PAP draft 0.3 §4.4). The description is published in auth.scopes; the hints, when given, in auth.scope_hints. Without them the hints are derived from the Rules classes of the tools behind the scope.

Field	Type	Meaning	Default
name (required)	text	The scope, in OAuth syntax: orders:read	—
description (required)	text	What it allows, as a person reads it: Read your orders	—
changes	PapScopeChanges	What its most consequential use changes: none, reversible or irreversible	empty
personal_data	true or false	Whether it reads or changes the person's personal data	empty

AppPapConnection

A company the application works with as a Personal Agent. The company is named by its domain, the discovery input, and nothing else: its endpoints, issuer and metadata are what discovery verifies and are kept by the deployment, never here, and no credential is ever part of a spec. access and as mean what they mean for every connection.

Field	Type	Meaning	Default
id (required)	text	Stable within the application: orders	—
company (required)	text	The company's domain, as discovery takes it: example.com	—
access	Access	How far: read, or write	"read"
as	ActsAs	In whose account: user (each person signs in to their own) or owner	"user"
scopes	list of text	The fewest scopes the application needs	—
interfaces	list of PapInterface	How it reaches the company	—
sign_in	list of PapSignIn	Sign-in modes the application accepts, preferred first; which of them the company offers is read from its issuer (grant_types_supported, Mediated from its poppy.json)	—
extensions	list of text	Extensions it uses: operations	—

AppPapExcludedTask

A task the company chose not to offer through the protocol (PAP draft 0.3 §8.1).

Field	Type	Meaning	Default
task (required)	text	The task, as a person says it, at most 200 characters	—
alternative	AppPapAlternative	Another way to do it	empty

AppPapOperation

Something a personal agent may ask the application to do for the person, done only once they approve its exact terms (Operations v2). Asked by a personal agent, the application's agent does not call tool: the company answers with the operation, its arguments the terms, and the personal agent asks the person about that revision. Its request sent again with their approval runs the tool, with those arguments and only once.

Field	Type	Meaning	Default
action (required)	text	The action's name at this company, e.g. orders.exchange	—
tool (required)	text	The application's tool that does it, called with the terms	—
summary (required)	text	What the person is shown, with {term} for each term, e.g. Exchange order {order_id} for size {size}; never written by the model	—

AppPapReference

One place an alternative points to: an OpenAPI operation, an MCP tool, or a page.

Field	Type	Meaning	Default
type (required)	PapReferenceType	openapi, mcp or web	—
url (required)	text	Its HTTPS URL: the API's or server's the company lists, or the page	—
operation_id	text	For openapi: the operation	empty
tool	text	For mcp: the tool	empty

AppPermissions

What the application may reach beside its connections. Nothing, unless said.

Field	Type	Meaning	Default
spaces	list of AppSpaceGrant	The Spaces it reads or writes	—
computer	AppComputer	Its computer: browse, files, shell	—

AppProfile

One of several assistants in one application: a variant of its agent. The person picks a profile before the conversation starts, and keeps it to the end: its instructions are told to the agent on top of the application's in every run, its model run in place of the application's (a mode's model wins over it), and its starters offered in place of the application's.

Field	Type	Meaning	Default
id (required)	text	Its id, what a conversation says it is with	—
label (required)	text	What the person picks it by	—
description	text	What it is for, in a sentence, beside its label	empty
instructions	text	What the agent is told besides its instructions, in every run with this profile	empty
model	text	The model it runs on, in place of the application's; a mode's model wins over it	empty
starters	list of AppStarter	The first messages it offers, in place of the application's; the application's when empty	—

AppProfileTranslation

A profile in another language.

Field	Type	Meaning	Default
label	text	What the person picks it by	empty
description	text	What it is for	empty

AppRecord

What is kept of what the application did, and for how long.

Field	Type	Meaning	Default
keep_for	text	How long: 90_days, 18_months, 1_years	"1_years"
include	list of RecordItem	What is kept	—
suggest_tests	true or false	Whether its conversations may be used to suggest tests: a few, sampled from those kept while it is on, proposed to its builder; off unless said	false

AppRepository

A repository lent to its computer: checked out at one revision, as its workspace. The same git content an Environment brings (a public repository at a pinned commit): an agent that works in a workspace — a coding harness — finds it there when it starts. What it may do to it is its Rules'.

Field	Type	Meaning	Default
url (required)	text	The repository, an https:// git URL anyone may clone	—
revision (required)	text	The full commit sha it is checked out at	—

AppRule

When the application acts alone, and when it asks.

Field	Type	Meaning	Default
action (required)	text	The action, in the words a person reads: Send an email	—
applies_to (required)	text or list of text	What the rule applies to: a class of action (read, write, send, buy, delete, publish), or named tools (server.tool, or a tool id)	—
behaviour (required)	Behaviour	do_it, if_asked, ask_first or leave_to_me	—

AppSampleAlternative

An alternative a decision is tried on, and what is known about it.

Field	Type	Meaning	Default
name (required)	text	Its name	—
evidence (required)	text	What is known about it: the text its typed questions are asked on	—
metrics	mapping of number	What each metric criterion found for it, by the criterion's name	—

AppSampleDocument

A document it answers from, as Datalayer publishes it with the application.

Field	Type	Meaning	Default
name (required)	text	The document, as its contents names it	—
file (required)	text	The file it is given as, in a sandbox: price-list.csv	—
text (required)	text	What it holds	—

AppSamples

What it is tried on before it is anybody's. Published with it by Datalayer and read only: what a visitor without an account tries it on, in the browser.

Field	Type	Meaning	Default
documents	list of AppSampleDocument	Documents of its contents, as Datalayer publishes them	—
alternatives	list of AppSampleAlternative	For a decision: alternatives with their evidence	—

AppScenario

A named set of weights: one way of looking at the same findings.

Field	Type	Meaning	Default
name (required)	text	Its name	—
weights	mapping of number	By criterion name	—

AppSignedFetch

Signed fetch: the sites it reads pages of, signed with its Web Bot Auth key.

Field	Type	Meaning	Default
sites	list of AppSignedFetchSite	Sites, each by its exact domain: read with GET only, every request signed	—

AppSignedFetchSite

A website the application reads pages of, each request signed. Decided 2026-10-13: a signed fetch names exact sites, an allow-list. Datalayer's gateway reads a page there with GET only, on its safe egress path (public addresses only), each request signed with the application's own Web Bot Auth key and recorded; reading is under the application's Rules like any read. Named by its domain: no other host is reached, and no credential is ever part of a spec.

Field	Type	Meaning	Default
id (required)	text	Stable within the application: example-verifier	—
site (required)	text	The site's domain, exactly: verify.examples.datalayer.run	—

AppSpaceGrant

A Space the application may reach.

Field	Type	Meaning	Default
space (required)	text	The Space, by its handle or its id	—
access	Access	read, or write	"read"

AppSpendLimit

The most one purchase may cost at a merchant.

Field	Type	Meaning	Default
amount (required)	text	At most this much, as written: 50, 12.50	—
currency (required)	text	Its currency, ISO 4217: USD	—

AppStarter

A first message offered to the user.

Field	Type	Meaning	Default
label (required)	text	What the button says	—
message (required)	text	What is sent when it is chosen	—
category	text	The heading it is offered under: the starters of one category are shown together, those without one first	empty

AppStarterTranslation

A starter in another language.

Field	Type	Meaning	Default
label	text	What the button says	empty
message	text	What is sent when it is chosen	empty

AppSurface

The component tree the user meets, over the approved catalog (A2UI).

Field	Type	Meaning	Default
protocol	text	The protocol the tree is written in	"a2ui/v0.9"
components	list of mapping	The components, as the protocol's updateComponents carries them	—
composed_by	text	Who composed it: a model's id, canvas (a person on the Canvas), developer, template	empty
composed_at	text	When, as an ISO date	empty

AppTestCase

An example of what the application should do, in plain words. A case is one message (ask) or a short conversation (turns): what the person says, chooses and presses, in order, each after the application answered the turn before — and what it should do is judged on the whole conversation. When plain words are not enough, its code decides it: code names the function of the application's app.py that is given the conversation and says whether it passed — @app.test writes it. expect still says it in words: without its file, the case is judged by them.

Field	Type	Meaning	Default
ask	text	What it is asked, in one message; none when it has turns	empty
turns	list of AppTestTurn	The conversation it is had in, turn by turn, in place of one message: what the person says, chooses and presses	—
expect (required)	text	What it should do	—
code	text	The function of its code that decides the case, by name, when words are not enough; expect says it in words	empty
files	list of AppTestFile	Text files it is given with what it is asked, each in the message after it	—

AppTestFile

A text file a test gives with what it asks, as a person gives one on its page.

Field	Type	Meaning	Default
name (required)	text	Its name, without a folder: orders.csv	—
text (required)	text	What it holds	—

AppTestTurn

One turn of a test's conversation: what the person says, the option of a choice they pick, or an action of its code they press, with its payload. Each is sent as its page sends it, after the application answered the turn before: a message, a choice answered in its option's words, an action by its name (@app.action).

Field	Type	Meaning	Default
say	text	What the person says	empty
choose	text	The option they pick, of the choice it asked	empty
press	text	The action of its code they press, by name (@app.action)	empty
payload	mapping	What the action is given with its press	—

AppTests

How the application is verified.

Field	Type	Meaning	Default
ready_at	number	The share of tests that has to pass for the application to be ready	0.8
evalset	text	An evalset its runs validate against, when one is chosen	empty
cases	list of AppTestCase	Its test conversations	—
verified	AppVerified	What was verified live, what runs on recorded data, and what is not verified yet	—

AppTheme

The theme an application runs in by default.

Field	Type	Meaning	Default
variant (required)	ThemeVariant	The theme: datalayer, spatial, lovely, matrix, earth, sand, ivory, sun, loop or vscode	—
mode	ThemeMode	light, dark or auto (the device's); the person's own when unsaid	empty

AppTool

A tool of the application's own, written in its code: @app.tool. Its agent calls it as any tool; the rules decide each call by what it does — a rule may name it, by its name alone — and the Canvas lists it. Without its file the agent is not given it.

Field	Type	Meaning	Default
name (required)	text	Its name: what the agent calls, and a rule names	—
description (required)	text	What it does, for the agent: when to call it	—
parameters	mapping	The JSON Schema of its arguments, an object; none when unsaid	—
does (required)	list of ActionClass	What it does, by class of action (read, write, send…): what the rules decide	—

AppTranslation

What a person reads of an application, in another language. Each part is keyed by what names it in the spec: a starter by its label, a category by its words, a setting by its field, a command by its name, a mode and a profile by their ids. What is not translated is shown in the spec's own words; what is translated is shown, never sent, but a starter's message — the agent is written to in the person's language.

Field	Type	Meaning	Default
name	text	Its display name	empty
description	text	What it does	empty
welcome	text	What it says first	empty
starters	mapping of AppStarterTranslation	Its starters and its profiles', by their label	—
categories	mapping of text	The starters' categories, by their words	—
settings	mapping of AppFieldTranslation	The fields of its settings, by name	—
commands	mapping of text	Its commands' descriptions, by name	—
modes	mapping of AppModeTranslation	Its modes, by id	—
profiles	mapping of AppProfileTranslation	Its profiles, by id	—

AppTrigger

What starts a worker's work.

Field	Type	Meaning	Default
type (required)	TriggerType	schedule, event or once	—
cron	text	For a schedule: a cron expression, 0 8 * * *	empty
event	text	For an event: its name, email_received	empty
at	text	For once: when, as an ISO date	empty
description	text	What it is, in words: Every morning at 8	empty
prompt	text	What the worker is told when it fires	empty

AppUploadKind

A kind of file a person may send, and how large.

Field	Type	Meaning	Default
type (required)	text	A media type (application/pdf), a family of them (image/*, audio/*) or an extension (.csv), lowercase	—
max_mb	number	The largest file of this kind, in megabytes; 25 at most	10

AppUploads

What a person may send in the composer without being asked: images, files, audio. A file of a kind it does not name, larger than its kind takes, or one too many is refused, in a sentence — by the page before it is sent, and by the runtime when it is sent all the same.

Field	Type	Meaning	Default
kinds (required)	list of AppUploadKind	The kinds of file it takes, each with its largest size	—
max_files	integer	The most files sent with one message	5

AppVerified

What was verified, and how, each in a sentence a person reads. An example says it on its card and on its page: what was tried live, what runs on recorded data instead, and what is not verified yet. Said by whoever tried it; nothing here is computed.

Field	Type	Meaning	Default
live	list of text	What was tried live, where and when	—
recorded	list of text	What runs on recorded data, not on live calls	—
unverified	list of text	What is not verified yet	—

AppVoice

Its voice: whether it listens, whether it speaks, with which voice, in which language. Off unless said. What is said becomes a message, and what is heard is the answer the conversation shows: the text stays the truth.

Field	Type	Meaning	Default
enabled	true or false	Whether it has a voice at all; off unless said	false
input	VoiceInput	off or push_to_talk (click the microphone or hold it, speak; it stops when let go or once the person stops speaking)	"push_to_talk"
output	VoiceOutput	When its answers are heard: off, on_request (a Read aloud on each answer) or always	"on_request"
voice	text	The voice it speaks with, an id of the voice catalogue (kokoro-af-heart); the language's first when unsaid	empty
language	text	The language it listens and speaks in, BCP 47 (en-US, fr-FR); the person's when unsaid	empty
where	VoiceWhere	Where its speech runs: auto, device (the person's browser) or server (Datalayer's)	"auto"

EmbeddedDeployment

The application inside another product's page.

Field	Type	Meaning	Default
mode	EmbedMode	inline, bubble, panel or assistant	"inline"
origins	list of text	The origins allowed to embed it	—
host	HostBridge	What the host page passes it and the functions of the host it may call	empty

HostBridge

What the host page and the application say to each other. The values of the host it reads (context: user, page, or a name of the host's own), through the tool host_context; the functions of the host it may call, each through host_<name>. Every one of these tools is decided by a rule that names it, as any tool is: one no rule names is left to the person. Who its user is (user): what the page says (claimed), or only what the host's server signed (signed) — a short token, HS256 with the deployment's secret, naming sub, name and exp at most an hour away. An application that acts in each user's name, or shows data that is theirs, says signed.

Field	Type	Meaning	Default
context	list of text	The host's values it reads: user, page, or names of the host's own	—
functions	list of HostFunction	The host's functions it may call	—
user	HostUser	Who its user is: claimed, what the page says; signed, only a token the host's server signed with the deployment's secret, the unsigned one refused	"claimed"

HostFunction

A function of the host page the application's agent may call.

Field	Type	Meaning	Default
name (required)	text	Its name, lower-case words joined by _: open_ticket	—
description (required)	text	What it does, for the agent: when to call it	—
parameters	mapping	Its arguments, as a JSON Schema object	—

HostedDeployment

The application at an address of its own.

Field	Type	Meaning	Default
visibility	Visibility	Who can open it	"private"
slug	text	The readable part of its address	empty
avatar_alone	true or false	At its address, only its avatar: the conversation opens in its balloon, as when it is shipped as assistant	false

Model3DAvatar

An avatar that is a 3D model (glTF), drawn in the page with three.js.

Field	Type	Meaning	Default
kind (required)	model3d	model3d	—
url	text	The https address of its model, a .glb or .gltf; when unsaid, Datalayer's default robot (RobotExpressive, CC0). Its animation named Idle plays while it is quiet; while it speaks, its mouth and head move with its voice	empty

UiChoice

A UI plugin an agent or an application names, and the renderer it is exposed through, when it is.

Field	Type	Meaning	Default
plugin (required)	text	A UI plugin of agentspecs/ui, by id	—
renderer	text	The UI renderer of agentspecs/ui-renderers it is exposed through, by id	empty

Choices

Accent

green, rose, sky, lime, sun, violet

Access

read, write

ActionClass

read, write, send, buy, delete, publish

ActsAs

owner, user

AppKind

chat, widget, decision, worker

BalloonDisplay

history, current

Behaviour

do_it, if_asked, ask_first, leave_to_me

CheckStage

answer, tool_call

CommerceProtocol

ucp, acp

CriterionKind

metric, noul, choice, score

EmbedMode

inline, bubble, panel, assistant

HostUser

claimed, signed

Layout

chat, page, split

PairRole

business, personal_agent

PapAgents

any, registered

PapInterface

agent, openapi, mcp, web

PapReferenceType

openapi, mcp, web

PapScopeChanges

none, reversible, irreversible

PapSignIn

direct, device, mediated

RecordItem

conversations, actions, decisions, approvals, checks, sources, outputs, feedback, audio, diffs, terminals

ThemeMode

light, dark, auto

ThemeVariant

datalayer, spatial, lovely, matrix, earth, sand, ivory, sun, loop, vscode

TriggerType

schedule, event, once

Visibility

private, invited, organization, link, public

VoiceInput

off, push_to_talk, hands_free

VoiceOutput

off, on_request, always

VoiceWhere

auto, device, server