A sophisticated Python 3.12 FastAPI + LangGraph backend for an AI-powered Personal Engineering Manager Agent. This system provides intelligent automation for engineering management tasks through a ReAct "Central Brain + Tools" architecture with dynamic knowledge retrieval, enterprise integrations, and scheduled workflows.

• ReAct Central Brain: Single supervisor agent with reasoning, action, and tool orchestration
• Tool-Based Architecture: Modular tools for memory, retrieval, Jira, Confluence, and Google Drive
• Dynamic Knowledge Retrieval: Pluggable, metadata-driven knowledge sources
• Enterprise Integrations: Jira, Confluence, Google Drive with official APIs
• Scheduled Workflows: Automated standups, project reviews, and grooming
• Real-time Streaming: Server-Sent Events for live AI responses
• Persistent Memory: User and project context with vector embeddings
• LangSmith Integration: Comprehensive tracing and monitoring

• One-Best-Tool-First: Calls exactly one tool at a time for efficient execution
• Capability Scoping: Tools organized by capability (general, memory, jira, confluence)
• Chain-of-Thought Privacy: Internal reasoning never exposed to users
• Pluggable Source System: Add new knowledge sources without code changes
• Circuit Breaking: Resilient error handling and rate limiting
• Idempotency: Duplicate request prevention with caching
• Structured Logging: JSON logging with request/session tracking

┌─────────────────────────────────────────────────────────────┐
│                    ReAct Supervisor                        │
│                   (Central Brain)                          │
│                                                             │
│  1. Thought: Analyze request and plan approach             │
│  2. Action: Choose tool call OR provide final answer       │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                     ToolNode                               │
│              (LangGraph Tool Execution)                    │
└─────────────────────┬───────────────────────────────────────┘
                      │
          ┌───────────┼───────────┐
          ▼           ▼           ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│   Memory    │ │  Retrieval  │ │Integration  │
│   Tools     │ │   Tools     │ │   Tools     │
│             │ │             │ │             │
│ • Save      │ │ • Search    │ │ • Jira      │
│ • Get       │ │ • Get       │ │ • Confluence│
│ • Search    │ │ • Plan      │ │ • Google    │
│ • Forget    │ │ • Retrieve  │ │ • Drive     │
└─────────────┘ └─────────────┘ └─────────────┘

User Query → Supervisor Thinks → Tool Call → Tool Executes → 
Supervisor Thinks → Final Answer → User

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│  Jira Issues    │    │ Confluence Pages │    │  Google Drive   │
│  (Tickets)      │    │  (Documentation) │    │  (Documents)    │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 ▼
                    ┌─────────────────────┐
                    │  Enterprise         │
                    │  Retrieval          │
                    │  Orchestrator       │
                    └─────────────────────┘

