Deprecate Teams feature due to fundamental issues

[zzstoatzz]

Summary

This PR deprecates the entire Teams feature (Team, Swarm, RoundRobinTeam, RandomTeam) due to critical, unfixable issues that make it unsuitable for production use.

The Problems

1. Infinite Delegation Loops 🔄

• Swarm (and other delegation-based teams) get stuck in infinite loops
• Generates hundreds of "Multiple EndTurn tools detected" warnings
• Makes the feature completely unusable

Evidence:

# This will loop forever with warnings
swarm = Swarm(members=[agent1, agent2])
swarm.run("Do something")  # ⚠️ Infinite loop!

2. No Actual Collaboration 🚫

• Basic Team class doesn't enable agents to work together
• Only the first agent does any work
• Other agents are never activated or consulted

3. Broken Documentation 📚

• The HierarchicalTeam example in docs doesn't even work
• Missing required field handling causes immediate failure
• Users waste time trying to debug examples that were never tested

4. Half-Baked Implementation 🍞

• Feature appears rushed for release without proper testing
• Multiple design issues with EndTurn tool management
• No tests for custom team patterns
• Clear signs of incomplete implementation

What This PR Does

✅ Adds deprecation warnings to all Team-related classes

• Warns users on instantiation
• Targets removal for Feb 2026 (6 months from now)
• Clear message directing users to use individual Agents

✅ Fixes documentation

• Corrects the broken HierarchicalTeam example
• Adds deprecation notices throughout teams docs
• Warns users about the issues

✅ Creates deprecation utilities

• New marvin._internal.deprecation module
• Based on Prefect's battle-tested patterns
• Reusable for future deprecations

User Impact

Users like Watts in our community have been struggling with these broken features. This deprecation:

• Saves users from wasting time on broken functionality
• Provides clear guidance on alternatives
• Sets expectations for removal timeline

Recommendation

Use individual Agents with explicit coordination instead of Teams.

The Agent class works well on its own. For multi-agent scenarios, users should orchestrate Agents explicitly in their application logic rather than relying on the broken Teams abstraction.

Testing

# All team types now show deprecation warnings
from marvin import Agent, Team, Swarm

agent = Agent()
team = Team(members=[agent])  # ⚠️ MarvinDeprecationWarning

swarm = Swarm(members=[agent, Agent()])  # ⚠️ MarvinDeprecationWarning

Related Issues

Addresses concerns raised by community members trying to use the teams feature as documented.

🤖 Generated with Claude Code

Co-Authored-By: Claude [email protected]