Background Agent Setup - Context Documentation

This guide walks you through the complete setup process for deploying Background Agents in your enterprise environment, including system requirements, configuration, and initial testing.

Prerequisites

Enterprise Access Requirements

Background Agents are available exclusively to enterprise customers. Contact enterprise@context.ai to begin the setup process.

System Requirements

Before beginning setup, ensure your environment meets these requirements:

Infrastructure

CPU: 8+ cores recommended
RAM: 16GB+ system memory
Storage: 500GB+ SSD storage
Network: Stable internet with 100+ Mbps

Software

OS: Linux (Ubuntu 20.04+) or Windows Server 2019+
Container Runtime: Docker 20.10+ or containerd
Database: PostgreSQL 13+ or MySQL 8.0+
SSL: Valid SSL certificates for HTTPS endpoints

Access Requirements

API Keys: Enterprise API access credentials
Network Access: Outbound HTTPS (port 443) to Context AI services
Domain: Subdomain for webhook endpoints (e.g., agents.yourcompany.com)
Authentication: Integration with your enterprise SSO (SAML/OAuth2)

Installation Process

Step 1: Environment Setup

Create your enterprise configuration file:

# Create enterprise directory
mkdir -p /opt/context/background-agents
cd /opt/context/background-agents

# Download enterprise configuration template
curl -H "X-API-Key: YOUR_ENTERPRISE_KEY" \
  https://enterprise.context.ai/config/background-agents/template \
  -o enterprise-config.yml

Step 2: Docker Deployment

Deploy Background Agents using Docker Compose:

# docker-compose.yml
version: '3.8'

services:
  background-agents:
    image: context-ai/background-agents:enterprise-latest
    container_name: context-background-agents
    restart: always
    ports:
      - "8080:8080"  # API port
      - "8443:8443"  # Webhook port
    environment:
      - CONTEXT_API_KEY=${CONTEXT_API_KEY}
      - CONTEXT_ENGINE_ENDPOINT=${CONTEXT_ENGINE_ENDPOINT}
      - ENTERPRISE_ORG_ID=${ENTERPRISE_ORG_ID}
      - DATABASE_URL=${DATABASE_URL}
      - REDIS_URL=${REDIS_URL}
      - SSL_CERT_PATH=/certs/tls.crt
      - SSL_KEY_PATH=/certs/tls.key
    volumes:
      - ./config:/app/config:ro
      - ./logs:/app/logs
      - ./certs:/certs:ro
      - ./data:/app/data
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:15-alpine
    container_name: context-postgres
    restart: always
    environment:
      - POSTGRES_DB=background_agents
      - POSTGRES_USER=context_agent
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro

  redis:
    image: redis:7-alpine
    container_name: context-redis
    restart: always
    command: redis-server --requirepass ${REDIS_PASSWORD}
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

Step 3: Configuration

Edit your enterprise configuration:

# config/enterprise-config.yml
enterprise:
  organization_id: "your-org-id"
  deployment_mode: "production"
  
context_engine:
  endpoint: "https://api.context.ai/v1/context-engine"
  timeout_ms: 30000
  retry_attempts: 3

background_agents:
  max_concurrent_tasks: 50
  task_timeout_minutes: 60
  progress_update_interval_seconds: 30
  
  # Agent types to enable
  enabled_agents:
    - research_agent
    - processing_agent
    - notification_agent
    
  # Custom agent configurations
  agent_configs:
    research_agent:
      max_sources: 20
      analysis_depth: "comprehensive"
      output_format: "structured_report"
    
    processing_agent:
      supported_formats: ["pdf", "docx", "xlsx", "pptx"]
      extraction_mode: "full_text_plus_metadata"
      
    notification_agent:
      email_enabled: true
      webhook_enabled: true
      slack_integration: true

integrations:
  # Enterprise system connections
  databases:
    primary:
      type: "postgresql"
      connection_string: "${DATABASE_URL}"
      
  file_systems:
    corporate_sharepoint:
      type: "sharepoint"
      tenant_id: "${SHAREPOINT_TENANT_ID}"
      client_id: "${SHAREPOINT_CLIENT_ID}"
      client_secret: "${SHAREPOINT_CLIENT_SECRET}"
      
  notification_systems:
    email:
      smtp_host: "smtp.yourcompany.com"
      smtp_port: 587
      username: "${SMTP_USERNAME}"
      password: "${SMTP_PASSWORD}"
      
    slack:
      bot_token: "${SLACK_BOT_TOKEN}"
      signing_secret: "${SLACK_SIGNING_SECRET}"

