Reference

Team manifest

A team of agents as one JSON document, cradle.team/v1: export, import with a dry run, skill packages and policies by id@version.

A team of agents is described by one JSON document, the cradle.team/v1 manifest. The manifest is the source of truth for the team's structure: the console canvas draws it, cradle-server exports and imports it, git keeps it. Skills and policies travel as separate packages, referenced by id@version.

Schema: /schemas/team.v1.json (JSON Schema draft 2020-12). This page and the schema are enough to write a valid manifest, by hand or by a model.

Shape of a team

Exactly three levels, no conditions or loops (routing stays with triage and the leads):

  • captain: one, takes the inbound message and dispatches (the triage role);
  • checker: one, stored in the team structure (it is not called as an agent in version 0.9.2); onReject is return-to-lead only in v1;
  • leads: 1–5 leads, each with members: 0–5 executors;
  • shared: 0–5 shared executors: any lead may hand them a task, they never receive messages directly.

An unknown field fails validation (additionalProperties: false), so a typo cannot pass silently.

Top level

FieldRule
schemaRequired, exactly cradle.team/v1
nameTeam slug [a-z0-9-]{1,64}, unique on the cradle
titleName, 1–120 characters
descriptionUp to 2000 characters, optional
captain, checkerOne agent each (fields below)
leads1–5 lead agents with members, sources, triggers
shared0–5 agents with triggers
requiresExternal dependencies by name: channels, mcpServers, knowledgeBases, ontologies. Never tokens or addresses

Agent fields

