Spaces:
Runtime error
Runtime error
| # 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. | |
| ```mermaid | |
| 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. | |