Skip to content

Setup

After completing the installation, follow this guide to set up your digitalNXT Agency development environment.

Initial Setup

1. Environment Variables

Create and configure your environment file:

cp .env.example .env

Edit .env with your specific configuration:

# Azure OpenAI Configuration (Primary)
AZURE_OPENAI_API_KEY=your_azure_openai_api_key_here
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
AZURE_OPENAI_API_VERSION=2024-02-01
AZURE_OPENAI_DEPLOYMENT_NAME=gpt-4

# Standard OpenAI Configuration (Optional fallback)
OPENAI_API_KEY=your_openai_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here

# Memory and Observability Configuration (Optional)
# For local Langfuse development
LANGFUSE_PUBLIC_KEY=pk-lf-1234567890abcdef
LANGFUSE_SECRET_KEY=sk-lf-1234567890abcdef1234567890abcdef
LANGFUSE_HOST=http://localhost:3000

# For remote Langfuse
# LANGFUSE_PUBLIC_KEY=your_remote_public_key
# LANGFUSE_SECRET_KEY=your_remote_secret_key
# LANGFUSE_HOST=https://your-langfuse-instance.com

2. Directory Structure Setup

Create the necessary directories for memory management:

# Create data directories
mkdir -p data/sessions
mkdir -p data/conversations
mkdir -p data/streamlit_sessions

# Create backup directories (optional)
mkdir -p backups/sessions
mkdir -p backups/conversations

3. Memory Configuration

The Agency framework supports different memory configurations:

Quick Memory Setup

from agency.factories.agency_factory import AgencyFactory
from agency.sessions.session_factory import SessionFactory
from agency.agency.config import AgencyConfig

# Create session for persistent memory
session = SessionFactory.create_file_session(
    session_id="my_first_session",
    db_path="data/sessions/my_first_session.db"
)

# Create agency with memory
config = AgencyConfig(
    name="MyFirstAgency",
    strategy_type="router"
)

agency = AgencyFactory.create_agency(
    config=config,
    session=session,
    user_id="user_123"
)

Memory-less Setup (Testing)

# For testing or temporary use
session = SessionFactory.create_memory_session("test_session")
agency = AgencyFactory.create_agency(config=config, session=session)

4. Temporal Development Environment

Quick Start - Complete Stack

# Start the complete development stack (Temporal + Langfuse + OpenTelemetry)
docker-compose up temporal temporal-postgres temporal-web \
                   langfuse langfuse-worker langfuse-postgres \
                   otel-collector

# Access the UIs:
# - Temporal UI: http://localhost:8080
# - Langfuse UI: http://localhost:3000 (admin@langfuse.local / password)
# - OpenTelemetry Metrics: http://localhost:8888

Temporal-Only Setup

# Start just Temporal services
docker-compose up temporal temporal-postgres temporal-web

# Temporal server: localhost:7233
# Temporal UI: http://localhost:8080

Start a Worker

# Start an Agency worker to process Temporal workflows
poetry run python run_agency_worker.py

# You should see:
# 🔧 Temporal v2 worker started on task queue: agency-task-queue
# 📋 Available strategies: ['router', 'sequential', 'map_reduce']

5. Observability Setup

Local Development (Auto-detected)

from agency.processors.processor import LangfuseMode

# Auto-detect best observability option (local Langfuse if available)
agency = AgencyFactory.create_agency(
    config=config,
    session=session,
    langfuse_mode=LangfuseMode.AUTO  # Default - tries local first
)

Production Observability

# Force remote Langfuse
agency = AgencyFactory.create_agency(
    config=config,
    session=session,
    langfuse_mode=LangfuseMode.REMOTE
)

# Disable observability
agency = AgencyFactory.create_agency(
    config=config,
    session=session,
    langfuse_mode=LangfuseMode.DISABLED
)

Test Your Setup

Quick Test Script

# test_setup.py
import asyncio
from agency.factories.agency_factory import AgencyFactory
from agency.sessions.session_factory import SessionFactory
from agency.agency.config import AgencyConfig

async def test_setup():
    print("🚀 Testing Agency setup...")

    # Create session
    session = SessionFactory.create_memory_session("test_session")

    # Create agency
    config = AgencyConfig(
        name="TestAgency",
        strategy_type="router"
    )

    agency = AgencyFactory.create_agency(
        config=config,
        session=session,
        user_id="test_user"
    )

    print("✅ Agency created successfully!")
    print(f"📊 Observability: {agency.processor.get_service_info()}")

    # Test a simple interaction (if you have agents configured)
    # response = await agency.run("Hello, can you help me?")
    # print(f"🤖 Response: {response}")

if __name__ == "__main__":
    asyncio.run(test_setup())

Run the Test

poetry run python test_setup.py

Next Steps