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

description, kind
description kind
Five task-board and wait tools plus coordination guidance for every member of an experimental Team composition. package-reference

@deepseek-ai/dsh-experimental-tool-agent-team

English | 中文

Summary

This package lets every Team member coordinate shared work: create, claim, and complete tasks on the shared board, and wait for teammates instead of polling. Each member also receives the shared-checkout coordination policy and a statement of its role. Creating, messaging, listing, and interrupting teammates stay on the standard subagent tools, so the package adds only five tool schemas. It is published under its experimental name and provides no stability guarantee.

Table of Contents


Use this package

Add this package on top of @deepseek-ai/dsh-experimental-agent-team when Team members should coordinate through tools. Once mounted, the Lead and every subagent below it, fresh or fork, get the same five tools, the same policy section, and a required runtime-context statement of their role.

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 five tools cover two capabilities; the standard subagent tools cover the third:

  • 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 teammates — wait_agent waits for the next task, member status, or inbox change after the call starts.
  • 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 ownerName results use agent names; the root is lead. Descriptions may repeat. Any member can use the board; only the Lead reassigns tasks. Updates enforce ownership and revision checks, rejecting stale edits.

What success and failure look like

Task tools return compact JSON task views or task pages. A stale expected_revision, an unauthorized action, or an unready task is reported as a tool error instead of overwriting newer work. wait_agent returns { "timedOut": false } after a change and { "timedOut": true } at its timeout; when no other member is running, it returns noProgress with reason no-active-peer right away, telling the caller to wake a teammate with send_message first.


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:

  • Scoped, not global. Every registration lives on the member Agent's own ctx; installation uses the Team membership available when the Agent is published.
  • 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, the fixed policy text, identity context, and the five scoped tool registrations

Policy and tools

One team:policy section and one required team:identity runtime-context entry on the member scope carry the shared coordination rules and the member's role; the fixed text and the five tool registrations are declared in src/index.ts. The five tool schemas are registered in every scope recognized as a Team member at publication, including fork children, so parent and fork requests list identical tools and system prompts. No registration shares a name with a subagent control, so send_message, list_agents, and interrupt_agent resolve to the global subagent tools in every member scope.

Scoped registration and teardown

maybeInstall runs for every live Agent and subscribes to agent/created; it skips Agents without Team membership. Disposal of an Agent runs the installed disposer, and plugin HMR disposes every installed scope before reinstall. Each disposer unwinds registrations in reverse order, so 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
Agent Teams is available in this session. Teammates are subagents. Use agent names with send_message to reach your direct continuable children or, as a continuable subagent, your parent and continuable siblings. Descriptions explain responsibilities and may repeat.

The Team Lead and all teammates share the same working directory and filesystem. Edits are immediately visible to every member. Split write work into disjoint scopes, record expected write scopes on shared tasks, and use task dependencies when work must be ordered. Write-scope overlap is advisory, not a lock.

Prefer read/edit/write for file changes. If a file operation returns FS_STALE_VERSION, read the current file, rebase your intended change onto the new content, and retry. Bash, formatters, code generators, and scripts are not fully protected by the filesystem version guard; coordinate them explicitly and have the Lead review the final diff and run tests.

Use agent names as task owners; the root agent is named lead. The Lead can reassign to itself, its direct continuable children, or historical members; other descendants claim tasks themselves. list_agents shows direct contacts and all reachable continuable descendants; discovery does not grant message or assignment authority. inactive means no turn is executing; it does not describe task completion, success, failure, or waiting for other agents. A successful send does not mean the recipient has processed it. Shared-task workflow is list, get, claim with the current revision, perform the work, then complete. Task readiness never starts an owner. Before wait_agent, make sure another required member is running; use send_message first for an inactive direct contact, or coordinate through its parent for a deeper member. wait_agent observes only changes after that call starts, never wakes a member, and returns noProgress immediately when no other member is running. Re-list after wakeup or timeout. The Lead must wait for required teammates before giving the final answer.

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 runtime context states You are the Team Lead. Your name is lead. for a root and Your name is "<name>". You are a teammate in the Team led by "lead". for a subagent. It follows current membership, survives optional-context suppression, and is restored after compaction. An ordinary fork of a teammate is a new root and receives the Lead statement.

Token effect

Identity is part of the complete runtime-context snapshot. An unchanged retained snapshot adds no message; changed or removed context causes the loop to append a complete snapshot, including identity.

KV Cache effect

Identity arrives in a runtime-context snapshot after the request prefix, so a subagent_fork child keeps its parent's system prompt, tools, and inherited messages and appends its teammate statement after them. Actual provider cache hits remain best-effort.

Task and wait tool schemas

What the model sees

Every Team member receives the same five schemas, listed in the generated tool catalog. Results are compact JSON task views, task pages, or wait values. When no other member is running, wait_agent returns noProgress with reason no-active-peer and the message No other Team member is running. wait_agent cannot make progress or wake inactive teammates. Re-list with list_agents and team_task_list, then use send_message to wake a required inactive direct contact before waiting again; coordinate deeper members through their parent. Lead-only reassign is enforced at execution, not by a different schema.

Token effect

The five schemas are a fixed cost on every Team member request. Tool calls add compact JSON results; 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.
  • Installation follows publication — an Agent that is not a Team member when it is published, such as a subagent whose parent is not loaded, receives no Team tools, policy, or identity, even after its parent loads.
  • No Web controls — browser roster and 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.