Files
deepseek-harness/packages/experimental/tool-agent-team

description, kind
description kind
Four task-board tools and shared-task guidance for an experimental Team composition. package-reference

@deepseek-ai/dsh-experimental-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 package is experimental and provides no stability guarantee.

Table of Contents


Use this package

Mount this package with @deepseek-ai/dsh-experimental-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-experimental-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, and team_task_update add, browse, read, and update shared tasks.
  • Wait for inbox input — wait_agent belongs to @deepseek-ai/dsh-tool-subagent-control and remains available without this package.
  • Create and reach teammates — subagent, subagent_fork, send_message, list_agents, and interrupt_agent come 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:

  • Agent-scoped registration. Every live Agent receives its task tools and policy on its own ctx; 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 execute against 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 scoped task tools

Policy and tools

One team:policy section, required team:identity context, and four task schemas are registered on each Agent scope, including fork children. Identity comes from ctx.subagents.rootOf(agent), without a separate membership service. If the root is unavailable, the context reports that shared tasks, subagent discovery, and messaging are unavailable; it does not infer a parent from Session lineage. Communication and waiting belong to subagent controls; the subagent runtime delivers final results.

Scoped registration and teardown

Installation covers current live Agents and subscribes to agent/created. Agent disposal and plugin HMR unwind registrations in reverse order; a failed install cannot leave a partial scope.


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.


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

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. If the root is unavailable, the context reports that fact and permits independent work. Optional-context suppression cannot remove this 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.
  • Experimental prototype with no stability promise — the package is public, but its schemas can change freely while it incubates.

Dev Note

Working context for maintainers — click to expand

None.