Skip to main content
The Context Service provides context resolution and management for entities in the Control Plane. It enables you to store, retrieve, and resolve context with inheritance across organizational hierarchies.

​
Quick Start

from kubiya import ControlPlaneClient

client = ControlPlaneClient()

# Get context for an agent
context = client.context.get(
    entity_type="agent",
    entity_id="agent-uuid"
)

# Update context
updated = client.context.update(
    entity_type="agent",
    entity_id="agent-uuid",
    context_data={
        "deployment_region": "us-east-1",
        "environment": "production"
    }
)

# Resolve context with inheritance
resolved = client.context.resolve(
    entity_type="agent",
    entity_id="agent-uuid"
)

​
Features

Context Storage

Store entity-specific context data

Context Retrieval

Retrieve context for any entity

Context Inheritance

Resolve context across organizational layers

Context Management

Update and delete entity context

​
Entity Types

The Context Service supports the following entity types:
  • agent: Individual agents
  • team: Multi-agent teams
  • environment: Runtime environments
  • project: Project entities
  • organization: Organization-level context

​
Get Context

Retrieve context for a specific entity: 
# Get agent context
agent_context = client.context.get(
    entity_type="agent",
    entity_id="agent-uuid"
)

print(f"Agent context: {agent_context}")

# Get team context
team_context = client.context.get(
    entity_type="team",
    entity_id="team-uuid"
)

# Get environment context
env_context = client.context.get(
    entity_type="environment",
    entity_id="env-uuid"
)
Parameters:
  • entity_type (str, required): Type of entity (‘agent’, ‘team’, ‘environment’, etc.)
  • entity_id (str, required): UUID of the entity
Returns: Dictionary containing entity context

​
Update Context

Update context for a specific entity: 
# Update agent context
updated_context = client.context.update(
    entity_type="agent",
    entity_id="agent-uuid",
    context_data={
        "region": "us-west-2",
        "tier": "premium",
        "tags": ["production", "critical"],
        "metadata": {
            "owner": "platform-team",
            "cost_center": "engineering"
        }
    }
)

print(f"Updated context: {updated_context}")

# Update team context
team_context = client.context.update(
    entity_type="team",
    entity_id="team-uuid",
    context_data={
        "max_concurrent_tasks": 10,
        "default_timeout": 3600
    }
)
Parameters:
  • entity_type (str, required): Type of entity
  • entity_id (str, required): UUID of the entity
  • context_data (dict, required): Context data to store
Returns: Dictionary containing updated context
Context updates replace the entire context for the entity. To merge with existing context, retrieve it first, merge locally, then update.

​
Delete Context

Clear or delete context for a specific entity: 
# Delete agent context
result = client.context.delete(
    entity_type="agent",
    entity_id="agent-uuid"
)

print(f"Context deleted: {result}")

# Delete team context
result = client.context.delete(
    entity_type="team",
    entity_id="team-uuid"
)
Parameters:
  • entity_type (str, required): Type of entity
  • entity_id (str, required): UUID of the entity
Returns: Dictionary containing deletion status

​
Resolve Context

Resolve context with inheritance from all organizational layers: 
# Resolve agent context with inheritance
resolved_context = client.context.resolve(
    entity_type="agent",
    entity_id="agent-uuid"
)

print(f"Resolved context: {resolved_context}")
print(f"Inherited from team: {resolved_context.get('team_context', {})}")
print(f"Inherited from environment: {resolved_context.get('environment_context', {})}")
print(f"Inherited from organization: {resolved_context.get('org_context', {})}")

# Resolve team context
team_resolved = client.context.resolve(
    entity_type="team",
    entity_id="team-uuid"
)
Parameters:
  • entity_type (str, required): Type of entity
  • entity_id (str, required): UUID of the entity
Returns: Dictionary containing resolved context with inheritance information
Use resolve() instead of get() when you need the full context picture including inherited values from parent entities.

​
Context Inheritance

Context inheritance follows organizational hierarchy: 
Organization Context
    ↓ (inherited by)
Environment Context
    ↓ (inherited by)
Project Context
    ↓ (inherited by)
Team Context
    ↓ (inherited by)
Agent Context
More specific context overrides inherited values.

​
Complete Example

Here’s a complete example showing context management across entity types: 
from kubiya import ControlPlaneClient

client = ControlPlaneClient()

