Agenten-Spezifikation — Implementierungsstand v0.1
Dieses Dokument beschreibt die tatsächlich implementierten Agenten des
Photo-to-Listing-Prototyps. Es ergänzt das Ziel-Design in
architecture.md um den konkreten Ist-Zustand.
Designentscheidungen v0.1 (Abweichungen vom Ziel-Design)
| Thema |
Ziel-Design (architecture.md) |
Prototyp v0.1 |
Begründung |
| Validierung |
Pydantic v2 |
dataclasses (Stdlib) |
Spike/Agenten laufen ohne pip install (siehe requirements.txt) |
| LLM-Zugang |
Anthropic API + ANTHROPIC_API_KEY |
lokaler claude -p CLI |
Kein Klartext-Key im Code (SOPS-Policy); CLI ist bereits authentifiziert |
| Preisdaten |
eBay Finding API |
Heuristik (Mock) bzw. Modell-Schätzung (Live) |
Echtes Scraping = AGB-/Rechtsthema, bewusst nicht enthalten |
| Robustheit |
Retry/Backoff |
Mock-Fallback je Agent |
Ein Agent darf die Pipeline nie reißen; Prototyp bleibt offline lauffähig |
Jeder LLM-gestützte Agent hat zwei Pfade:
- live — ruft
claude -p auf (wenn CLI vorhanden, sonst automatisch Fallback),
- mock — deterministische Logik, garantiert offline/in CI reproduzierbar.
Der Betriebsmodus wird zentral über ClaudeClient(mode="auto"|"live"|"mock")
gesetzt und vom Orchestrator an alle Agenten durchgereicht.
Orchestrator — src/agents/orchestrator.py
| Eigenschaft |
Wert |
| Rolle |
Zentraler Koordinator (BMAD-Orchestrator-Pattern) |
| Kein KI-Modell |
reine Python-Orchestrierung |
| Kern-Methode |
photo_to_listing(image_path=None, description=None) -> ListingResult |
| Chat-Methode |
answer_question(question, listing) -> ChatReply |
| Ablauf |
Vision → Market → Listing, danach optional Chat |
Vision — ImageAnalysisAgent (image_analysis_agent.py)
| Eigenschaft |
Wert |
| Rolle |
Bildanalyse: Artikel, Zustand, Merkmale erkennen |
| Input |
{"image_path": str, "description": str} (oder Pfad-String) |
| Output |
ItemAnalysis(title_guess, category, brand, condition, condition_score, features, defects, confidence, source) |
| Live |
claude -p liest die Bilddatei (Tool Read) und liefert JSON |
| Mock |
Stichwort-Heuristik aus Dateiname/Beschreibung → plausibles Beispielobjekt |
Market — PriceResearchAgent (price_research_agent.py)
| Eigenschaft |
Wert |
| Rolle |
Marktpreis vorschlagen |
| Input |
ItemAnalysis |
| Output |
PriceSuggestion(suggested_price, price_min, price_max, currency, sample_size, rationale, source) |
| Live |
Modell schätzt Preisspanne (deutscher eBay-Markt) als JSON |
| Mock |
Basispreis je Kategorie × Zustands-Faktor (0,5 … 1,0) |
Listing — ListingAgent (listing_agent.py)
| Eigenschaft |
Wert |
| Rolle |
eBay-konformes Listing erzeugen |
| Input |
(ItemAnalysis, PriceSuggestion) (oder dict) |
| Output |
Listing(title≤80, description, category_id, item_specifics, price, currency, source) |
| Live |
Modell erzeugt Titel/Text/Attribute als JSON |
| Mock |
Template: Titel aus Marke+Artikel+Zustand, Beschreibung mit Stichpunkten, Kategorie-ID-Lookup |
Chat — ChatModerationAgent (chat_moderation_agent.py)
| Eigenschaft |
Wert |
| Rolle |
Käuferfragen beantworten / eskalieren |
| Input |
{"question": str, "listing": Listing} |
| Output |
ChatReply(question, answer, escalate, source) |
| Live |
Modell antwortet + setzt escalate bei Reklamation/Recht |
| Mock |
FAQ-Intents (Versand, Preis, Zustand, Verfügbarkeit) + Eskalations-Stichwörter |
Datenfluss (implementiert)
Foto/Text
│
▼ ImageAnalysisAgent
ItemAnalysis
│
▼ PriceResearchAgent
PriceSuggestion
│
▼ ListingAgent
Listing ──► ListingResult (analysis + price + listing)
│
▼ ChatModerationAgent (auf Käuferfrage)
ChatReply
Alle Strukturen sind in src/models.py definiert und über .to_dict() /
.to_json() serialisierbar.
3f5b1a59a5