AgentUp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

AgentUp is a Python framework for creating AI agents with production-ready features including security, scalability, and extensibility. It uses a configuration-driven architecture where agent behaviors, data sources, and workflows are defined through YAML configuration rather than code.

Key Features:

• Configuration-over-code approach with YAML-driven agent definitions
• Security-first design with scope-based access control and comprehensive audit logging
• Plugin ecosystem with community registry and automatic security scanning
• Multi-provider AI support (OpenAI, Anthropic, Ollama)
• MCP (Model Context Protocol) and A2A (Agent-to-Agent) protocol compliance
• Real-time operations with streaming, async processing, and push notifications

Technology Stack

• Python: >=3.11 required
• Pydantic: v2 for data validation and settings management
• Web Framework: FastAPI with Uvicorn ASGI server
• Package Manager: UV (preferred) for dependency management
• Plugin System: Pluggy-based architecture with middleware inheritance
• Authentication: OAuth2, JWT, API key support via Authlib
• Logging: Structlog with correlation IDs for distributed tracing
• Testing: Pytest with async support and comprehensive markers
• Code Quality: Ruff (linting/formatting), MyPy (type checking), Bandit (security)

Essential Development Commands

Environment Setup

uv sync --all-extras --dev    # Install all dependencies including dev tools
uv pip install -e .           # Install package in editable mode

Testing

# Unit tests only (fast)
uv run pytest tests/test_*.py tests/test_core/ tests/test_cli/ -v -m "not integration and not e2e and not performance"

# Integration tests
chmod +x tests/integration/int.sh && ./tests/integration/int.sh

# All tests with coverage
uv run pytest tests/ --cov=src --cov-report=html --cov-report=term-missing

# Watch mode for development
uv run pytest-watch --runner "uv run pytest tests/test_*.py tests/test_core/ tests/test_cli/ -m 'not integration and not e2e and not performance'"