# Architettura

> I servizi eseguiti da PentAGI, come comunicano tra loro e quali sono opzionali.

PentAGI è un insieme di servizi Docker. Lo stack principale è sufficiente per eseguire i [flows](https://pentagi.com/it/docs/glossary/#flow); il [knowledge graph](https://pentagi.com/it/docs/glossary/#knowledge-graph) e gli stack di osservabilità sono componenti aggiuntivi opzionali.

## [Contesto del sistema](https://pentagi.com/it/docs/concepts/architecture/#system-context)

```mermaid
flowchart LR
  accTitle: System context of PentAGI with its users, targets, LLM providers, search engines, monitoring and the update server
  user["Security engineer"] -->|HTTPS| pentagi["PentAGI"]
  user -->|monitors| langfuse["Langfuse"]
  user -->|monitors| grafana["Grafana"]
  pentagi -->|tests| target["Target systems"]
  pentagi -->|queries| llm["LLM providers"]
  pentagi -->|searches| search["Search engines"]
  pentagi -->|reports| langfuse
  pentagi -->|reports| grafana
  pentagi -->|checks for updates| update["update.pentagi.com"]
```

Entro due minuti dall'avvio e poi ogni tre ore, PentAGI controlla anche `update.pentagi.com` per verificare la presenza di una build più recente e invia un riepilogo dell'installazione insieme alla richiesta; [Controllo aggiornamenti](https://pentagi.com/it/docs/configuration/security/#update-check) elenca cosa contiene e come disattivarlo.

## [Servizi](https://pentagi.com/it/docs/concepts/architecture/#services)

| Gruppo                   | Servizi                                                                                                                                                    | File Compose                       |
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| Principale               | `pentagi` (backend Go con REST e GraphQL, UI React), `pgvector` (PostgreSQL con pgvector), `pgexporter` (metriche PostgreSQL), `scraper` (browser isolato) | `docker-compose.yml`               |
| Knowledge graph          | `graphiti`, `neo4j`                                                                                                                                        | `docker-compose-graphiti.yml`      |
| Osservabilità LLM        | `langfuse-web`, `langfuse-worker`, `clickhouse`, `redis`, `minio`, `postgres`                                                                              | `docker-compose-langfuse.yml`      |
| Osservabilità di sistema | `grafana`, `otel`, `victoriametrics`, `jaeger`, `clickstore`, `loki`, `node-exporter`, `cadvisor`                                                          | `docker-compose-observability.yml` |

I [tools](https://pentagi.com/it/docs/glossary/#tool) non vengono mai eseguiti all'interno del container `pentagi` stesso: ogni flow ottiene il proprio container in [sandbox](https://pentagi.com/it/docs/glossary/#sandbox), creato da un'immagine scelta in base all'obiettivo del flow, come Kali Linux.

## [Container](https://pentagi.com/it/docs/concepts/architecture/#containers)

```mermaid
graph TB
  accTitle: Containers of the core stack and the optional knowledge graph
  subgraph Core
    UI[Web UI] -->|HTTP/WS| API[Backend API]
    API --> DB[(PostgreSQL + pgvector)]
    API --> Agents[Agents]
    Agents --> Sandbox[Sandboxed tools]
    Agents --> Scraper[Isolated browser]
  end
  subgraph Knowledge graph
    Graphiti --> Neo4j[(Neo4j)]
  end
  Agents --> Graphiti
  API -->|telemetry| OTEL[OpenTelemetry]
  API -->|LLM traces| Langfuse
```

* **Backend API** — Go, con REST e GraphQL e accesso tramite token Bearer per l'automazione.
* **Vector store** — PostgreSQL con pgvector conserva ogni comando, output ed embedding.
* **Agents** — il sistema multi-agente che pianifica ed esegue il lavoro; vedi [Agents](https://pentagi.com/it/docs/concepts/agents/).
* **Sandbox** — container dei tool isolati dall'host; in produzione possono risiedere su un [worker node](https://pentagi.com/it/docs/deployment/worker-node/) separato.