When a business request requires multiple Agents to divide the work, TeamHarness lets them split tasks, perform work, and deliver results under a shared set of rules. You do not need to repeat the collaboration workflow in your prompts. The platform already provides team member information, collaboration rules, and the accompanying Skills; you mainly define each Agent's business responsibilities and delivery requirements.
Typical scenario
After a user submits a request through an AG-UI application or through DingTalk, Lark, or WeCom, the team leader (Leader) creates an asynchronous task and the executing members (Worker) complete the work as assigned:
The user submits a request.
The Leader creates an asynchronous task.
The team divides and performs the work in the task room.
The Leader reviews the results, consolidates them, and delivers them.
After the task is created, the user does not need to keep the original conversation connected. Collaboration continues in the task room, and the platform notifies the relevant members when the task status changes.
How custom Agent instructions fit together
Instructions and capabilities are divided into the following four parts by responsibility:
Your definition (business) — Determines what the Agent does, how it handles the business, and what it delivers.
Harness (execution) — Calls models and tools to drive execution.
TeamHarness (collaboration) — Provides the team identity and collaboration rules, and organizes the division of labor, feedback, and delivery.
Skills (methods) — Read business or collaboration skills on demand to complete specific operations.
At runtime, the business definition, the base Harness rules, and the TeamHarness collaboration rules are provided to the model together with the current session, and Skills are read on demand. This division describes responsibility relationships and does not mean that prompts are concatenated in a fixed order or priority.
Take a data analyst as an example: you describe the analysis methods and report requirements in the business definition, Harness performs tool calling, TeamHarness instructs the Agent to take on tasks as a Worker and submit results, and Skills provide the specific methods.
Capability matrix
The following capabilities apply to team collaboration under a managed Harness and are supported by both QwenPaw and Qoder. Task scheduling, archiving, and channel notifications are provided by the supporting platform services.
| Dimension | Capability | QwenPaw and Qoder |
| Team | Team roles and division of labor (Leader and Worker) | Yes. The Leader organizes work and consolidates results, and the Worker performs the assigned work. |
| Team | The same Agent joining multiple teams | Yes. The Agent uses the team identity and role that correspond to the current request. |
| Team | Member communication and message wake-up | Yes. Supports wake-up by @mention. |
| Task | Task planning and dynamic adjustment | Yes. QwenPaw supports plans and adjustments to the content of existing nodes; Qoder supports plans and dependency-based progression. |
| Task | Task breakdown and subtask delegation | Yes. The Leader creates tasks and assigns subtasks to Workers. |
| Task | Task participant adjustment | Yes. Adjust participants and Agents as needed. Agent teams join automatically by default, and humans are specified as needed. |
| Task Schedule | Task fallback fault tolerance | Yes. Supports startup timeout retries, runtime timeout alerts, and session-loss recovery alerts. |
| Task Schedule | Task concurrency throttling | Yes. Supports per-Agent throttling and queuing for tasks and subtasks, with capacity control based on AgentRuntime. |
| Task Schedule | Automatic task archiving | Yes. Supports automatic archiving of tasks in final states, with FIFO truncation based on time expiration and volume pressure. |
| Task notifications | DingTalk, Lark, and WeCom | Yes. Status changes are sent to users by a bot. |
| Scheduled tasks | Team scheduled tasks | Yes. Supports creating, updating, starting, stopping, and manually triggering team scheduled tasks, and depends on the scheduling service. |
Legend: Yes indicates that the capability is supported. Some capabilities require configuration.
Prerequisites
Before you use TeamHarness for team collaboration, complete the following setup. This topic does not cover these operations.
Create and configure an Agent. For instructions, see Agent usage guide (managed Harness).
Configure and manage teams and tasks in the AgentCore console. For instructions, see Team collaboration guide (task system).
How Agents collaborate
Roles and responsibilities
Leader — Organizes tasks, arranges the division of labor, coordinates issues, and reviews and consolidates results.
Worker — Performs assigned subtasks, reports issues, and submits results.
You define business identities such as data analyst and development engineer, and the platform configures the Leader and Worker team roles. The same Agent can take on different roles in different teams, and a self-introduction in the prompt does not change its permissions.
Task rooms and non-task rooms
A task room is a dedicated session for performing a specific task. Private chats, team chats, group chats, and regular conversations in AG-UI or IM are non-task rooms.
In a non-task room:
The Leader replies directly to general conversation. The Leader creates a task when the work requires team execution, must continue across sessions, requires ongoing delivery tracking, or when the user explicitly requests a task.
Workers can join the conversation. Team work that requires formal execution is organized by the Leader.
In a task room:
The Leader drives the current task, arranges the division of labor, reviews results, and completes delivery.
Workers perform their assigned subtasks, report issues, and submit results.
When the request is clear, the Leader creates the task directly; when an important ambiguity affects delivery, the Leader clarifies it with the user first. After the task is created, the current turn ends and the subsequent work continues in the task room. Request adjustments and result feedback for an existing task are handled in the original task. An @mention is used only for communication and wake-up and does not mean that a subtask has been assigned.
Workflow inside a task room
A task records the overall goal, and a subtask records the specific work assigned to a Worker. The built-in collaboration workflow includes the following stages:
Assign work — The Leader uses the plan orchestration Skill to assign subtasks. Independent subtasks support parallel execution, and dependent subtasks proceed after the preceding results are accepted.
Perform work — After confirming acceptance, the Worker performs the work according to the subtask requirements, completes the necessary checks, and does not operate on other members' tasks.
Submit and review — The Worker submits the subtask result, and the Leader accepts the result or provides revision comments. When changes are required, continue to use the original subtask to preserve result versions.
Handle issues — The Worker reports a blocker in the subtask and the Leader coordinates; the Leader reports the task as blocked only when the overall work cannot proceed.
Wait and continue — When waiting for other members or for a review, end the current turn and resume when the subsequent notification arrives instead of polling in a loop.
Deliver — The Leader consolidates the accepted results and submits the task result. Whether final manual acceptance is required is determined by the task configuration.
Also note the following during collaboration:
When no suitable Worker is available, the Leader can complete the work directly within its own capabilities and permissions, without creating a subtask assigned to itself.
Generating a file or replying "done" does not replace submitting the result. Save delivered files by using the built-in Skill and reference them in the result.
The Leader does not need to repeat all of the Worker's checks when reviewing; when independent testing or expert review is required, arrange the corresponding work.
When an existing task requires additional information from the user, raise it through the blocked-task feedback path instead of only asking in the task room.
After receiving a notification, confirm the current status before continuing, so that delayed notifications do not cause duplicate submissions.
Multiple teams and temporary assistants
When an Agent is a Worker in one team and a Leader in another, it can delegate work to the team that it leads through the built-in workflow: submit the upstream subtask result only after the downstream task is completed and accepted and the files are handed over. Permissions and task states on both sides are managed separately and are not automatically canceled, resumed, or accepted together. A temporary Subagent is an execution assistant; it does not automatically become a team Worker and cannot replace a formal subtask.
Write Agent instructions
Write business requirements, not collaboration workflows
In an instruction file such as AGENTS.md or in the system prompt, specify the following four items:
What to do — The professional responsibilities and business scope.
How to do it — The methods, tools, and data usage requirements.
What to deliver — The output format, quality standards, and required checks.
Which operations require authorization — For example, modifying production data, deploying, or publishing externally.
Use the information that the platform provides for team members and roles, and do not hard-code accounts or team IDs. File names and configuration entries depend on the Harness and Agent template in use.
A Leader instruction must also describe the business expertise of members, the approach to dividing work, and how to convert business requests into task goals and delivery requirements. A Worker instruction only needs to define business processing capabilities and does not need to repeat built-in rules such as team scheduling, status feedback, and result submission.
Avoid conflicting instructions
| Avoid | Do this instead |
| Performing a task immediately after being @mentioned. | Perform work only when it is assigned as a formal subtask, and use regular messages for communication. |
| The Worker only generates files and the Leader submits them. | The Worker submits its own results, and the Leader reviews and consolidates them. |
| Ending a task by replying "done". | Submit the result through the built-in workflow and then briefly confirm. |
| Polling continuously until other members finish. | Wait for the collaboration notification before continuing. |
| Always asking the user directly when information is missing. | Clarify directly in regular conversations, and report issues that occur during task execution through the blocked-task workflow. |
| Creating a new task after receiving revision comments. | Revise within the original task or subtask. |
| Prohibiting all command execution. | Limit the scope of business operations while retaining the execution capabilities that the built-in collaboration tools require. |
When you find a clause that conflicts with the built-in collaboration rules, rewrite that clause directly instead of only appending a statement such as "TeamHarness takes precedence". You do not need to copy the commands or prompts of the built-in Skills.
Leader example: business analytics team
Assume that the team has two types of Workers, data analytics and report writing. You can define the Leader as follows:
Business responsibilities — Organize business analytics and convert user requests into clear analysis goals and delivery requirements.
Members and division of labor — The data analytics member queries and analyzes business data, explains metric changes, and provides conclusions with supporting evidence; the report writing member writes reports based on accepted analysis results and does not add unconfirmed data or conclusions.
Requests and tasks — Answer consultations about metric definitions or analysis methods directly in the conversation, and organize the work as a task when actual analysis and a delivered report are required. When creating a task, record the analysis scope, time range, statistical criteria, delivery format, and acceptance criteria. Clarify unclear key information first, and do not add business goals on your own.
Approach to dividing work — Arrange data analytics first in the task room, and arrange report writing when a report is needed. Report writing depends on accepted analysis results, and work items without dependencies can proceed in parallel; when the user needs only conclusions, do not arrange an additional report; when an independent review is needed, assign the review as explicit work.
Delivery requirements — Consolidate the results, answer the user's business question, and explain the main conclusions and important limitations. Obtain authorization first when the work involves modifying production data or publishing externally.
Worker example: data analytics member
You can define the data analytics Worker as follows:
Business responsibilities — Analyze business data, explain metric changes, and form conclusions, without modifying production data.
Working methods — Use authorized data sources and the statistical criteria specified in the task; distinguish data facts from analytical inferences and from conclusions that are pending verification, and do not fabricate missing data.
Delivery requirements — Deliver the analysis conclusions or data files required by the subtask and describe the statistical criteria and important limitations; report only the checks that were actually performed and their results.