multi-agent-collaboration

name	multi_agent_collaboration
description	Use this skill when another agent's expertise or context is needed, or when the user explicitly asks to involve another agent. First list agents, then use qwenpaw agents chat for two-way communication with replies.
metadata	{"builtin_skill_version":"1.4","qwenpaw":{"emoji":"🤝"}}

Multi-Agent Collaboration

When to Use

Use this skill when you need another agent's expertise, context, workspace content, or collaborative support. If the user explicitly asks a specific agent to participate/assist/answer, you should also use this skill.

Should Use

• The current task is clearly better suited for a specialized agent
• You need another agent's workspace / files / context
• You need a second opinion or expert review
• The user explicitly asks for a specific agent to participate or to invoke another agent

Should Not Use

• You can complete the task on your own and the user has not explicitly asked to invoke another agent
• It is just a normal Q&A that does not require a specialized agent
• Information is insufficient -- you should ask the user for clarification first
• You just received a message from Agent B -- do not call Agent B again to avoid loops

Decision Rules

1. If the user explicitly requests invoking another agent, prioritize following the request
2. Otherwise, if you can do it yourself, do not invoke another agent
3. Check agents before invoking -- do not guess IDs
4. When context continuation is needed, you must pass --session-id
5. Do not call back the source agent

---

Most Common Commands

1) First Query Available Agents

qwenpaw agents list

2) Start a New Conversation (Real-time Mode)

qwenpaw agents chat \
  --from-agent <your_agent> \
  --to-agent <target_agent> \
  --text "[Agent <your_agent> requesting] ..."

3) Submit a Complex Task (Background Mode)

Complex tasks include: data analysis, report generation, batch processing, external API calls, etc.

qwenpaw agents chat --background \
  --from-agent <your_agent> \
  --to-agent <target_agent> \
  --text "[Agent <your_agent> requesting] ..."

Output:

[TASK_ID: xxx-xxx-xxx]
[SESSION: ...]

4) Query Background Task Status

qwenpaw agents chat --background --task-id <task_id>

Important: Do not query frequently! After submitting a task:

1. Do not block - Continue handling other tasks or work
2. Wait a reasonable time before querying - Choose based on task complexity:
   • Simple analysis: query after 10-20 seconds
   • Complex analysis: query after 30-60 seconds
   • Batch processing: query after 1-3 minutes
3. During the wait - You can reply to the user, handle other requests, or execute other tasks

5) Continue an Existing Conversation

qwenpaw agents chat \
  --from-agent <your_agent> \
  --to-agent <target_agent> \
  --session-id "<session_id>" \
  --text "[Agent <your_agent> requesting] ..."

Key points:

• Not passing --session-id = new conversation
• Passing --session-id = continue conversation (context preserved)
• Use --background for complex tasks; record the task_id after submission

---

Task Mode Selection

Real-time Mode vs Background Mode

Task Type	Mode to Use	Command
Simple quick query	Real-time mode	qwenpaw agents chat
Complex task (data analysis, batch processing, etc.)	Background mode	qwenpaw agents chat --background

Examples of complex tasks:

• Analyzing large amounts of data or log files
• Generating detailed reports
• Batch processing files (10+ files)
• Calling slow external APIs
• Independent tasks that need parallel execution

Decision criteria: If you are unsure how long a task will take, or if the task is complex, prefer background mode.

---

Minimal Workflow

Real-time Mode Workflow

1. Determine whether another agent is needed, or whether the user explicitly requested it
2. qwenpaw agents list
3. qwenpaw agents chat to start a conversation
4. Record [SESSION: ...] from the output
5. Include --session-id when context continuation is needed later

Background Mode Workflow

1. Determine whether the task is complex (data analysis, report generation, etc.)
2. qwenpaw agents list
3. qwenpaw agents chat --background to submit the task
4. Record [TASK_ID: ...] from the output
5. Continue handling other work
6. Wait a reasonable time (30-60 seconds) before querying status
7. Use --background --task-id to query results