agent-manager-backend/
├── 📁 app/                          # Main application code
│   ├── 📄 main.py                   # FastAPI application entry point
│   ├── 📄 config.py                 # Settings and configuration management
│   ├── 📄 database.py               # Database connection and session management
│   ├── 📄 dependencies.py           # FastAPI dependency injection
│   ├── 📄 logging.py                # Structured JSON logging setup
│   │
│   ├── 📁 models/                   # SQLAlchemy database models
│   │   ├── 📄 base.py               # Base model with common fields
│   │   ├── 📄 memory.py             # Memory storage model
│   │   ├── 📄 message.py            # Chat message model
│   │   └── 📄 session.py            # Chat session model
│   │
│   ├── 📁 repositories/             # Data access layer
│   │   ├── 📄 base_repository.py    # Generic repository pattern
│   │   ├── 📄 memory_repository.py  # Memory data operations
│   │   ├── 📄 message_repository.py # Message data operations
│   │   └── 📄 session_repository.py # Session data operations
│   │
│   ├── 📁 routes/                   # FastAPI route handlers
│   │   ├── 📄 assistants.py         # Assistant management endpoints
│   │   ├── 📄 messages.py           # Message processing endpoints
│   │   ├── 📄 monitoring.py         # Health and monitoring endpoints
│   │   ├── 📄 scheduler.py          # Scheduled job management
│   │   └── 📄 sessions.py           # Session management endpoints
│   │
│   ├── 📁 schemas/                  # Pydantic request/response models
│   │   ├── 📄 messages.py           # Message schemas
│   │   └── 📄 sessions.py           # Session schemas
│   │
│   ├── 📁 services/                 # Business logic layer
│   │   ├── 📄 embedding_service.py  # Vector embedding generation
│   │   ├── 📄 langsmith_service.py  # LangSmith tracing integration
│   │   ├── 📄 llm_service.py        # LLM provider management
│   │   ├── 📄 message_service.py    # Message processing logic
│   │   ├── 📄 scheduler.py          # Job scheduling service
│   │   ├── 📄 session_service.py    # Session management logic
│   │   │
│   │   ├── 📁 graph/                # LangGraph ReAct system
│   │   │   ├── 📄 agents.py         # Legacy agent definitions (deprecated)
│   │   │   ├── 📄 graph.py          # ReAct graph orchestration with ToolNode
│   │   │   ├── 📄 state.py          # Agent state management
│   │   │   ├── 📄 supervisor.py     # ReAct supervisor with Union-based actions
│   │   │   └── 📄 utils.py          # Graph utilities
│   │   │
│   │   ├── 📁 integrations/         # External service integrations
│   │   │   ├── 📄 confluence_client.py    # Confluence API client
│   │   │   ├── 📄 confluence_source.py    # Confluence source adapter
│   │   │   ├── 📄 google_source.py        # Google Drive source adapter
│   │   │   ├── 📄 jira_client.py          # Jira API client
│   │   │   └── 📄 jira_source.py          # Jira source adapter
│   │   │
│   │   └── 📁 tools/                # LangChain tools and utilities
│   │       ├── 📄 confluence_tools.py     # Confluence LangChain tools
│   │       ├── 📄 enterprise_retrieval.py # Multi-source orchestration
│   │       ├── 📄 google_tools.py         # Google Drive LangChain tools
│   │       ├── 📄 jira_tools.py           # Jira LangChain tools
│   │       ├── 📄 memory_tools.py         # Memory management tools
│   │       ├── 📄 metadata.py             # Tool metadata utilities
│   │       ├── 📄 registry.py             # Dynamic tool registry
│   │       ├── 📄 retrieval_planner.py    # Source selection planner
│   │       └── 📄 source_protocol.py      # Universal source contract
│   │
│   └── 📁 utils/                    # Utility functions
│       ├── 📄 idempotency.py        # Idempotency key management
│       └── 📄 sse.py                # Server-Sent Events utilities
│
├── 📁 alembic/                      # Database migrations
│   ├── 📄 env.py                    # Alembic environment configuration
│   └── 📁 versions/                 # Migration files
│       ├── 📄 001_add_pgvector_index.py
│       └── 📄 002_update_models_jsonb_enums.py
│
├── 📁 data/                         # Persistent data storage
│   └── 📁 postgres/                 # PostgreSQL data directory
│
├── 📁 scripts/                      # Database and setup scripts
│   ├── 📄 init-db.sql               # Database initialization
│   └── 📄 setup_checkpointer.py     # LangGraph checkpoint setup
│
├── 📁 tests/                        # Test files
│   └── 📄 test_jira_integration.py  # Jira integration tests
│
├── 📄 .env.example                  # Environment configuration template
├── 📄 API.md                        # Comprehensive API documentation
├── 📄 Dockerfile                    # Container definition
├── 📄 docker-compose.yml            # Local development stack
├── 📄 Makefile                      # Development commands
├── 📄 pyproject.toml                # Dependencies and tool configuration
├── 📄 requests.http                 # API testing requests
└── 📄 README.md                     # This file

• Python 3.12+
• uv package manager
• Docker & Docker Compose (recommended)
• PostgreSQL 17 with pgvector extension

# Clone the repository
git clone <repository-url>
cd agent-manager-backend

# Copy environment template
cp env.example .env

# Edit configuration
nano .env

Configure your .env file with the required settings:

# Application
APP_ENV=dev
DATABASE_URL=postgresql+asyncpg://emagent:emagent_password@postgres:5432/emagent

# LLM Provider (choose one)
MODEL_PROVIDER=OPENAI
OPENAI_API_KEY=your_openai_api_key

# Or use Vertex AI
# MODEL_PROVIDER=VERTEX
# GOOGLE_APPLICATION_CREDENTIALS=path/to/credentials.json

# Atlassian Integrations
JIRA_ENABLED=true
JIRA_URL=https://your-domain.atlassian.net
JIRA_USERNAME=[email protected]
JIRA_API_TOKEN=your_api_token

CONFLUENCE_ENABLED=true
CONFLUENCE_URL=https://your-domain.atlassian.net
CONFLUENCE_USERNAME=[email protected]
CONFLUENCE_API_TOKEN=your_api_token

# Google Drive
GOOGLE_DRIVE_ENABLED=true
GOOGLE_CREDENTIALS_JSON_PATH=path/to/service-account.json

# LangSmith Tracing
LANGSMITH_API_KEY=your_langsmith_api_key
LANGSMITH_PROJECT=your_project_name

# Build and start all services
make docker-build
make docker-up

# View logs
make docker-logs

# Get shell access
make docker-shell

# Run tests
make test

# Install dependencies
make install

# Run database migrations
make migrate

# Start the application
make run

# Test health endpoint
curl http://localhost:8080/healthz

The ReAct Supervisor is the single decision-making agent that:

1. Analyzes user requests using internal reasoning
2. Plans the best approach (direct answer vs tool usage)
3. Acts by either:
   • Providing a final answer for questions it can handle directly
   • Calling exactly one tool to gather needed information
4. Iterates until it has sufficient information for a complete response

# ReAct Supervisor Decision Logic
Simple questions (math, general knowledge) → Direct final answer
Memory operations ("remember X", "what is my Y") → Memory tools
Document search ("find documentation") → Retrieval tools  
Jira operations ("create ticket", "search issues") → Jira tools
Confluence operations ("search pages") → Confluence tools
Ambiguous requests → Clarifying question

✅ Simplified Architecture: Single supervisor replaces complex multi-agent routing
✅ Flexible Reasoning: General policy allows natural planning vs rigid decision rules
✅ Efficient Execution: One-best-tool-first approach reduces latency and token usage
✅ Clean Separation: Internal thoughts never leak to user responses
✅ Easy Extension: Add new tools by registering them with capabilities
✅ Better Observability: Structured thoughts preserved for tracing and debugging

The system uses a pluggable source architecture that allows adding new knowledge sources without modifying agent code:

# Universal Source Contract
class SourceHandle(Protocol):
    def spec(self) -> SourceSpec: ...
    async def search(self, query: str, top_k: int) -> dict: ...
    async def get_by_key(self, key: str) -> dict: ...  # Optional

1. Planning: plan_retrieval_source selects the best source based on:

   • Key pattern matching (e.g., "ABC-123" → Jira)
   • Keyword scoring (e.g., "documentation" → Confluence)
   • Fallback to default source

2. Execution: Single source search with timeout

3. Orchestration: If low confidence, enterprise_retrieval fans out to all sources concurrently

4. Ranking: Results scored by relevance, recency, and source confidence

• Official API: Uses atlassian-python-api library
• Capabilities: Search, create, update, transition issues
• Tools: jira_search, jira_get_issue, jira_create_issue, jira_update_issue
• Source: JiraSource adapter for dynamic retrieval

• Official API: Uses atlassian-python-api library
• Capabilities: Search pages, get content, manage attachments
• Tools: confluence_search, confluence_get_page, confluence_get_children
• Source: ConfluenceSource adapter with metadata enrichment
• Features: HTML cleanup, caching, rate limiting

• API: Google Drive API v3
• Capabilities: Search documents, get content
• Tools: google_drive_search, google_drive_get_document
• Source: GoogleSource adapter (placeholder implementation)

The ReAct system supports scheduled workflows by sending predefined prompts to the supervisor, which then uses appropriate tools to gather information and generate reports.

• Trigger: Cron schedule 0 9 * * *
• Process: ReAct supervisor uses Jira and memory tools to analyze recent activity
• Output: Yesterday's completed work, today's planned work, blockers

• Trigger: Cron schedule 0 16 * * 5
• Process: ReAct supervisor orchestrates Jira, Confluence, and memory tools
• Output: Comprehensive project status with milestones, risks, next steps

• Trigger: Cron schedule 0 10 * * 1,3,5
• Process: ReAct supervisor analyzes backlog using Jira tools
• Output: Backlog analysis and grooming recommendations (requires approval)

# Setup and Installation
make install          # Install dependencies
make dev              # Install development dependencies
make migrate          # Run database migrations

# Development
make run              # Start application locally
make docker-build     # Build Docker image
make docker-up        # Start Docker services
make docker-down      # Stop Docker services
make docker-logs      # View Docker logs
make docker-shell     # Get Docker shell access

# Code Quality
make lint             # Run linting (ruff + mypy)
make format           # Format code (black + ruff --fix)
make test             # Run tests
make clean            # Clean generated files

# Utilities
make help             # Show all available commands

The system uses PostgreSQL 17 with the pgvector extension for vector embeddings:

-- Required extensions
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

MODEL_PROVIDER=OPENAI
OPENAI_API_KEY=sk-...

MODEL_PROVIDER=VERTEX
GOOGLE_APPLICATION_CREDENTIALS=path/to/credentials.json

MODEL_PROVIDER=MOCK
# No additional configuration required

# Run all tests
make test

# Run specific test file
docker-compose exec app python -m pytest tests/test_jira_integration.py

# Run with coverage
docker-compose exec app python -m pytest --cov=app tests/

tests/
├── test_jira_integration.py    # Jira API integration tests
├── test_confluence_integration.py  # Confluence API tests (to be added)
├── test_retrieval_system.py    # Dynamic retrieval system tests (to be added)
└── test_agents.py              # Agent behavior tests (to be added)

All agent interactions are traced in LangSmith:

• Project URL: https://smith.langchain.com/o/default/projects/p/pr-sunny-courtroom-64
• Tracing: Complete request/response cycles
• Performance: Token usage and timing metrics
• Debugging: Step-by-step agent execution

