Teams Service

Create and manage AI agent teams with the Kubiya SDK

The Teams Service provides comprehensive management of AI agent teams through the Kubiya platform. Teams allow you to group multiple agents together for coordinated task execution, where a team leader delegates tasks to specialized team members.

Teams: detailed guide

This page focuses on the team-specific parts of the SDK: creation, configuration, agent management, and execution patterns.

If you haven’t set up a ControlPlaneClient yet, see the Client Quick Start at Client Overview for initialization and authentication instructions.

Create a team example

The following example demonstrates creating a team with multiple agents using the Control Plane SDK:

from kubiya.control_plane_client import ControlPlaneClient

client = ControlPlaneClient()

team_data = {
    "name": "Team Name",
    "visibility": "private",
    "runtime": "default",
    "model_id": "kubiya/claude-sonnet-4",
    "environment_ids": [],
    "configuration": {
        "member_ids": [
            "agent-uuid-1"
        ],
        "agent_assignments": [
            {
                "agent_id": "agent-uuid-1",
                "runner_name": None
            }
        ],
        "instructions": "Instructions for the team.",
        "llm": {
            "model": "kubiya/claude-sonnet-4",
            "temperature": 0.7
        }
    },
    "skill_ids": [],
    "skill_configurations": {},
    "execution_environment": {
        "env_vars": {},
        "secrets": [],
        "integration_ids": [],
        "mcp_servers": {}
    }
}

team = client.teams.create(team_data)
print(f"Created team: {team['name']} (UUID: {team['id']})")

Core Operations

List Teams

Retrieve a list of teams with optional filtering and pagination:

# List all teams
teams = client.teams.list()

# With pagination
teams = client.teams.list(skip=0, limit=10)

# Filter by status
active_teams = client.teams.list(status_filter="active")

for team in teams:
    print(f"Team: {team['name']} - Status: {team['status']}")

Parameters:

Parameter	Type	Default	Description
skip	int	0	Number of records to skip for pagination
limit	int	100	Maximum number of records to return
status_filter	str	None	Filter by status: active, inactive, archived, idle

Get Team Details

Fetch a single team’s details by UUID:

team = client.teams.get("team-uuid-here")
print(team)

Create Team

Create a new team:

team_data = {
    "name": "Team Name1",
    "visibility": "private",
    "runtime": "default",
    "model_id": "kubiya/claude-sonnet-4",
    "environment_ids": [],
    "configuration": {
        "member_ids": [
            "12b68fe6-1c5d-4f96-8770-b65b50feb277"
        ],
        "agent_assignments": [
            {
                "agent_id": "12b68fe6-1c5d-4f96-8770-b65b50feb277",
                "runner_name": None
            }
        ],
        "instructions": "Instructions for the team.",
        "llm": {
            "model": "kubiya/claude-sonnet-4",
            "temperature": 0.7
        }
    },
    "skill_ids": [],
    "skill_configurations": {},
    "execution_environment": {
        "env_vars": {},
        "secrets": [],
        "integration_ids": [],
        "mcp_servers": {}
    }
}

team = client.teams.create(team_data)
print(team)

Update Team

Update an existing team’s configuration (partial update - only provided fields are updated):

update_data = {
    "status": "active",
    "configuration": {
        "instructions": "Updated instructions for the team.",
    }
}

updated = client.teams.update("team-uuid", update_data)
print(updated)

Updatable fields:

• name - Team name
• visibility - Team visibility
• status - Team status
• runtime - Runtime type (default or claude_code)
• model_id - LLM model ID
• configuration - Team configuration
• skill_ids - List of skill IDs
• skill_configurations - Dict of skill configs
• environment_ids - List of environment IDs
• execution_environment - Execution environment config

Delete Team

Permanently remove a team by UUID:

client.teams.delete("team-uuid")

---

Agent Management

Add Agent to Team

Add an agent to an existing team:

result = client.teams.add_agent("team-uuid", "agent-uuid")
print(f"Agent added. Team now has {len(result.get('agents', []))} agents")

This sets the agent’s team_id foreign key. You can also manage members through the team’s configuration.member_ids field.

Remove Agent from Team

Remove an agent from a team:

result = client.teams.remove_agent("team-uuid", "agent-uuid")
print("Agent removed from team")

---

Team Execution

Execute Task

Execute a task using the team. The team leader coordinates and delegates to appropriate team members:

execution_data = {
    "prompt": "Deploy the application to production.",
    "worker_queue_id": "<worker-queue-uuid>",
    "user_metadata": {
        "user_name": "[e-mail]",
        "user_email": "[e-mail]",
        "user_avatar": "avatar-url"
    }
}

result = client.teams.execute("team-uuid", execution_data)
print(f"Execution started: {result}")

Execute with Streaming

Execute a task with real-time streaming response:

execution_data = {
    "prompt": "Deploy the application to production.",
    "worker_queue_id": "<worker-queue-uuid>",
    "user_metadata": {
        "user_name": "[e-mail]",
        "user_email": "[e-mail]",
        "user_avatar": "avatar-url"
    }
}

for chunk in client.teams.execute_stream("team-uuid", execution_data):
    print(chunk.decode(), end="", flush=True)

Execution parameters:

Parameter	Type	Required	Description
prompt	str	Yes	The task/prompt to execute
system_prompt	str	No	Optional system prompt for team coordination
stream	bool	No	Whether to stream the response
worker_queue_id	str	Yes	Worker queue ID (UUID) to route execution to
user_metadata	dict	No	User attribution metadata

---

Error Handling

The Teams Service raises TeamError for API errors:

from kubiya.resources.exceptions import TeamError

try:
    team = client.teams.get("non-existent-team")
except TeamError as e:
    print(f"Team operation failed: {e}")

---

Best Practices

• Use descriptive team names that reflect the team’s purpose
• Configure a capable leader agent to coordinate tasks effectively
• Group agents with complementary skills into the same team
• Use status filters when listing teams in large organizations
• Handle streaming responses gracefully with proper error handling
• Always specify worker_queue_id for execution to ensure proper routing

---