Einstieg Doku

Readme.md

@@ -1,4 +1,51 @@
-# Template für ein Agentensystem
+# Template für das Agentensystem
+
+## Einstieg
+0. Rechner vorbereiten
+ 	1. Docker Desktop installieren <https://docs.docker.com/desktop/>
+	2. Editor (IDE) installieren (freie Auswahl, Beispiele für <https://code.visualstudio.com/>)
+1. Repository einrichten 
+	1. Template laden `git clone -o UHH https://git.chai.uni-hamburg.de/UMS-Agenten/Agenten-Plattform.git`
+	2. *Eigenes* Repository hinzufügen `git remote add UMS https://git.uni-muenster.de/example/my-group.git`
+	3. In *eigenes* Repository pushen `git push UMS master`
+	4. Später dann auch immer `git push UMS ...`, `git pull UMS ...`
+	5. Updates vom Template `git pull UHH master` (Achtung: Merge-Konflikt)
+2. Lokale Umgebung (kann übersprungen werden, mach aber das Entwickeln netter; nur für VS Code)
+	- Python-Paket `src`: Eigene Implementierung
+	- Python-Paket `ums`: Agenten-Plattform ([Quelle](https://git.chai.uni-hamburg.de/UMS-Agenten/Agenten-Plattform/src/branch/master/ums))
+	- VS Code kann leider kein Autocomplete/ IntelliSense im Docker Container anbieten, daher müssen die Quellen auch auf dem Host verfügbar sein.
+	- VS Code erkennt das Verzeichnis `./src/` als Paket `src`
+	- Wir brauchen zusätzlich ein paar Abhängigkeiten und `ums`
+	1. Virtuelles Env. erstellen `python3 -m venv .`
+	2. Virtuelles Env. aktivieren `source ./bin/activate`
+	3. Pakete installieren `pip install requests fastapi pdoc` (evtl. später weitere, damit diese auch IntelliSense unterstützen)
+	4. In VS Code (in einer Python-Datei unten rechts) das Virtuelle Env. auswählen (`./bin/...`)
+	5. Verzeichnis `ums` aus dem Docker Container extrahieren:
+		```bash
+			docker create --name "management" "git.chai.uni-hamburg.de/ums-agenten/management:arm64" # oder :amd64
+			docker cp "management:/ums-agenten/plattform/ums/" ./ums/
+			docker rm "management"
+		```
+	- Virtuelles Env. und das Verzeichnis `./ums` werden von git ignoriert (siehe `./.gitignore`) 
+3. Agenten und Management starten
+	- Die Konfiguration des Managements und er verschiedenen Agenten erfolgt über die Datei `docker-compose.yml`
+	- Es ist sehr sinnvoll die Datei einmal durchzugehen und die Kommentare dort anzusehen.
+	1. Für jeden Container/ Service die Images prüfen und anpassen (`:arm64` or `:amd64`, siehe [&darr;](#docker-images))
+	2. `docker compose up` startet alle Container wie in der `docker-compose.yml` angegeben
+		- Anschließend hängt das Terminal an der Ausgabe der verschiedenen Container
+		- Fehler erscheinen dort im Terminal oder/ und in `./data/persist-*/ums.log`
+	3. Das Management kann über <http://localhost:8080> erreicht werden, es bietet:
+		- Dokumentation: <http://localhost:8080/docs/ums.html>
+		- Übersicht der Nachrichten zwischen Agenten und Management: <http://localhost:8080/app/table>
+		- Senden von Nachrichten/ Erstellen von Rätseln: <http://localhost:8080/app/new>
+		- Web API: <http://localhost:8080/api> (siehe auch <http://localhost:8080/docs/ums/utils/request.html>)
+4. Im Ordner `src` ist ein sehr einfaches Agentensystem implementiert [&rarr; Beispiel: Rätsel & Agent](./Example.md)
+5. Die Implementierung kann auf dem Beispiel aufbauen [&rarr; Implementierung](./Implement.md)
+
+> **Generell gilt:**
+> Die Images sind größtenteils neu. 
+> Auch das Management und Agenten-Framework wurde neu entworfen, d.h., es können (und werden) noch ein paar Käfer irgendwo lauern.
+> Bugs also bitte melden und bei Problemen mit dem System nachfragen (magnus.bender@uni-hamburg.de).
 
 ## Docker Images
 Es gibt unter <https://git.chai.uni-hamburg.de/UMS-Agenten/-/packages> viele verschiedene Docker Images.
@@ -24,18 +71,6 @@ Folgende Images sind verfügbar:
 	- Dieses Repository bildet einen einfachen und beispielhaften Agenten ab und soll als Basis dienen.
 
 
-> **Generell gilt:**
-> Die Images sind größtenteils neu. 
-> Auch das Management und Agenten-Framework wurde neu entworfen, d.h., es können (und werden) noch ein paar Käfer irgendwo lauern.
-> Bugs also bitte melden und bei Problemen mit dem System nachfragen (magnus.bender@uni-hamburg.de).
-
 Es wird im Laufe der Zeit sicherlich Updates der verschiedenen Images geben. 
 Aus diesem Grund gibt bei den Tags Suffixe wie z.B. `2024-10-04` mit dem Datum des Build eines Images.
 Somit bleiben auch alte Versionen erreichbar, auch wenn am Ende die aktuelle Version ohne Suffix genutzt werden soll.
-
-## Struktur einen Agenten
-> Dieses Repository ist so konzipiert, dass es geclont werden kann und dann zu einem Angenten *umgebaut* wird.
-
-...
-
-TODO