FieldRule
idSlug, unique in the manifest. The stable key of the agent: on re-import the agent with the same id is updated in place
titleName, 1–120 characters
badge1–3 characters for the canvas, optional (not stored in v1)
promptRequired. System prompt, 1–32,000 characters
categorycoding · business · marketing · seo · general · other; default general
modelModel alias (the model's ID in the cradle's catalog). Absent: placement picks a model by requirement
requirementgeneral · coding · reasoning; default general
temperature0–1.5, default 0.7
tagsRouting tags from the directory (faq, escalation, …). An unknown tag is created
skillsSkill packages id@semver. A missing package blocks the import
policiesPolicies id@semver. A missing one blocks
toolsBuilt-in tools: web.search, web.fetch, doc.read, doc.create, tts.speak, image.generate. An unknown one blocks
knowledgeBasesNames of the team's knowledge bases. Missing ones do not block: the agent is marked needsBinding
mcpServersNames of the cradle's MCP servers. Same
groundingoff · soft · strict; default soft. A policy with strict wins
enabledDefault true
executionExecutors only (a lead's members and shared): { "kind": "external", "repository": "owner/name", "baseBranch": "main" }. The task goes to an external code agent (a GitHub Actions workflow); no cradle model is called for it. The repository must be in the team's repository list, otherwise import warns with repository_not_allowed. No field — the executor runs on a cradle model. Details — External code agent
sourcesLeads only: which sources the lead accepts: telegram, telegram:private, telegram:group, widget, api, mcp-server. Absent: any; []: tasks and triggers only
triggersLeads and shared executors, up to 5: { id, cron (5 fields), tz (IANA, default UTC), instruction }. Stored and shown in v1, not scheduled yet

Full example

{
  "schema": "cradle.team/v1",
  "name": "stoic-sage",
  "title": "Стоик",
  "description": "Собеседник-стоик для Telegram-группы: беседа, редактура подборок, библиотека и поиск в общем пуле",
  "captain": {
    "id": "triage",
    "title": "Triage",
    "prompt": "Ты — диспетчер. Определяешь, кому адресовано сообщение: беседа — Собеседнику, запрос на подборку или текст — Редактору.",
    "requirement": "general",
    "tags": ["greeting", "faq", "escalation"]
  },
  "checker": {
    "id": "checker",
    "title": "Checker",
    "prompt": "Ты — Checker. Проверяешь, что цитаты приписаны верному автору и тексту, а совет не выдаёт себя за медицинскую или юридическую помощь.",
    "requirement": "reasoning",
    "grounding": "strict",
    "onReject": "return-to-lead"
  },
  "leads": [
    {
      "id": "companion",
      "title": "Собеседник",
      "badge": "СБ",
      "prompt": "Ты — собеседник-стоик в духе Марка Аврелия, Эпиктета и Сенеки. Отвечаешь коротко, задаёшь встречный вопрос, опираешься на первоисточники из библиотеки. Для цитат проси библиотекаря, для фактов о мире — поисковика.",
      "requirement": "general",
      "temperature": 0.8,
      "tags": ["tone-support"],
      "knowledgeBases": ["stoic-canon"],
      "sources": ["telegram:group"]
    },
    {
      "id": "editor",
      "title": "Редактор",
      "badge": "РД",
      "prompt": "Ты — редактор подборок. Собираешь тематические подборки цитат с комментарием, готовишь утренний текст и недельный обзор обсуждений группы. Входящие сообщения не принимаешь — работаешь по расписанию и задачам.",
      "requirement": "reasoning",
      "temperature": 0.5,
      "tags": ["copy"],
      "knowledgeBases": ["stoic-canon", "stoic-community"],
      "sources": [],
      "triggers": [
        { "id": "morning", "cron": "0 7 * * *", "tz": "Europe/Moscow", "instruction": "Подготовь утреннюю цитату с комментарием на 3–4 предложения." },
        { "id": "weekly", "cron": "0 18 * * 0", "tz": "Europe/Moscow", "instruction": "Собери обзор обсуждений недели из базы stoic-community: темы, лучшие вопросы, цитаты, которые помогли." }
      ]
    }
  ],
  "shared": [
    {
      "id": "librarian",
      "title": "Библиотекарь",
      "badge": "Б",
      "prompt": "Ты — библиотекарь. По запросу находишь точные цитаты в первоисточниках и возвращаешь их с указанием автора, труда, книги и фрагмента. Не пересказываешь — цитируешь.",
      "requirement": "general",
      "temperature": 0.1,
      "grounding": "strict",
      "knowledgeBases": ["stoic-canon", "stoic-community"]
    },
    {
      "id": "searcher",
      "title": "Поисковик",
      "badge": "П",
      "prompt": "Ты — поисковик. По запросу находишь факты в сети и возвращаешь краткую выжимку со ссылками на источники.",
      "requirement": "general",
      "temperature": 0.2,
      "tools": ["web.search", "web.fetch"]
    },
    {
      "id": "observer",
      "title": "Наблюдатель",
      "badge": "Н",
      "prompt": "Ты — наблюдатель группы. Ночью просматриваешь обсуждения дня и формируешь краткий конспект: темы, вопросы без ответа, повторяющиеся трудности.",
      "requirement": "general",
      "temperature": 0.3,
      "knowledgeBases": ["stoic-community"],
      "triggers": [
        { "id": "nightly-digest", "cron": "30 2 * * *", "tz": "Europe/Moscow", "instruction": "Составь конспект обсуждений за прошедшие сутки для базы stoic-community." }
      ]
    }
  ],
  "requires": {
    "channels": ["telegram"],
    "knowledgeBases": ["stoic-canon", "stoic-community"]
  }
}

More examples: the folder examples/team-manifest: a one-lead manifest referencing a skill and policies; two policies; a skill package.

Export and import

MethodPathScopeWhat
GET/api/v1/teams/:slug/manifestteams:readCanonical JSON, header X-Manifest-Sha256
POST/api/v1/teams/manifest/dry-runteams:readValidation and plan, nothing written
POST/api/v1/teams/manifest?mode=create|replaceagents:write (a new team needs admin:*)Apply. 409: slug taken in create; 422: schema errors or blocking gaps

Dry-run response:

{
  "valid": true,
  "errors": [],
  "plan": { "action": "create", "team": { "slug": "stoic-sage", "exists": false },
            "agents": { "create": ["triage", "checker", "companion", "editor", "librarian", "searcher", "observer"], "update": [], "remove": [] } },
  "missing": { "skills": [], "policies": [], "models": [], "tools": [],
               "channels": ["telegram"], "mcpServers": [], "knowledgeBases": ["stoic-canon", "stoic-community"], "ontologies": [] },
  "warnings": [{ "path": "/leads/1/triggers", "code": "trigger_inactive" }],
  "blocking": false
}

skills, policies, models and tools block. The rest does not: the team is created and agents with unbound dependencies are marked on the canvas.

replace runs in one transaction: an agent with the same id is updated in place and keeps its history, new ones are created, the rest are removed. A failure half-way leaves the team as it was. Export → import into a clean team → export is byte-identical (keys in schema order, defaults written out, no internal ids or dates).

In the console: team screen → Export / Import (schema check in the browser, the plan, upload of missing packages right from the plan, Apply).

Manifest through MCP

An assistant connected to the cradle's MCP endpoint (POST /mcp, the cradle key in the Authorization or X-Api-Key header) can build and apply a manifest without the console: cradle_catalog (what the cradle has), cradle_team_plan (validation and plan, nothing written), cradle_team_apply (create or replace, only after the person agrees to the plan) and cradle_team_export. The boundary is the one of the other team operations: a team key sees its own team, a person sees the teams of their organization and a team they create joins it.

Skill packages

A skill is a folder with SKILL.md (frontmatter name, description, version as semver, optional tags) and any files. The body of SKILL.md is appended to the system prompt of an agent that references name@version.

---
name: grounding-check
description: Проверка, что каждое утверждение ответа подтверждено фрагментом источника
version: 1.0.0
tags: [compliance]
---

# Grounding check

Когда получаешь результат на проверку:

1. Разбей ответ на утверждения — по одному факту на строку.
2. Для каждого утверждения найди подтверждающий фрагмент в источниках `[n]`. Нет фрагмента — утверждение «не подтверждено».
3. Числа, даты, имена и коды сверяй посимвольно.
4. Вердикт: `accept`, если неподтверждённых утверждений нет; иначе `reject` со списком неподтверждённых утверждений и тем, что нужно исправить.

Не исправляй ответ сам — верни его лиду.

Export is a zip of the folder, <id>-<version>.skill.zip: GET /api/v1/skills/:id/:version/export. Import: POST /api/v1/skills/import (multipart/form-data, field file). Limits: ≤ 10 MB, no symlinks, no absolute paths or ... The same version with other content is 409.

Policies

A policy is a cradle.policy/v1 document (schema /schemas/policy.v1.json):

{
  "schema": "cradle.policy/v1",
  "id": "strict-grounding",
  "version": "1.0.0",
  "title": "Строгое заземление",
  "description": "Каждое утверждение подтверждено источником; инструменты не используются.",
  "grounding": "strict",
  "tools": { "allow": [] }
}

grounding overrides the agent's mode (stricter wins), tools.allow only narrows the tools, risk.holdOn is stored and shown in v1. GET /api/v1/policies/:id/:version/export, POST /api/v1/policies/import (JSON).