security:
  authentication:
    type: "enterprise_sso"
    provider: "okta"  # or "azure_ad", "saml"
    configuration:
      issuer: "https://yourcompany.okta.com"
      client_id: "${OKTA_CLIENT_ID}"
      client_secret: "${OKTA_CLIENT_SECRET}"
      
  encryption:
    data_at_rest: true
    data_in_transit: true
    key_rotation_days: 90

monitoring:
  logging:
    level: "info"
    format: "json"
    retention_days: 90
    
  metrics:
    enabled: true
    endpoint: "/metrics"
    prometheus_compatible: true
    
  health_checks:
    enabled: true
    endpoint: "/health"
    interval_seconds: 30

Step 4: SSL Certificate Setup

Configure SSL certificates for secure communication:

# Generate or install SSL certificates
mkdir -p certs

# Option 1: Use Let's Encrypt
certbot certonly --standalone \
  -d agents.yourcompany.com \
  --email admin@yourcompany.com \
  --agree-tos

cp /etc/letsencrypt/live/agents.yourcompany.com/fullchain.pem certs/tls.crt
cp /etc/letsencrypt/live/agents.yourcompany.com/privkey.pem certs/tls.key

# Option 2: Use your enterprise CA certificates
cp /path/to/your/certificate.crt certs/tls.crt
cp /path/to/your/private.key certs/tls.key

Step 5: Database Initialization

Initialize the PostgreSQL database:

-- init.sql
CREATE DATABASE background_agents;

CREATE USER context_agent WITH ENCRYPTED PASSWORD 'your_secure_password';

GRANT ALL PRIVILEGES ON DATABASE background_agents TO context_agent;

\c background_agents;

-- Create required tables
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

CREATE TABLE agent_tasks (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    task_type VARCHAR(100) NOT NULL,
    status VARCHAR(50) NOT NULL DEFAULT 'pending',
    priority INTEGER DEFAULT 5,
    input_data JSONB NOT NULL,
    output_data JSONB,
    progress_percentage INTEGER DEFAULT 0,
    error_message TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    completed_at TIMESTAMP WITH TIME ZONE,
    created_by VARCHAR(255) NOT NULL,
    organization_id VARCHAR(100) NOT NULL
);