# 1. Set organization-level context
org_context = client.context.update(
    entity_type="organization",
    entity_id="org-uuid",
    context_data={
        "company": "Acme Corp",
        "compliance_level": "high",
        "default_region": "us-east-1"
    }
)

# 2. Set environment context
env_context = client.context.update(
    entity_type="environment",
    entity_id="prod-env-uuid",
    context_data={
        "environment": "production",
        "region": "us-west-2",  # Overrides org default
        "monitoring_enabled": True
    }
)

# 3. Set team context
team_context = client.context.update(
    entity_type="team",
    entity_id="team-uuid",
    context_data={
        "team_name": "Platform Engineering",
        "on_call_rotation": ["alice", "bob", "charlie"],
        "max_concurrent_tasks": 5
    }
)

# 4. Set agent context
agent_context = client.context.update(
    entity_type="agent",
    entity_id="agent-uuid",
    context_data={
        "agent_name": "infrastructure-agent",
        "specialization": "kubernetes",
        "max_concurrent_tasks": 3  # Overrides team default
    }
)

# 5. Resolve agent context with full inheritance
resolved = client.context.resolve(
    entity_type="agent",
    entity_id="agent-uuid"
)

print("Resolved Agent Context:")
print(f"  Company: {resolved.get('company')}")  # From org
print(f"  Region: {resolved.get('region')}")  # From environment
print(f"  Team: {resolved.get('team_name')}")  # From team
print(f"  Agent: {resolved.get('agent_name')}")  # From agent
print(f"  Max Tasks: {resolved.get('max_concurrent_tasks')}")  # Agent override

# 6. Get just agent-specific context
agent_only = client.context.get(
    entity_type="agent",
    entity_id="agent-uuid"
)
print(f"\nAgent-only context: {agent_only}")

​
Error Handling

Handle context-related errors: 
from kubiya.resources.exceptions import ControlPlaneError

try:
    context = client.context.get(
        entity_type="agent",
        entity_id="invalid-id"
    )
except ControlPlaneError as e:
    print(f"Context error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

​
Use Cases

​
Configuration Management

# Store environment-specific configuration
client.context.update(
    entity_type="environment",
    entity_id="prod-env-uuid",
    context_data={
        "database_host": "prod-db.example.com",
        "api_endpoint": "https://api.example.com",
        "cache_ttl": 3600
    }
)

​
Access Control

# Store access control information
client.context.update(
    entity_type="agent",
    entity_id="agent-uuid",
    context_data={
        "allowed_resources": ["s3", "ec2", "rds"],
        "restricted_actions": ["delete", "terminate"],
        "approval_required": True
    }
)

​
Monitoring & Observability

# Store monitoring configuration
client.context.update(
    entity_type="team",
    entity_id="team-uuid",
    context_data={
        "metrics_endpoint": "https://metrics.example.com",
        "log_level": "info",
        "tracing_enabled": True,
        "alert_email": "[email protected]"
    }
)

​
Cost Attribution

# Store cost center information
client.context.update(
    entity_type="project",
    entity_id="project-uuid",
    context_data={
        "cost_center": "engineering-001",
        "budget_code": "ENG-2024-Q1",
        "billing_contact": "[email protected]"
    }
)

​
Best Practices

​
Context Organization

  • Hierarchical Design: Use inheritance to avoid duplication
  • Specific Overrides: Place specific values at lower levels
  • Consistent Keys: Use consistent key names across entity types
  • Avoid Deep Nesting: Keep context structure flat when possible

​
Data Management

  • Regular Updates: Keep context data current
  • Clean Up Unused: Delete context for deleted entities
  • Validate Data: Validate context data before storing
  • Version Context: Include version info in context for tracking changes

​
Security

  • Sensitive Data: Avoid storing sensitive data in context (use Secrets Service instead)
  • Access Control: Limit who can update context
  • Audit Changes: Log all context changes
  • Encrypt Sensitive Fields: Use encryption for any sensitive context data

​
Performance

  • Cache Resolved Context: Cache resolved context for frequently accessed entities
  • Batch Operations: When updating multiple entities, batch where possible
  • Lazy Resolution: Use get() instead of resolve() when inheritance isn’t needed

​
API Reference

MethodEndpoint PatternDescription
get()GET /context//Get entity context
update()PUT /context//Update entity context
delete()DELETE /context//Delete entity context
resolve()GET /context///resolveResolve with inheritance

​
Next Steps

Agents Service

Manage agents with context

Teams Service

Configure team context

Environments Service

Set environment context

Secrets Service

Store sensitive data securely