dev-agent/ARCHITECTURE.md

Universal Dev Agent Architecture

This document describes the high-level architecture of the Universal Dev Agent, which acts as a platform-agnostic builder converting natural-language requirements into structured, validated agent specifications.

graph TD
    User([User Prompt / Message]) --> API[FastAPI Layer]
    User --> CLI[CLI Loop]
    API --> SessionService[Conversation & Session Service]
    CLI --> SessionService
    SessionService --> DB[(SQLite Database)]
    SessionService --> DevAgent[LangGraph DevAgent]
    DevAgent --> AnalyzeNode[Analyze Node]
    AnalyzeNode --> LLMService[LLM Service / LiteLLM]
    AnalyzeNode --> RouteAnalysis{Missing Info?}
    RouteAnalysis -- Yes --> ClarifyNode[Clarify Node]
    RouteAnalysis -- No --> GenerateNode[Generate Spec Node]
    ClarifyNode --> END([Awaiting User Input])
    GenerateNode --> ValidateNode[Validate Spec Node]
    ValidateNode --> ValidationService[Validation Service]
    ValidationService --> SchemaValidator[Schema Validator]
    ValidationService --> ConnectionValidator[Connection Validator]
    ValidationService --> ConflictValidator[Conflict Validator]
    ValidationService --> ToolValidator[Tool Validator]
    ValidationService --> WorkflowValidator[Workflow Validator]
    ValidateNode --> RouteValidation{Valid Spec?}
    RouteValidation -- Yes --> FinalizeNode[Finalize Node]
    RouteValidation -- No --> ClarifyNode
    FinalizeNode --> END

---

Core Components

1. LangGraph State Machine (app/agents/)

The conversational flow is modeled as a state machine using LangGraph. The workflow progresses through the following states:

• analyze: Inspects user messages in the context of the history to extract core fields (triggers, connections, modes, tools).
• clarify: Formulates questions if critical information is missing or validation errors occur, then pauses execution by returning END.
• generate: Generates a draft JSON Agent Spec according to the Pydantic schemas.
• validate: Runs the spec through the multi-layer Validation Service.
• finalize: Marks the spec as validated, increments versions, and prepares the version record.

2. Validation Service (app/validators/)

A multi-layered validation pipeline guarantees correct, conflict-free, and secure Agent Specs:

1. Schema Validation: Uses Pydantic to ensure all fields match required types, structures, and schemas.
2. Connection Validation: Verifies connection configurations by type (e.g. base_url for REST APIs) and scans the specs to prevent raw credentials (secrets, API keys) from leaking.
3. Conflict Validation: Flags conflicting properties, such as a trigger type set to manual but containing cron configurations.
4. Tool Validation: Ensures steps executing tool_call actions reference existing tools defined in the spec.
5. Workflow Validation: Automatically performs cycle detection to prevent circular execution dependencies, checks that all step dependencies exist, and verifies that step inputs only reference outputs of preceding dependent steps.

3. LiteLLM Service (app/services/llm_service.py)

Abstracts model provider configuration. Uses completion() to execute NLP analysis, clarification question generation, and spec generation.

• Smart Fallback: If no LLM API key is configured, a rule-based parser kicks in, ensuring complete conversational flow, spec drafting, and validation run offline.

4. Database Layer (app/db/)

Uses SQLAlchemy for ORM and SQLite by default.

• dev_sessions: Persists conversation builder variables like extracted_requirements, draft_spec, validation_result, and current state.
• conversation_messages: Maintains chronological messages.
• agent_specs & agent_versions: Persists generated specifications and auto-increments version tags.