Skip to main content

​
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: 
{
  "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: 
{
  "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

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

GET /api/v1/context/environment/{environment_id}/context

​
Adding Team Context

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

GET /api/v1/context/teams/{team_id}/context

​
Generic Context Operations

# 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

# 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.