> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kubiya.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Context Management

> Manage knowledge and configuration inheritance across agents and teams

## Overview

Context management enables agents and teams to access relevant knowledge, configuration, and state information. Contexts provide a hierarchical way to share information across organizational boundaries.

## Context Types

### Environment Context

Environment-level context provides configuration and knowledge that applies to all agents in a specific environment.

**Use cases:**

* Environment-specific API endpoints
* Shared knowledge bases
* Environment documentation
* Common procedures and runbooks

**Example:**

```json theme={null}
{
  "environment_id": "prod-env",
  "context": {
    "api_endpoints": {
      "user_service": "https://api.prod.example.com/users",
      "payment_service": "https://api.prod.example.com/payments"
    },
    "runbooks": {
      "incident_response": "https://wiki.example.com/incidents"
    }
  }
}
```

### Team Context

Team-level context provides information specific to a team's domain and responsibilities.

**Use cases:**

* Team-specific knowledge
* Shared procedures
* Team documentation
* Historical decisions and context

**Example:**

```json theme={null}
{
  "team_id": "devops-team",
  "context": {
    "on_call_schedule": "https://pagerduty.com/schedules/devops",
    "monitoring_dashboards": {
      "production": "https://grafana.example.com/prod",
      "staging": "https://grafana.example.com/staging"
    },
    "knowledge": {
      "deployment_process": "...",
      "rollback_procedure": "..."
    }
  }
}
```

### Context Manager

The context manager orchestrates context resolution across multiple levels:

* Organization-level context
* Project-level context
* Environment-level context
* Team-level context
* Agent-level context

**Context inheritance:**

```
Organization Context
    ↓
Project Context
    ↓
Environment Context
    ↓
Team Context
    ↓
Agent Context
```

Lower levels can override values from higher levels, enabling flexible configuration.

## Context Resolution

When an agent executes, the context manager:

1. Collects context from all relevant levels
2. Merges contexts with appropriate precedence
3. Resolves variables and references
4. Provides the final context to the agent

**Resolution order (highest to lowest priority):**

1. Agent-specific context
2. Team context
3. Environment context
4. Project context
5. Organization context

## Common Patterns

### Adding Environment Context

```bash theme={null}
PUT /api/v1/context/environment/{environment_id}/context
{
  "knowledge": {
    "deployment_regions": ["us-east-1", "eu-west-1"],
    "max_replicas": 10,
    "monitoring_url": "https://monitoring.example.com"
  },
  "documentation": {
    "architecture": "https://wiki.example.com/arch",
    "apis": "https://wiki.example.com/api-docs"
  }
}
```

### Getting Environment Context

```bash theme={null}
GET /api/v1/context/environment/{environment_id}/context
```

### Adding Team Context

```bash theme={null}
PUT /api/v1/context/teams/{team_id}/context
{
  "expertise": ["kubernetes", "terraform", "python"],
  "responsibilities": [
    "Infrastructure management",
    "CI/CD pipelines",
    "Monitoring and alerting"
  ],
  "escalation": {
    "primary": "@devops-lead",
    "secondary": "@platform-team"
  }
}
```

### Getting Team Context

```bash theme={null}
GET /api/v1/context/teams/{team_id}/context
```

### Generic Context Operations

```bash theme={null}
# Get context for any entity
GET /api/v1/context/{entity_type}/{entity_id}

# Update context for any entity
PUT /api/v1/context/{entity_type}/{entity_id}
{
  "key": "value",
  "nested": {...}
}

# Delete context
DELETE /api/v1/context/{entity_type}/{entity_id}
```

### Resolve Context with Inheritance

```bash theme={null}
# Resolve context for an entity with full inheritance chain
GET /api/v1/context/resolve/{entity_type}/{entity_id}

Response:
{
  "resolved_context": {
    "key1": "value from agent",
    "key2": "value from team",
    "key3": "value from environment"
  },
  "inheritance_chain": [
    "environment",
    "team",
    "agent"
  ]
}
```

**Resolution order**: Environment → Team → Agent (later levels override earlier ones)

## Context Use Cases

### Knowledge Sharing

Share organizational knowledge across teams:

* Architecture documentation
* Best practices
* Common patterns
* Historical decisions

### Configuration Management

Manage configuration hierarchically:

* API endpoints per environment
* Feature flags
* Resource limits
* Integration settings

### Dynamic Behavior

Agents adapt behavior based on context:

* Different approval rules per environment
* Environment-specific tools
* Team-specific knowledge
* Project-specific configurations

## Best Practices

1. **Hierarchy**: Use the appropriate level for each piece of context
2. **DRY Principle**: Define shared context once at the appropriate level
3. **Documentation**: Document what context is available and its purpose
4. **Versioning**: Version context changes for auditability
5. **Secrets**: Never store secrets in context - use the secrets API
6. **Size**: Keep context focused - don't dump entire documentation
7. **Updates**: Update context when systems or processes change

## Context vs. Configuration

**Use context for:**

* Knowledge and documentation
* Shared information
* Non-sensitive configuration
* Dynamic, frequently-changing information

**Use configuration/secrets for:**

* Sensitive credentials
* API keys and tokens
* Static configuration
* Security-sensitive settings

## Next Steps

Explore the API endpoints for environment context, team context, and the context manager to learn how to manage and resolve context across your organization.