---

Key Rules

Required Parameters

qwenpaw agents chat must include all of the following:

• --from-agent
• --to-agent
• --text

Identity Prefix

Messages should begin with the following prefix:

[Agent my_agent requesting] ...

Session Reuse

The first call will return:

[SESSION: your_agent:to:target_agent:...]

For subsequent follow-ups, you must copy this session_id and pass it via --session-id.

---

Brief Examples

User Explicitly Requests Invoking Another Agent

qwenpaw agents list

qwenpaw agents chat \
  --from-agent scheduler_bot \
  --to-agent finance_bot \
  --text "[Agent scheduler_bot requesting] User explicitly asked to consult finance_bot. Please answer what pending financial tasks are there."

New Conversation

qwenpaw agents chat \
  --from-agent scheduler_bot \
  --to-agent finance_bot \
  --text "[Agent scheduler_bot requesting] What pending financial tasks are there today?"

Continue Conversation

qwenpaw agents chat \
  --from-agent scheduler_bot \
  --to-agent finance_bot \
  --session-id "scheduler_bot:to:finance_bot:1710912345:a1b2c3d4" \
  --text "[Agent scheduler_bot requesting] Expand on item 2"

---

Common Mistakes

Mistake 1: Not checking agents first

Do not guess agent IDs. First run:

qwenpaw agents list

Mistake 2: Wanting to continue a conversation but not passing session-id

This will create a new conversation, losing context.

Mistake 3: Calling back the source agent

If you just received a message from Agent B, do not call Agent B again.

---

Optional Commands

View Existing Sessions

qwenpaw chats list --agent-id <your_agent>

Streaming Output

qwenpaw agents chat \
  --from-agent <your_agent> \
  --to-agent <target_agent> \
  --mode stream \
  --text "[Agent <your_agent> requesting] ..."

JSON Output

qwenpaw agents chat \
  --from-agent <your_agent> \
  --to-agent <target_agent> \
  --json-output \
  --text "[Agent <your_agent> requesting] ..."

---

Full Parameter Reference

qwenpaw agents list

Parameters:

• --base-url (optional): Override the API address

No required parameters -- just run it directly.

qwenpaw agents chat

Required parameters (real-time mode):

• --from-agent: Sender agent ID
• --to-agent: Target agent ID
• --text: Message content

Background task parameters:

• --background: Background task mode
• --task-id: Query task status (used together with --background)

Optional parameters:

• --session-id: Reuse session context (copy from previous output)
• --new-session: Force create a new session (even if session-id is passed)
• --mode: stream (streaming) or final (complete, default)
• --timeout: Timeout in seconds (default 300)
• --json-output: Output full JSON instead of plain text
• --base-url: Override the API address

---

Background Task Mode Details

When to Use Background Mode?

When the task is a complex task, use --background to submit it to the background:

Should use background mode:

• Data analysis (analyzing logs, computing statistics)
• Report generation (generating long reports or documents)
• Batch processing (processing multiple files)
• External API calls (calling slow services)
• Complex tasks with uncertain duration

Does not need background mode:

• Simple quick queries
• Tasks that are clearly going to complete quickly

Background Task Examples

Submitting a Complex Task

qwenpaw agents chat --background \
  --from-agent scheduler \
  --to-agent data_analyst \
  --text "[Agent scheduler requesting] Analyze user behavior in /data/logs/2026-03-26.log and generate a detailed report"

Output:

[TASK_ID: 20802ea3-832d-4fb4-86f0-666ad79fcc80]
[SESSION: scheduler:to:data_analyst:1774516703206:ec02e542]

✅ Task submitted successfully

Check status with:
  qwenpaw agents chat --background --task-id 20802ea3-...

Querying Task Status

Important: Do not block after submitting!

