Team
The roles captain, lead, executor and Checker, creating a team, templates, the cradle.team/v1 manifest, setting up through Claude over MCP, executor tools.
A team is the unit the console works with: it has its own agents, knowledge bases, tickets and conversations. A team lives in one cradle and belongs to an organization.
1. Roles in a team
| Role in the console | What it does |
|---|---|
Captain (captain) | the root of the structure, one per team; does not receive messages directly |
Lead (lead) | reports to the captain; receives the incoming message and decides: answer itself, hand it to an executor, or call a human |
Executor (executor) | reports to a lead; works only on the lead's assignments (tasks) |
Checker (checker) | one per team, kept in the structure; does not receive messages directly and is not called as an agent |
Before a reply is sent it goes through programmatic checks (citations, reply hygiene); if one fails, the ticket waits for a human (Waiting for decision). "Shared" executors (without a lead) take assignments from any lead. More about routing is in Triage and risk engine.
2. Create a team
In the console: Teams → Add team → in the "New team" window enter a
Name (for example "Support"), choose the Cradle if there are several,
press Save. The same with a command (needs admin:*):
cradle teams create support --name "Support"The team immediately gets the "Базовая команда" (basic team) template: Dispatcher (captain), Team Lead (lead), Исполнитель (the executor) and Checker; models are picked by the team's requirements (Keys and models).
How to check. A team card appeared on the "Teams" page; on its page the "Canvas" view shows four agents. From the CLI:
cradle teams use support
cradle agents listThe table has four rows: Dispatcher, Checker, Team Lead, Исполнитель.
If it did not work.
- "slug already taken" — a team with that slug exists; the console retries with a suffix, and
cradle teams createanswersslug already taken— choose another name. - "The cradle “…” does not answer" — the server is not running or the SSH tunnel of the GPU server is closed.
- Agents show a model warning — there is no suitable model or the contour is closed (Keys and models).
3. Team and agent templates
On the team page press Templates. The Teams tab holds ready-made teams; the Create team button adds their agents to the open team and prints "Agents created: N":
| Template | Agents |
|---|---|
| Базовая команда (basic team) | Dispatcher, Team Lead, Исполнитель, Checker |
| Dev team | Dispatcher, Team Lead, Developer 1, Developer 2, DevOps, Deploy, Checker |
| Group | Dispatcher, Собеседник (the conversation partner) and the executors Поисковик (search), Документы (documents), Голос (voice), Дизайнер (designer) — for a bot in a group chat |
A template is applied to a team that has no captain and no Checker yet; otherwise the answer is "team already has a captain: apply the team template to a team without a captain and a checker". The Agents tab holds single-agent templates (support, sales, lawyer and others): a click opens the agent form with the prompt filled in.
From the CLI (a single-agent template):
cradle agents create --template support --name "Support"How to check. cradle agents list shows the new agent; agents appeared on the canvas.
4. Set up an agent
Click an agent on the canvas — the form opens on the right. What to change first:
- System prompt — what the agent does and does not do;
- "Requirement" and Model — which model the agent gets (Keys and models);
- Knowledge Bases — the agent's knowledge bases (Knowledge bases);
- Inbound sources (leads only) — where it accepts messages from: "any" or
telegram,telegram:private,telegram:group,widget,api,mcp-server; - Grounding mode —
Off,Soft(the default) orStrict: withStrictevery fact must be backed by a source from a knowledge base.
Press Save; the "Disable" / "Enable" button switches the agent off.
How to check. After Save the form shows no error, and when you open the agent again the values are the same.
If it did not work. The team_invariant error means the team structure is
broken (one captain and one Checker, a lead reports to the captain, an executor
to a lead).
5. The cradle.team/v1 manifest
A whole team is one JSON document (Team manifest,
the schema is /schemas/team.v1.json). On the team page:
- Export downloads the file
<slug>.team.json; - Import opens the window "Import a team from a manifest": paste the JSON or pick a file (File…), press Check — it shows the plan ("Create", "Update", "Remove") and what is missing; then Create team or, with "Replace the current team" ticked, Apply replace.
The check without writing is the Check window or the tool cradle_team_plan (step 6); creating a team needs an admin:* key or a person.
How to check. The check passes: "valid":true, "blocking":false,
an empty errors.
If it did not work.
errorsholds a JSON Pointer path and a reason — fix that field.missing.modelslists a model that is not on the cradle: register it (cradle models add <ref> …, Keys and models);blockingbecomesfalse.- Knowledge bases and MCP servers named in the manifest that are not on the cradle do not block applying: the agent is marked "Not bound at import" — pick the base in the agent form and save.
6. Setting up through Claude over MCP
Four tools of the MCP channel build and apply a team without the console:
| Tool | Scope | What it does |
|---|---|---|
cradle_catalog | teams:read | what is on the cradle: models, tools, knowledge bases, MCP servers, skills, policies, teams |
cradle_team_plan | teams:read | checks a manifest and gives the plan without writing |
cradle_team_apply | agents:write | creates (create) or replaces (replace) a team; creating needs an admin:* key or a person |
cradle_team_export | teams:read | the manifest of a team by slug |
-
Turn the MCP channel on (Channels); it listens on
127.0.0.1:31417. -
Issue a key (
admin:*to create teams, Sign-in, people and keys) and save the filecradle-mcp.json:{ "mcpServers": { "cradle": { "type": "http", "url": "http://127.0.0.1:31417/mcp", "headers": { "x-api-key": "ck_live_..." } } } } -
Start Claude Code with that file:
claude --mcp-config cradle-mcp.json. Ask, for example: "Show what is on the cradle (cradle_catalog), build a team of a captain, a lead with an executor and a Checker, check it withcradle_team_planand show me the plan". Apply (cradle_team_apply) only after you agree with the plan.
How to check. Without Claude: curl http://127.0.0.1:31417/health answers
"ok":true and "toolCount":12. Calling cradle_catalog returns the models,
tools and teams.
If it did not work. The answer unauthorized — no key or no x-api-key header
(Authorization: Bearer … works too); ECONNREFUSED — the MCP channel is not
turned on; a 405 for GET /mcp is normal, MCP uses POST /mcp.
7. Executor tools and external MCP servers
An executor that received an assignment works in a "model → tool → result" loop
(at most 4 iterations) and calls only the tools on its own list. Every call goes
through the gateway; a tool of the class irreversible is not run by itself — the
ticket gets the reason tool_approval (Waiting for decision).
| Tool | What it does | What it needs |
|---|---|---|
web.search | web search, up to 8 results | SearXNG: CRADLE_SEARXNG_URL or settings.search.searxngUrl (from a repository clone — cradle server docker up searxng); or Brave with the provider key brave |
web.fetch | page text by URL, up to 8,000 characters | in Docker the internal network is closed: CRADLE_WEB_ALLOW_PRIVATE |
doc.read | the text of a conversation attachment (PDF, DOCX, XLSX, CSV) | — |
doc.create | a PDF, DOCX, CSV or XLSX file | — |
tts.speak | a voice message (Amazon Polly) | AWS credentials of the host |
image.generate | a 1024×1024 picture (OpenAI) | the provider key openai |
The agent form has no "tools" field. The list is set by the manifest field tools
(web.search, web.fetch, doc.read, doc.create, tts.speak,
image.generate), or by the "Group" template.
External MCP servers (other services' tools for agents) cannot be added from
the web console in version 0.9.2: the "MCP servers" page shows "Not available
over this cradle's HTTP", and the server has no call to add them. An agent
can choose only the servers that already exist on the cradle (the "External MCP
tools" field; mcpServers in a manifest).
How to check. cradle_catalog lists the cradle's tools in the tools field,
and the manifest export shows an agent's tools field.
If it did not work. search is not configured: set settings.search.searxngUrl (or CRADLE_SEARXNG_URL) — search is not configured; unknown tool: <name> — the tool
name is wrong.