Setup

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 consoleWhat 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 list

The 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 create answers slug 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":

TemplateAgents
Базовая команда (basic team)Dispatcher, Team Lead, Исполнитель, Checker
Dev teamDispatcher, Team Lead, Developer 1, Developer 2, DevOps, Deploy, Checker
GroupDispatcher, Собеседник (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) or Strict: with Strict every 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.

  • errors holds a JSON Pointer path and a reason — fix that field.
  • missing.models lists a model that is not on the cradle: register it (cradle models add <ref> …, Keys and models); blocking becomes false.
  • 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:

ToolScopeWhat it does
cradle_catalogteams:readwhat is on the cradle: models, tools, knowledge bases, MCP servers, skills, policies, teams
cradle_team_planteams:readchecks a manifest and gives the plan without writing
cradle_team_applyagents:writecreates (create) or replaces (replace) a team; creating needs an admin:* key or a person
cradle_team_exportteams:readthe manifest of a team by slug
  1. Turn the MCP channel on (Channels); it listens on 127.0.0.1:31417.

  2. Issue a key (admin:* to create teams, Sign-in, people and keys) and save the file cradle-mcp.json:

    {
      "mcpServers": {
        "cradle": {
          "type": "http",
          "url": "http://127.0.0.1:31417/mcp",
          "headers": { "x-api-key": "ck_live_..." }
        }
      }
    }
  3. 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 with cradle_team_plan and 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).

ToolWhat it doesWhat it needs
web.searchweb search, up to 8 resultsSearXNG: CRADLE_SEARXNG_URL or settings.search.searxngUrl (from a repository clone — cradle server docker up searxng); or Brave with the provider key brave
web.fetchpage text by URL, up to 8,000 charactersin Docker the internal network is closed: CRADLE_WEB_ALLOW_PRIVATE
doc.readthe text of a conversation attachment (PDF, DOCX, XLSX, CSV)—
doc.createa PDF, DOCX, CSV or XLSX file—
tts.speaka voice message (Amazon Polly)AWS credentials of the host
image.generatea 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.