description, kind
| description | kind |
|---|---|
| Four task-board tools and shared-task guidance for Team-enabled Sessions. | package-reference |
@deepseek-ai/dsh-tool-agent-team
English | 中文
Summary
This package lets every agent in a subagent tree create, claim, and complete shared tasks. It adds four task schemas, shared-board guidance, and required Team identity. Ordinary subagent controls own discovery, messaging, interruption, and inbox waiting. The base bundle loads the service and tools; new Sessions default to Team mode off.
Table of Contents
- Use this package
- Understand the implementation
- Further Exploration
- Model Experience
- Known Limitations and Deferred Work
- Dev Note
Use this package
Team tools are available to each model step only while the root Session enables Team mode. Prompt providers read the same selection when evaluated. Ordinary subagent controls remain available.
Mount this package with @deepseek-ai/dsh-agent-team when models need the shared board. The root and descendants receive identical task schemas and task policy.
When to choose it
Choose it whenever the Team domain is mounted and models should use the board; without it, the board is reachable only through ctx.agentTeams. Teammates are created and reached through the standard subagent, subagent_fork, send_message, list_agents, and interrupt_agent tools, so the composition also needs @deepseek-ai/dsh-tool-subagent and @deepseek-ai/dsh-tool-subagent-control.
Smallest working example
The plugin takes no configuration; mount it beside the Team domain as in the agent-team setup:
- id: tool-agent-team
name: '@deepseek-ai/dsh-tool-agent-team'
A row that sets interrupt, freshProvider, or forkProvider does not activate, and dsh names the key in its startup warning. The upgrade guide maps the removed tools and keys to their replacements, and the generated configuration catalog records the empty configuration.
Ask the Lead to start a subagent to review the diff, add a review task, and wait for its result. The description explains the subagent’s work; the returned id addresses it.
What the model can do
The task tools complement the ordinary subagent controls:
- Manage the task board —
team_task_create,team_task_list,team_task_get, andteam_task_updateadd, browse, read, and update shared tasks. - Wait for inbox input —
wait_agentbelongs to@deepseek-ai/dsh-tool-subagent-controland remains available without this package. - Create and reach teammates —
subagent,subagent_fork,send_message,list_agents, andinterrupt_agentcome from the subagent tool packages and are unchanged by this package.
Task owner arguments and ownerId results use Session ids. The root may reassign to itself or any reachable continuable descendant; historical roster records grant no authority. Other agents claim ready tasks themselves. Updates enforce ownership and revision checks.
What success and failure look like
Task tools return compact JSON task views or pages. Stale revisions, unauthorized actions, and unready tasks return errors.
Understand the implementation
Implementation internals — click to expand
This section explains the design decisions behind the adapter and points at the code that realizes them; the observable behavior is fully covered in Use this package.
Design philosophy
The adapter is built on four commitments:
- Session-selected tools. Shared tool registrations select availability from each caller’s root Session; the service resolves tree authority when called.
- One tool family. Team registers no messaging, listing, or interruption tool; the standard subagent tools serve Leads and teammates alike.
- Declared results, compact JSON. Every tool declares its complete result schema and renders that value as compact JSON, so the compiler checks
executeagainst what the model is promised and no result spends tokens on indentation. - The domain owns authority. Tools delegate to
ctx.agentTeams, which enforces Lead authority and revision checks; the adapter adds no weaker path.
The subagent teammates Agent Note owns the model-facing and scoping decisions.
Source map
| File | Role |
|---|---|
src/index.ts |
Plugin entry, removed-key rejection, Team policy and identity, and four conditional task tools |
Policy and tools
One plugin registration provides a dynamic team:policy section, required team:identity context, and four conditional task tools. Each provider reads the caller’s root Session selection; prompt visibility is independent of tool restrictions. Tree authority and root identity come from ctx.subagents.rootOf(agent). An unavailable root disables Team tools and guidance. Communication and waiting belong to subagent controls; the subagent runtime delivers final results.
Scoped registration and teardown
Tool when conditions resolve at step preparation, including the first step of new, forked, and resumed Agents. Policy text is evaluated during prompt assembly; identity is also refreshed at request admission. An already prepared step retains its tool selection, but task operations check the current mode before starting. Plugin disposal removes all registrations through their owning effects.
Further Exploration
Read these pages when the package-level contract is not enough. They move from the domain service to the exact schemas and the decisions behind the design.
- agent-team package — the
ctx.agentTeamsdomain service behind these tools. - Agent Teams subsystem — durable Team types and service API.
- Subagent control tools — messaging, listing, interruption, and inbox waiting.
- Generated tool catalog — every tool schema the model receives.
- Subagent teammates Agent Note — model-facing, scoping, and tool-family decisions.
Model Experience
Team policy system prompt
What the model sees
Every Team member's system prompt carries one team:policy section; the Lead and every teammate see the same text:
Team policy
A shared task board is available to every agent in your subagent tree. Task owners are agent ids from list_agents. The root can reassign tasks to itself or any continuable descendant; other agents claim ready tasks themselves.
Read tasks with team_task_list or team_task_get, claim with the current revision, perform the work, then complete the task. Dependencies determine readiness; write scopes describe expected edits and overlapping scopes are advisory, not locks. Task readiness does not start an agent.
Task changes do not end wait_agent calls, add inbox messages, or start idle agents. Use send_message when an agent needs to act on a task update.
Token effect
The section is a fixed cost on every request of every Team member.
KV Cache effect
The text is identical for the Lead and every descendant and does not change while the plugin stays loaded, so it keeps a stable system-prompt prefix, including between a parent and its subagent_fork child. Loading or unloading the plugin changes the system prompt of every member and invalidates their cached prefixes.
Team identity runtime context
What the model sees
While Team is enabled and its root is available, required team:identity context uses the following text, replacing <agent-id> or <root-id> with the JSON-encoded Session id derived from the subagent tree. Otherwise it contributes no text. Optional-context suppression cannot remove an enabled identity; the ordinary runtime-context mechanism restores it after compaction.
Root identity
You are the Team Lead. Your agent id is <agent-id>.
Teammate identity
You are a teammate in the Team led by agent <root-id>.
Token effect
Identity is part of the full runtime-context snapshot. Stable retained context adds no new message.
KV Cache effect
Identity appends through runtime context while shared system text stays identical across members. An ordinary Session fork in Team mode receives its own root identity; actual provider cache reuse remains best-effort.
Task tool schemas
What the model sees
Every member receives the same four task schemas in the generated tool catalog. Results are compact JSON task views or pages. Root-only reassignment is enforced at execution, not through different schemas.
Token effect
The four schemas are a fixed cost per request. Tool results add compact JSON; team_task_list returns at most 100 tasks per page.
KV Cache effect
The schemas are identical for the Lead and every descendant, including subagent_fork children, so a fork's tool list matches its parent's request prefix. Tool results append after the reusable prefix. Loading or unloading the plugin changes every member's tool list and invalidates their cached prefixes.
Known Limitations and Deferred Work
These limits describe what the policy and tools cannot guarantee for a team. They are current package constraints, not a comparison with other collaboration surfaces.
- Prompt policy is coordination, not confinement — it cannot stop Bash or external processes from writing overlapping files.
- Task authority needs a live root — tool availability does not guarantee that the caller’s root remains available when an operation executes.
- No Web controls — browser task-board presentation is outside this runtime package.
Dev Note
Working context for maintainers — click to expand
None.