The system uses structured JSON logging with:

• Request tracking: Unique request IDs
• Session context: User and session information
• Agent execution: Step-by-step agent decisions
• Error tracking: Detailed error information with stack traces

• Basic health: /healthz endpoint
• Detailed health: /monitoring/health/detailed with integration status
• Scheduler status: /scheduler/status with job information
• LangSmith status: /monitoring/langsmith with tracing configuration

# Build production image
docker build -t em-agent:latest .

# Run with production configuration
docker run -d \
  --name em-agent \
  -p 8080:8080 \
  --env-file .env.prod \
  em-agent:latest

APP_ENV=dev
MODEL_PROVIDER=MOCK
LANGSMITH_ENABLED=false

APP_ENV=prod
MODEL_PROVIDER=OPENAI
OPENAI_API_KEY=sk-...
LANGSMITH_ENABLED=true
LANGSMITH_API_KEY=ls__...

• MAX_STEPS: Maximum agent execution steps (default: 6)
• MAX_TOKENS: Maximum token usage (default: 4096)
• COST_CAP_USD: Maximum API cost per request (default: 0)

• Idempotency-Key: Prevents duplicate message processing
• Response Caching: Cached responses for duplicate requests
• Session-based: Idempotency scoped to sessions

• Single Tool Execution: Only one tool called per iteration
• Thought Privacy: Internal reasoning never exposed to users
• Capability Scoping: Tools filtered by relevance to reduce attack surface
• Early Termination: Stops as soon as sufficient information is available

1. Fork and clone the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make changes following the code style guidelines
4. Run tests: make test
5. Run linting: make lint
6. Commit changes: git commit -m 'Add amazing feature'
7. Push to branch: git push origin feature/amazing-feature
8. Open a Pull Request

The project uses:

• Black for code formatting
• Ruff for linting and import sorting
• MyPy for type checking
• 88 character line length limit

To add a new tool that the ReAct supervisor can use:

1. Create the tool in app/services/tools/:

   from langchain_core.tools import tool
   
   @tool("my_new_tool")
   async def my_new_tool(param1: str, param2: int = 5) -> dict:
       """Tool description that the supervisor will see."""
       # Tool logic here
       return {"ok": True, "result": "success"}

2. Register with capabilities in app/services/tools/registry.py:

   # In _build_entries method
   new_tools = [(lambda: my_new_tool, ToolMetadata(
       capabilities=["general", "my_capability"],
       vendor="internal",
       rate_limit_per_minute=60
   ))]
   general.extend(new_tools)

3. The ReAct supervisor automatically discovers and can use the new tool

To add a new knowledge source:

1. Create source adapter in app/services/integrations/:

   class NewSource(SourceHandle):
       def spec(self) -> SourceSpec:
           return SourceSpec(
               id="new_source",
               display_name="New Source",
               capabilities={"search"},
               keywords={"keyword1", "keyword2"},
               key_regex=r"^PATTERN$",
               per_call_timeout_s=3,
               default_top_k=5
           )

2. Register in registry in app/services/tools/registry.py:

   if getattr(settings, "new_source_enabled", False):
       self._source_factories.append(lambda: NewSource())

3. Add configuration in app/config.py:

   new_source_enabled: bool = Field(default=False)
   new_source_url: str = Field(default="")
   new_source_api_key: str = Field(default="")

• API Documentation: API.md - Comprehensive API reference
• Swagger UI: http://localhost:8080/docs
• ReDoc: http://localhost:8080/redoc
• OpenAPI JSON: http://localhost:8080/openapi.json

• Agent Chat UI: https://github.com/langchain-ai/agent-chat-ui
• LangSmith: https://smith.langchain.com/
• LangGraph: https://langchain-ai.github.io/langgraph/

• requests.http: Contains example API requests for testing

# Reset Docker environment
make docker-down
docker system prune -f
make docker-build
make docker-up

# Reset database
docker-compose down -v
docker-compose up -d postgres
make migrate

# Recreate virtual environment
rm -rf .venv
make install

Enable debug logging:

LOG_LEVEL=DEBUG

• Check LangSmith traces for agent execution bottlenecks
• Monitor database queries with PostgreSQL logs
• Review source timeouts in retrieval orchestrator
• Check rate limiting in integration clients

This project is licensed under the MIT License - see the LICENSE file for details.

• ReAct Pattern from "ReAct: Synergizing Reasoning and Acting in Language Models" (Yao et al., 2022)
• LangChain for the tool-based framework and structured output
• LangGraph for ReAct orchestration and ToolNode execution
• FastAPI for the web framework
• Atlassian for official Python APIs
• PostgreSQL and pgvector for vector storage

Built with ❤️ for Engineering Managers everywhere
Now powered by ReAct "Central Brain + Tools" architecture