Workforce Troubleshooting

Common causes:

• Description too vague (e.g., "make me a team")
• Clarification answers too short or generic
• Contradictory requirements in the description
• Temporary service issue

Solutions:

• Be more specific about roles: "1 sales manager, 2 SDRs" instead of "some sales agents"
• Provide more detail in clarification answers - complete sentences help
• Try generating again - transient errors resolve on retry
• Start with a simpler structure and add complexity incrementally

Common causes:

• Circular dependency: A → B → C → A
• Self-reference: Agent reporting to itself
• Duplicate edge: Same connection already exists

Solutions:

• Review your org chart for cycles - delegation should flow one way
• Use the Auto-Layout button to visualize the structure clearly
• Remove conflicting edges and recreate in the correct direction

Diagnostic steps:

1. Verify the bot is in the group (check member list)
2. Confirm the bot has admin permissions
3. Check you're using the exact @username
4. Look at the workforce dashboard for connection status

Solutions:

• Click "Reconnect" in workspace settings to re-establish webhooks
• Remove and re-add the bot to the group
• Verify the workforce is deployed (not in draft state)
• Check the bot token is still valid in BotFather

Solutions:

• Re-run the Telegram wizard Phase 2 (group setup)
• Ensure all bots are admins in the group
• Try creating a fresh Telegram group
• Check your internet connection - webhooks need stable connectivity
• Contact support if the issue persists after retrying

Solutions:

• Go to BotFather and use /mybots to find your bot
• Select the bot and click "API Token" to see the current token
• Copy the entire token including the colon and alphanumeric string
• If the token was revoked, generate a new one with /revoke
• Paste carefully - no extra spaces before or after

Diagnostic steps:

1. Check the writing agent's conversation logs
2. Verify memory_write was actually called
3. Confirm the key name is spelled correctly
4. Check if TTL expired on the written data

Common causes:

• Agent decided not to write (check conversation for reasoning)
• Key typo: writing "lead_info" but reading "leadInfo"
• Data expired due to short TTL
• Reading from wrong workforce (if agent is in multiple)

Diagnostic steps:

1. Verify the reporting line exists on the canvas
2. Check the parent's system prompt mentions delegation
3. Review conversation logs to see the agent's reasoning
4. Test with an explicit delegation request

Solutions:

• Add explicit delegation instructions to the parent's prompt
• Ensure the child agent is deployed (not just drafted)
• Regenerate the parent's system prompt to include agent-as-tool
• Simplify the task to test basic delegation flow

Understanding the issue:

Each delegation is a round-trip: the parent waits for the child to complete before continuing. Deep hierarchies (3+ levels) multiply this latency.

Solutions:

• Flatten your hierarchy - 2 levels is usually optimal
• Have managers delegate multiple tasks in parallel when possible
• Consider whether delegation is necessary for simpler tasks
• Use shared memory to pass context instead of deep delegation