KI-Agent-Design-Architekt Prompt

**GREEN MVP – Minimal Working Agent** **1. Process Breakdown (Simplified)** - Stage 1: Fetch input data from the specified source. - Stage 2: Parse/clean data into a standard format. - Stage 3: Generate output via LLM (if required) or template. - Stage 4: Deliver output to the target destination. **2. LLM vs. Script** - LLM: Only for text generation, summarization, or unstructured data parsing. - Script: For fetching, transforming, scheduling, and delivering. **3. Input/Output per Stage** - Stage 1: Input = trigger; Output = raw data. - Stage 2: Input = raw data; Output = structured JSON. - Stage 3: Input = JSON; Output = final text/file. - Stage 4: Input = final text/file; Output = confirmation. **4. Tools & Credentials** - Tools: HTTP client, file system, email/SMTP, Telegram bot API. - Credentials: API keys stored in environment variables. **5. Memory/State** - None. Stateless execution per run. **6. Main Loop** - Single pass: fetch → process → generate → deliver → exit. **7. Verification** - Check output is non-empty and matches expected schema. **8. Error Handling** - Try/catch per stage. Retry once on network failure. Log error and exit. **9. Stopping Conditions** - Max 3 retries per stage. Total runtime cap: 10 minutes. **10. Human Approval** - None required. **11. Logging** - Single log file with timestamps and stage names. **12. Self-Improvement** - None. **13. Test Scenarios** - Empty input, malformed data, API timeout, successful run. **14. Project Structure** ``` agent/ main.py config.py requirements.txt logs/ ``` **15. Development Plan** - Day 1: Write fetch and parse logic. - Day 2: Add LLM call and output formatting. - Day 3: Add delivery and error handling. - Day 4: Test and deploy. --- **YELLOW STABLE – Reliable Production Version** **1. Process Breakdown** - Stage 1: Trigger (schedule/event) → validate input. - Stage 2: Fetch data with retries and timeout. - Stage 3: Normalize and validate data. - Stage 4: LLM processing with structured prompts. - Stage 5: Output validation against schema. - Stage 6: Delivery with confirmation check. - Stage 7: Logging and alerting. **2. LLM vs. Script** - LLM: For semantic tasks (summarization, classification, drafting). - Script: For all deterministic operations (fetch, parse, validate, send). **3. Input/Output per Stage** - Stage 1: Trigger → validated parameters. - Stage 2: Params → raw data (with metadata). - Stage 3: Raw data → clean JSON. - Stage 4: JSON → LLM output (text/JSON). - Stage 5: LLM output → verified output. - Stage 6: Verified output → delivery receipt. **4. Tools & Credentials** - Tools: Requests, Pandas, SMTP, Telegram, Slack webhook, database connector. - Credentials: Vault or .env with rotation policy. **5. Memory/State** - SQLite or Redis for run history, last-run timestamps, and deduplication keys. **6. Main Loop** - State machine with explicit transitions and validation gates. **7. Verification** - Schema validation, regex checks, and cross-field consistency checks. **8. Error Handling** - Retry with exponential backoff (max 3). - Fallback: use cached data or skip stage with alert. **9. Stopping Conditions** - Max retries, max runtime, max consecutive failures (circuit breaker). **10. Human Approval** - Required for: sending external emails, publishing content, executing payments. **11. Logging/Metrics/Alerting** - Structured logs (JSON) to file and stdout. - Metrics: run duration, stage latency, error count. - Alerts: Telegram/Slack on failure or anomaly. **12. Self-Improvement** - Store failed inputs and outputs. Weekly manual review to adjust prompts or rules. **13. Test Scenarios** - Network failure, partial data, duplicate runs, LLM hallucination, delivery failure. **14. Project Structure** ``` agent/ src/ main.py stages/ fetch.py parse.py generate.py deliver.py utils/ logger.py retry.py validator.py config/ settings.yaml data/ state.db tests/ test_stages.py logs/ agent.log requirements.txt Dockerfile ``` **15. Development Plan** - Week 1: Core pipeline with validation and retries. - Week 2: Add state management and alerting. - Week 3: Add approval gates and fallback routes. - Week 4: Testing, hardening, deployment. --- **BLUE PRO – Advanced Version** **1. Process Breakdown** - Same as Yellow, plus: - Stage 0: Context loading (memory, user preferences, history). - Stage 7: Post-run analysis (error classification, performance metrics). - Stage 8: Self-improvement loop (prompt tuning, rule updates). **2. LLM vs. Script** - LLM: Also used for error classification, self-reflection, and dynamic prompt generation. - Script: All deterministic logic, orchestration, and monitoring. **3. Input/Output per Stage** - Same as Yellow, plus: - Stage 0: Memory → context window. - Stage 7: Run logs → improvement suggestions. - Stage 8: Suggestions → updated config/prompts. **4. Tools & Credentials** - Same as Yellow, plus: vector DB (for memory), monitoring stack (Prometheus/Grafana), CI/CD pipeline. **5. Memory/State** - Vector DB for semantic memory (past outputs, user feedback). - SQLite/Postgres for transactional state. - Redis for caching and rate limiting. **6. Main Loop** - Event-driven with async execution. Context-aware branching based on memory and risk level. **7. Verification** - Multi-layer: schema, semantic similarity to expected output, and human-in-the-loop spot checks. **8. Error Handling** - Adaptive retries based on error type. Automatic rollback to previous known-good config. **9. Stopping Conditions** - Dynamic based on risk score and resource budget. Global kill-switch. **10. Human Approval** - Same as Yellow, plus: any action exceeding a risk threshold or budget. **11. Logging/Metrics/Alerting** - Full observability: traces, metrics, logs. Dashboards for latency, error rate, token usage. - Alerts with severity levels and escalation paths. **12. Self-Improvement** - Automated error clustering. Weekly retraining or prompt optimization based on failure patterns. - A/B testing of prompt variants. **13. Test Scenarios** - All Yellow scenarios, plus: memory corruption, prompt injection, budget overflow, model drift. **14. Project Structure** ``` agent/ src/ core/ orchestrator.py memory.py risk.py stages/ ... llm/ prompts/ client.py monitoring/ metrics.py alerts.py self_improve/ analyzer.py tuner.py config/ settings.yaml prompts.yaml data/ vector_db/ state.db tests/ unit/ integration/ chaos/ deploy/ docker-compose.yml k8s/ requirements.txt Makefile ``` **15. Development Plan** - Month 1: Build on Yellow, add memory and monitoring. - Month 2: Add self-improvement loop and A/B testing. - Month 3: Chaos testing, security audit, production hardening. --- **System Architecture Overview** ``` [Trigger] → [Orchestrator] → [Stage: Fetch] → [Stage: Parse] → [Stage: Generate] → [Stage: Validate] → [Stage: Deliver] ↑ ↓ ↓ ↓ ↓ ↓ [Memory] [Cache] [LLM API] [Validator] [Approval] [Logger] ↑ ↓ [Vector DB] [Metrics/Alerts] ``` **Data Flow Diagram (Text-Based)** ``` Input Source → Raw Data → Clean JSON → LLM Output → Validated Output → Delivery Target ↑ ↑ ↑ ↑ ↑ ↑ Trigger Retry/Log Schema Check Prompt/Model Rule Check Confirmation ``` **Full Tool and API List** | Tool/API | Purpose | Version | |----------|---------|---------| | Python 3.11 | Runtime | Green/Yellow/Blue | | Requests | HTTP calls | All | | Pandas | Data manipulation | Yellow/Blue | | OpenAI API | LLM calls | All | | SMTP/Telegram/Slack | Delivery | All | | SQLite/Redis | State/Cache | Yellow/Blue | | Vector DB (e.g., Chroma) | Memory | Blue | | Prometheus/Grafana | Monitoring | Blue | **Pseudocode for the Main Loop** ``` function run_agent(trigger): context = load_context(trigger) if not validate_input(context): alert("Invalid input"); return raw_data = fetch_data(context) if raw_data is None: retry_or_fallback(); return clean_data = parse_and_validate(raw_data) if clean_data is None: alert("Parse error"); return output = generate_output(clean_data) # LLM or template if not validate_output(output): alert("Validation failed"); return if requires_approval(output): wait_for_human_approval() delivery_receipt = deliver(output) if not delivery_receipt: alert("Delivery failed"); return log_success(trigger, output, delivery_receipt) update_memory(trigger, output) ``` **Recommended Folder Structure** See project structures above per version. **Step-by-Step Development Roadmap** 1. Define exact input/output schemas. 2. Build Green MVP end-to-end. 3. Add validation and retries (Yellow). 4. Add state management and alerting. 5. Add approval gates. 6. Add memory and monitoring (Blue). 7. Implement self-improvement loop. 8. Run chaos tests and security audit. **Security Checklist** - [ ] API keys stored in environment variables or vault - [ ] No secrets in logs or code - [ ] HTTPS for all external calls - [ ] Input sanitization to prevent prompt injection - [ ] Rate limiting on all external APIs - [ ] Audit log of all human approvals - [ ] Data encryption at rest (if storing sensitive data) - [ ] Principle of least privilege for credentials **Testing Checklist** - [ ] Happy path end-to-end - [ ] Empty input - [ ] Malformed data - [ ] API timeout - [ ] API rate limit exceeded - [ ] LLM returns invalid JSON - [ ] Duplicate run (idempotency) - [ ] Delivery failure - [ ] Approval timeout - [ ] Memory corruption (Blue) - [ ] Prompt injection attempt - [ ] Budget overflow **Agent Readiness Criteria** - [ ] Runs successfully 10 consecutive times without manual intervention - [ ] All error paths produce alerts, not silent failures - [ ] Average token usage per run is within budget - [ ] No sensitive data appears in logs - [ ] Human approval gates work correctly - [ ] Rollback plan exists and is tested - [ ] Documentation is up to date - [ ] Monitoring dashboard shows healthy metrics for 7 days