CREATE TABLE agent_logs (
    id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
    task_id UUID REFERENCES agent_tasks(id),
    level VARCHAR(20) NOT NULL,
    message TEXT NOT NULL,
    metadata JSONB,
    timestamp TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE INDEX idx_agent_tasks_status ON agent_tasks(status);
CREATE INDEX idx_agent_tasks_created_at ON agent_tasks(created_at);
CREATE INDEX idx_agent_tasks_org ON agent_tasks(organization_id);
CREATE INDEX idx_agent_logs_task_id ON agent_logs(task_id);

Configuration Validation

Step 6: Environment Variables

Create your .env file with enterprise credentials:

# .env
CONTEXT_API_KEY=your_enterprise_api_key
CONTEXT_ENGINE_ENDPOINT=https://api.context.ai/v1/context-engine
ENTERPRISE_ORG_ID=your_organization_id

DATABASE_URL=postgresql://context_agent:your_secure_password@localhost:5432/background_agents
REDIS_URL=redis://:your_redis_password@localhost:6379

POSTGRES_PASSWORD=your_secure_password
REDIS_PASSWORD=your_redis_password

# SSO Configuration
OKTA_CLIENT_ID=your_okta_client_id
OKTA_CLIENT_SECRET=your_okta_client_secret

# Integration Credentials
SHAREPOINT_TENANT_ID=your_tenant_id
SHAREPOINT_CLIENT_ID=your_sharepoint_client_id
SHAREPOINT_CLIENT_SECRET=your_sharepoint_client_secret

SMTP_USERNAME=notifications@yourcompany.com
SMTP_PASSWORD=your_smtp_password

SLACK_BOT_TOKEN=xoxb-your-slack-bot-token
SLACK_SIGNING_SECRET=your_slack_signing_secret

Step 7: Start Services

Launch the Background Agent system:

# Start all services
docker-compose up -d

# Verify services are running
docker-compose ps

# Check logs
docker-compose logs -f background-agents

Testing & Validation

Step 8: Health Check

Verify the system is running correctly:

# Check health endpoint
curl -k https://agents.yourcompany.com:8443/health

# Expected response:
{
  "status": "healthy",
  "version": "1.0.0",
  "services": {
    "context_engine": "connected",
    "database": "connected",
    "redis": "connected"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Step 9: Authentication Test

Test enterprise SSO authentication:

# Test authentication endpoint
curl -X POST https://agents.yourcompany.com:8443/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser@yourcompany.com",
    "password": "testpassword"
  }'

# Expected response includes JWT token
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "user_info": {
    "email": "testuser@yourcompany.com",
    "organization": "your-org-id",
    "permissions": ["background_agents:read", "background_agents:write"]
  }
}

Step 10: Sample Task Submission

Submit a test background task:

# Get authentication token first
TOKEN=$(curl -s -X POST https://agents.yourcompany.com:8443/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"testuser@yourcompany.com","password":"testpassword"}' \
  | jq -r '.access_token')

# Submit test task
curl -X POST https://agents.yourcompany.com:8443/api/v1/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task_type": "research_agent",
    "priority": 5,
    "input": {
      "query": "Analyze market trends for AI companies in Q4 2024",
      "sources": ["financial_reports", "market_data"],
      "output_format": "executive_summary"
    },
    "webhook_url": "https://yourcompany.com/webhooks/background-tasks"
  }'

# Expected response:
{
  "task_id": "task_123e4567-e89b-12d3-a456-426614174000",
  "status": "accepted",
  "estimated_completion": "2024-01-15T11:00:00Z",
  "webhook_configured": true
}

Troubleshooting

Common Issues

Connection to Context Engine Failed

Verify your API key and network connectivity:

# Test Context Engine connectivity
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://api.context.ai/v1/context-engine/health

# Check firewall rules for outbound HTTPS
sudo ufw status

Database Connection Issues

Check database configuration and credentials:

# Test PostgreSQL connection
psql -h localhost -U context_agent -d background_agents -c '\dt'

# Check database logs
docker-compose logs postgres

SSL Certificate Problems

Verify certificate validity and configuration:

# Check certificate expiration
openssl x509 -in certs/tls.crt -text -noout | grep "Not After"

# Test SSL endpoint
curl -I https://agents.yourcompany.com:8443/health

Support Resources

For additional support:

Enterprise Support: enterprise@context.ai
Technical Documentation: Available in your enterprise portal
24/7 Support Hotline: Provided after enterprise setup completion

Next Steps

API Endpoints

Complete API reference for Background Agent integration

Usage Examples

Real-world examples and implementation patterns

Enterprise

​Prerequisites

​Enterprise Access Requirements

​System Requirements

Infrastructure

Software

​Access Requirements

​Installation Process

​Step 1: Environment Setup

​Step 2: Docker Deployment

​Step 3: Configuration

​Step 4: SSL Certificate Setup

​Step 5: Database Initialization

​Configuration Validation

​Step 6: Environment Variables

​Step 7: Start Services

​Testing & Validation

​Step 8: Health Check

​Step 9: Authentication Test

​Step 10: Sample Task Submission

​Troubleshooting

​Common Issues

​Support Resources

​Next Steps

API Endpoints

Usage Examples

Prerequisites

Enterprise Access Requirements

System Requirements

Access Requirements

Installation Process

Step 1: Environment Setup

Step 2: Docker Deployment

Step 3: Configuration

Step 4: SSL Certificate Setup

Step 5: Database Initialization

Configuration Validation

Step 6: Environment Variables

Step 7: Start Services

Testing & Validation

Step 8: Health Check

Step 9: Authentication Test

Step 10: Sample Task Submission

Troubleshooting

Common Issues

Support Resources

Next Steps