1. Continue handling other work - Reply to other user questions, execute other tasks
2. Query at the right time - After finishing other work, or when the user asks about progress
3. If you must wait - Use a reasonable interval (10-60 seconds); do not query immediately

# Method 1: Query after handling other tasks (recommended)
# After submitting the task, continue with the user's other requests
# Query at an appropriate time:
qwenpaw agents chat --background \
  --task-id 20802ea3-832d-4fb4-86f0-666ad79fcc80

# Method 2: If you must wait, use a reasonable interval
sleep 30 && qwenpaw agents chat --background \
  --task-id 20802ea3-832d-4fb4-86f0-666ad79fcc80

Status Descriptions:

Task status has two layers:

• Outer status (API response): submitted -> pending -> running -> finished
• Inner status (only when outer status is finished): completed (success) or failed (failure)

Possible outputs:

1. Submitted (may be seen when querying immediately after submission):

[TASK_ID: 20802ea3-832d-4fb4-86f0-666ad79fcc80]
[STATUS: submitted]

📤 Task submitted, waiting to start...

💡 Don't wait - continue with other work!
   Check again in a few seconds:
  qwenpaw agents chat --background --task-id 20802ea3-...

2. Pending:

[TASK_ID: 20802ea3-832d-4fb4-86f0-666ad79fcc80]
[STATUS: pending]

⏸️  Task is pending in queue...

💡 Don't wait - handle other work first!
   Check again in a few seconds:
  qwenpaw agents chat --background --task-id 20802ea3-...

4. Running:

[TASK_ID: 20802ea3-832d-4fb4-86f0-666ad79fcc80]
[STATUS: running]

⏳ Task is still running...
   Started at: 1774516703

💡 Don't wait - continue with other tasks first!
   Check again later (10-30s):
  qwenpaw agents chat --background --task-id 20802ea3-...

5. Completed successfully:

[TASK_ID: 20802ea3-832d-4fb4-86f0-666ad79fcc80]
[STATUS: finished]

✅ Task completed

(Task result content...)

6. Failed:

[TASK_ID: 20802ea3-832d-4fb4-86f0-666ad79fcc80]
[STATUS: finished]

❌ Task failed

Error: (Error message...)

Query Interval Strategy

Do not query frequently! After submitting a task, you should:

1. Continue handling other work - Do not block; go complete other tasks
2. Wait a reasonable time before querying - Choose the interval based on task complexity
3. Avoid blocking the current flow - This is the core value of background tasks

Task Type	Suggested First Query	Subsequent Interval	What to Do While Waiting
Simple analysis	After 10 seconds	5-10 seconds	Handle other user requests
Complex analysis	After 30 seconds	10-20 seconds	Complete other parts of the current conversation
Batch processing	After 1 minute	20-30 seconds	Execute other independent tasks
Very large tasks	After 2 minutes	30-60 seconds	Continue with the user's other work

Recommended Approach

Method 1: Query after handling other tasks (recommended)

# 1. Submit the task, record the task_id
qwenpaw agents chat --background ...
# Returns task_id

# 2. Continue handling the user's other requests or tasks
# (e.g., answer other questions, perform other operations)

# 3. Query the result at an appropriate time
# (e.g., after finishing the current task, or when the user asks about progress)
qwenpaw agents chat --background --task-id <id>

Method 2: Timed polling (if you must wait)

# Incrementally increasing intervals, fast first then slow
sleep 10 && qwenpaw agents chat --background --task-id <id>
sleep 20 && qwenpaw agents chat --background --task-id <id>
sleep 30 && qwenpaw agents chat --background --task-id <id>

Do Not Do This

# Wrong: querying too frequently
while true; do
    qwenpaw agents chat --background --task-id <id>
    sleep 1  # Too frequent!
done

---

Help Information

Use -h at any time to view detailed help:

qwenpaw agents -h
qwenpaw agents list -h
qwenpaw agents chat -h