Context Service

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": "team@example.com"
    }
)

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": "finance@example.com"
    }
)

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

Method	Endpoint Pattern	Description
`get()`	GET /context//	Get entity context
`update()`	PUT /context//	Update entity context
`delete()`	DELETE /context//	Delete entity context
`resolve()`	GET /context///resolve	Resolve 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

Getting Started

Control Plane Client

Context Graph & Memory

Advanced

Resources

Context Service

Quick Start

Features

Context Storage

Context Retrieval

Context Inheritance

Context Management

Entity Types

Get Context

Update Context

Delete Context

Resolve Context

Context Inheritance

Complete Example

Error Handling

Use Cases

Configuration Management

Access Control

Monitoring & Observability

Cost Attribution

Best Practices

Context Organization

Data Management

Security

Performance

API Reference

Next Steps

Agents Service

Teams Service

Environments Service

Secrets Service

​Quick Start

​Features

Context Storage

Context Retrieval

Context Inheritance

Context Management

​Entity Types

​Get Context

​Update Context

​Delete Context

​Resolve Context

​Context Inheritance

​Complete Example

​Error Handling

​Use Cases

​Configuration Management

​Access Control

​Monitoring & Observability

​Cost Attribution

​Best Practices

​Context Organization

​Data Management

​Security

​Performance

​API Reference

​Next Steps

Agents Service

Teams Service

Environments Service

Secrets Service

Quick Start

Features

Entity Types

Get Context

Update Context

Delete Context

Resolve Context

Context Inheritance

Complete Example

Error Handling

Use Cases

Configuration Management

Access Control

Monitoring & Observability

Cost Attribution

Best Practices

Context Organization

Data Management

Security

Performance

API Reference

Next Steps