Agent Team Guide

Agent Team Quick Build Guide

This skill guides users to quickly build leader-teammate multi-agent collaboration teams based on the com.openjiuwen.agentteams package. The framework main line: LeaderTeammateAgentTeam.Builder declares the team -> build() creates TeamAgent via TeamFactory -> interact / deliverInput / broadcast / dispatchTask triggers collaboration.

Core Mental Model

• LeaderTeammateAgentTeam is the declarative entry point, TeamAgent is the runtime host.
• TeamBackend is the data and message hub, Messager is the transport layer, TeamDatabase is the storage layer.
• CoordinatorLoop does not make decisions; it only handles wake-up and periodic polling. The actual collaboration logic is in EventDispatcher + team tools.
• The leader collaborates with teammates through team tools (send_message/update_task/claim_task/spawn_member); teammates enter their own ReAct loop via invokeForSpawn(...).

Key Concepts Quick Reference

Scenario Quick Reference Table

Jump directly to the corresponding section based on the task scenario:

Quick Start: Minimal Team

Minimal example: default leader is auto-included, no predefined teammates, teamMode=default (leader dynamically spawns at runtime).

import com.openjiuwen.agentteams.LeaderTeammateAgentTeam;

LeaderTeammateAgentTeam team = LeaderTeammateAgentTeam.builder()
        .teamName("investment_analysis")
        .description("Investment analysis collaboration team")
        .lifecycle(LeaderTeammateAgentTeam.LIFECYCLE_TEMPORARY)
        .teammateMode(LeaderTeammateAgentTeam.TEAMMATE_MODE_BUILD)
        .spawnMode(LeaderTeammateAgentTeam.SPAWN_MODE_INPROCESS)
        .storage(LeaderTeammateAgentTeam.STORAGE_SQLITE)
        .leaderMemberName("team_leader")
        .leaderDisplayName("Investment Lead")
        .leaderPersona("Senior investment analysis expert, skilled at decomposing complex problems and assigning suitable members")
        .language("cn")
        .build()
        .build(); // First build() assembles spec, second build() creates TeamAgent

Map<String, Object> result = team.dispatchTask("Analyze the latest financial report of 600519");

Two build() calls are both required: The first generates TeamAgentSpec, the second actually creates TeamAgent via TeamFactory.createAgentTeam(...).

Quick Start: With Predefined Members

Add addPredefinedMember(...) to declare fixed members. As long as a non-HUMAN_AGENT predefined member is passed, the Builder automatically resolves teamMode to hybrid.

import com.openjiuwen.agentteams.schema.team.TeamMemberSpec;
import com.openjiuwen.agentteams.schema.team.TeamRole;

LeaderTeammateAgentTeam team = LeaderTeammateAgentTeam.builder()
        .teamName("investment_analysis")
        .lifecycle(LeaderTeammateAgentTeam.LIFECYCLE_TEMPORARY)
        .addPredefinedMember(TeamMemberSpec.builder()
                .name("fundamental_analyst")
                .role(TeamRole.MEMBER)
                .description("Fundamental analyst")
                .modelName("fundamental_model")
                .build())
        .addPredefinedMember(TeamMemberSpec.builder()
                .name("technical_analyst")
                .role(TeamRole.MEMBER)
                .description("Technical analyst")
                .modelName("technical_model")
                .build())
        .build()
        .build();

Prerequisites (Must Read for Beginners)

Before copying the quick start code above, confirm three things, otherwise it won't run:

1. Maven compile path: The examples/ directory is not in the Maven compile path by default (pom.xml doesn't register it as a source root). Either move examples/ under src/main/java/, or add it as a source root in your IDE, otherwise examples.agent_teams.AgentTeamE2eExample won't be found.
2. API configuration: Fill real values for API_BASE / API_KEY / MODEL_PROVIDER / MODEL_NAME in src/main/resources/apiconfig.json. SharedExampleApiConfigLoader reads this file from classpath by default. Placeholder values (like your-api-key) will throw IllegalStateException: Missing required key in apiconfig.json at startup. Override with -Dopenjiuwen.example.config=<path> or OPENJIUWEN_API_CONFIG environment variable.
3. Team skill placement: If using team skills (like investment-analysis-team), place them in a directory the framework will scan, otherwise the leader won't discover them:
   • Team workspace skills/: ~/.openjiuwen/.agent_teams/<team_name>/team-workspace/skills/
   • Global: ~/.openjiuwen/workspace/skills/
   • skills/ subdirectory of the current working directory

Startup command (example):

mvn exec:java -Dexec.mainClass=examples.agent_teams.AgentTeamE2eExample

Configuration Parameters Quick Reference

Config Choice: teammateMode

Determines the execution path after a teammate claims a task:

• build_mode: Teammate executes autonomously and marks completion directly, no leader approval needed. Default choice.
• plan_mode: Teammate must first write_plan to submit a plan, wait for leader approve_plan approval before executing. Use when strict quality gate control is needed.

Config Choice: teamMode

Determines the leader's workflow template and available team tools:

• default: Leader dynamically spawns teammates at runtime, tool set includes spawn_member. Default for minimal team.
• predefined: All members are determined at assembly time, spawn_member is excluded.
• hybrid: Has both predefined members and allows leader to dynamically expand. Automatically becomes hybrid when predefined members are passed.

Configuration Details

• When no explicit leader is declared, TeamAgentSpec.ensureLeader() automatically adds a default leader named team_leader.
• When spawnMode=inprocess, members share the same JVM, convenient for local debugging; in process mode, members run as independent processes and must configure pyzmq transport.
• Reserved member names (team_leader / human_agent / user) cannot be arbitrarily used; TeamAgentSpec.validate() checks this.
• File layout is managed by TeamPaths: team directory ~/.openjiuwen/.agent_teams/<team_name>/, shared memory under team-workspace/team-memory/.

Run Mode: Run Leader Directly

After assembly, call dispatchTask(...) directly:

Map<String, Object> result = team.dispatchTask("Summarize this week's investment views");
// result contains team_id, session_id, status, leader, route, target, delivered_content, message_id

When streaming output is needed:

Iterator<Object> chunks = team.agent().stream(Map.of("query", query), sessionApi);
while (chunks.hasNext()) {
    Object chunk = chunks.next();
    // Process streaming fragment
}

Run Mode: Continuous Interaction with User

Both interact(...) / deliverInput(...) put input into CoordinatorLoop, the difference is whether the agent runtime goes through steer:

team.interact("Look at the valuation from another angle");      // Equivalent to deliverInput(message, true)
team.deliverInput("Supplement with the latest data", false);

// Leader proactive broadcast
String messageId = team.broadcast("Please check your responsible task status");

Run Mode: Resume and Destroy

// Persistent team: resume from existing snapshot
TeamAgent restored = TeamFactory.recoverAgentTeam(snapshot);

// Switch to new session: keep alive teammates, re-spawn
team.resumeForNewSession(newSessionId);

// Resume existing session: no re-spawn, just session binding
team.recoverForExistingSession(existingSessionId);

// Batch recover abnormal members
List<String> restarted = team.recoverTeam();

// Destroy
team.destroyTeam();          // Equivalent to destroyTeam(true)
team.destroyTeam(false);     // Don't force-close other members

Get snapshot via team.snapshot(), which internally contains spec, context, leader_inbox, messages, and model allocator state.

Team Tool Set

TeamTools.createTeamTools(role, backend, teammateMode, excludeTools, ...) filters tools by role, TeamAgent.registerTeamTools() adds team_name.member_name suffix to each tool's card id to avoid conflicts.

Dynamic Adjustment Rules:

• teamMode=predefined -> spawn_member is excluded, leader cannot expand members.
• teammateMode=plan_mode -> teammate gets extra write_plan, leader gets extra approve_plan.
• All members (including leader) additionally register file_io for reading/writing files in the team workspace (typically writing .team/reports/T*.md).

Member State Machine

Members transition between two sets of states at runtime:

• MemberStatus: UNSTARTED -> READY -> BUSY -> SHUTDOWN_REQUESTED -> SHUTDOWN, error path goes through RESTARTING / ERROR. Each transition publishes a member_status_changed event via Messager.
• ExecutionStatus: IDLE -> STARTING -> RUNNING -> COMPLETING -> COMPLETED, cancel and failure branches: CANCEL_REQUESTED / CANCELLING / CANCELLED / FAILED / TIMED_OUT.

Both enums have built-in canTransitionTo(...) legality checks. When troubleshooting member anomalies, first check MemberStatus for ERROR / RESTARTING, then check ExecutionStatus for FAILED / TIMED_OUT.

Event-Driven and Coordination Mechanism

TeamAgent collaboration relies on two event streams merging into the CoordinatorLoop queue, then unified dispatch by EventDispatcher.dispatch(event).

Event Sources:

CoordinationManager.subscribeTransport() subscribes to the 4 topics when the leader first stream(...) or teammate invokeForSpawn(...). All transport events go through echo suppression before enqueuing (localMember.equals(event.getSenderId()) skips), preventing members from receiving their own events.

Key Event Routing:

Auto-completion: StreamController calls tryAutoCompleteMemberTasks at the end of a member's ReAct round -- if the member sent send_message to the leader this round, the framework automatically claims + completes all unfinished tasks under that member. The member doesn't need to explicitly call complete_task.

Multi-stage Data Flow

Multi-stage pipelines like investment-analysis-team rely on framework built-in mechanisms, no need for leader explicit scheduling:

1. Create tasks with dependencies: Leader create_task(..., dependencies=["T1","T2"]), TeamTaskManager.add(...) sets the dependent task as blocked initially, records edges in TaskDependencyRecord table.
2. Member completes upstream task: After member claims and completes T1, completeResult(...) marks it as completed, publishes task_completed.
3. Framework captures upstream output: EventDispatcher.tryAutoCompleteMemberTasks detects member sent send_message to leader, collects message content into TeamResultCollector (key = teamName + memberName).
4. Auto-unblock downstream: tryDeliverToNextStage iterates all blocked tasks, when all dependencies are completed, retrieves each dependency assignee's output from TeamResultCollector, assembles a member_results_delivery event, publishes it to the downstream assignee via team:message topic.
5. Downstream member receives: EventDispatcher verifies target_assignee == localMember then deliverInput(content), injecting upstream results into its ReAct loop.
6. team_mode=predefined special handling: When downstream assignee includes leader, the delivered message is accompanied by a strong constraint prompt "You are the leader, must use file_io to write the final report and complete this task yourself", preventing the leader from re-delegating the final task.

HITT: Human Member Collaboration

When enableHitt=true, members with role=HUMAN_AGENT can be added:

• TeamRail.buildTeamHittSection(...) generates different collaboration rules for leader, teammate, and human_agent perspectives.
• Leader cannot ask human members in plain text, must use send_message.
• Human agent only has the send_message tool, no claim_task / update_task / spawn_member.
• exposeHumanAgentsToTeammates controls whether human members are visible to teammates.
• If HUMAN_AGENT members exist, enableHitt must also be enabled, otherwise TeamAgentSpec.validate() throws an error.

Team Skill: Team Skill Discovery

TeamAgent.setupAgent() defaults to enableSkillDiscovery(true) + skillMode("all"), scanning directories:

• Team workspace skills/ node
• Current working directory (System.getProperty("user.dir"))
• ~/.openjiuwen/workspace/skills

HarnessFactory automatically appends SkillUseRail when hasConfiguredSkills(source) || source.isEnableSkillDiscovery(), responsible for:

• Scanning skill directories, loading local and remote skills (incremental hot-reload based on mtime signatures).
• Registering list_skill and skill_tool tools, enabling leader/teammate to discover and invoke skills in the ReAct loop.
• Injecting a prompt section named skills in beforeModelCall.

Two evolutionary rails (com.openjiuwen.harness.rails):

• TeamSkillRail: Listens to member view_task, triggers a "team evolution analysis" event when all tasks are complete, consolidating collaboration experience.
• TeamSkillCreateRail: After leader calls spawn_member reaching threshold (default 2 times), schedules a follow-up prompt guiding the leader to use the team-skill-creator skill to codify this collaboration pattern as a new team skill.

Place team skills under the team workspace skills/ or ~/.openjiuwen/workspace/skills/, the team will automatically discover and load them on the next execution.

Team Skill Standard Directory Structure

A complete team skill (like investment-analysis-team) consists of 5 parts:

Typical Runtime Lifecycle

1. Use LeaderTeammateAgentTeam.builder() to configure teamName, lifecycle, teammateMode, spawnMode, transport, storage, leader, predefined members.
2. Call build() -> TeamFactory.createAgentTeam(spec) constructs TeamAgent, internally assembling ModelAllocator, TeamBackend, CoordinatorLoop, EventDispatcher, RecoveryManager, SpawnManager, StreamController, and creates the leader's own DeepAgent.
3. Call interact(...) / deliverInput(...) / dispatchTask(...) / stream(...) to trigger CoordinatorLoop wake-up, EventDispatcher consumes events.
4. Leader collaborates with teammates through team tools; teammates enter their own ReAct loop via invokeForSpawn(...).
5. After tasks complete, temporary team is wrapped up by leader calling shutdown_member then clean_team; persistent team keeps running waiting for new instructions.

Usage

1. Scenario positioning: First use the "Scenario Quick Reference Table" to jump to the corresponding section based on current task.
2. Copy Template: Code blocks in the quick start sections can be directly copied and modified. Remember to change teamName, leaderPersona, member names, modelName.
3. Config Decision: When unsure about configuration, check "Configuration Parameters Quick Reference" and "Config Choice" sections.
4. Troubleshoot: First check "Pitfall FAQ", then "Member State Machine" and "Multi-stage Data Flow".
5. Extend Capabilities: Need team skill see "Team Skill" section; need human collaboration see "HITT" section.
6. Don't Fabricate When Unsure: API details are subject to source code; this skill does not replace official API documentation.

Pitfall FAQ (High-frequency Issues Quick Reference)

Most common pitfalls for beginners, located by symptom:

Subsystem and Sub-package Quick Reference

Not Yet Implemented / Usage Boundaries

• Complete controller-style declarative team orchestration (leader runtime spawn is still the primary path).
• Unified selector API for multiple ModelAllocator strategies (currently only built-in round_robin and by_model_name).
• Complete lifecycle for health check and auto-recovery (SpawnHandle exposes startHealthCheck, but it's not enabled by default).

Safe approach: Build team assembly on LeaderTeammateAgentTeam + TeamAgent + TeamBackend; extend agent / tools / monitor sub-packages when finer collaboration control is needed.

Reference Entry Points

• Full documentation: documents/zh/2.Development Guide/Multi-Agent/AgentTeams.md
• Example code: examples/agent_teams/AgentTeamE2eExample.java + AgentTeamE2eExampleSupport.java
• Example team skill: examples/agent_teams/skills/investment-analysis-team/
• API documentation: documents/zh/API Documentation/com.openjiuwen.agentteams/ sub-modules
• Minimal runnable example: references/MinimalRunnableExample.java (self-contained, includes model config, copy and run)