# agenta-ai/agenta architecture

> Architecture diagram of the GitHub repository agenta-ai/agenta, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agenta-ai/agenta
- Repository: https://github.com/agenta-ai/agenta

## Overview

Agenta is an open-source workspace for building, sharing, and running agents. The documented user journey is to define an agent, connect tools and workspace resources, then run it in chat or in the background; permissions govern tool actions, and traces and evaluations support improvement. The tree provides paths for these capabilities, but the sampled source excerpts are mostly unrelated frontend hooks, so the runtime wiring below reflects README-documented behavior rather than inspected call sites.

Main entry points: [`api/oss/src/core/sessions`](https://github.com/agenta-ai/agenta/tree/main/api/oss/src/core/sessions) (Session runtime), [`api/oss/src/apis/fastapi/agent_templates/router.py`](https://github.com/agenta-ai/agenta/blob/main/api/oss/src/apis/fastapi/agent_templates/router.py) (Agent APIs), [`api/oss/src/apis/fastapi/sessions/router.py`](https://github.com/agenta-ai/agenta/blob/main/api/oss/src/apis/fastapi/sessions/router.py) (Session API), [`api/oss/src/apis/fastapi/triggers/router.py`](https://github.com/agenta-ai/agenta/blob/main/api/oss/src/apis/fastapi/triggers/router.py) (Background triggers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Agent authoring"]
  node_templates["Agent definitions"]
  node_agent_api["Agent APIs<br/>[router.py]"]
end

subgraph group_runtime["Agent runtime"]
  node_sessions_api["Session API<br/>[router.py]"]
  node_session_runtime["Session runtime"]
  node_session_commands["Session commands<br/>[service.py]"]
  node_background["Background triggers<br/>[router.py]"]
  node_workflows["Workflows<br/>[service.py]"]
  node_channels["Chat channels<br/>[service.py]"]
end

subgraph group_integrations["Tools and resources"]
  node_mcp["MCP integrations<br/>[service.py]"]
  node_composio["Composio apps<br/>[adapter.py]"]
  node_workspace["Workspace resources<br/>[service.py]"]
  node_models["Model gateways<br/>[service.py]"]
end

subgraph group_reliability["Observability"]
  node_events["Run events<br/>[service.py]"]
  node_tracing["Run tracing<br/>[router.py]"]
  node_evaluations["Evaluations<br/>[service.py]"]
end

subgraph group_platform["Platform controls"]
  node_permissions["Tool permissions<br/>[service.py]"]
  node_team_access["Team access<br/>[service.py]"]
end

node_user(("User or team"))
node_connected_apps(("Connected applications"))
node_model_provider(("Model provider"))

node_user -->|"defines agent"| node_agent_api
node_agent_api -->|"manages definitions"| node_templates
node_user -->|"starts chat"| node_sessions_api
node_sessions_api -->|"handles session"| node_session_runtime
node_session_runtime -->|"processes commands"| node_session_commands
node_session_runtime -->|"serves chat"| node_channels
node_user -->|"configures runs"| node_background
node_background -->|"starts runs"| node_workflows
node_workflows -->|"runs agent"| node_session_runtime
node_session_runtime -->|"checks actions"| node_permissions
node_session_runtime -->|"uses tools"| node_mcp
node_session_runtime -.->|"uses integrations"| node_composio
node_session_runtime -->|"uses resources"| node_workspace
node_session_runtime -->|"requests completions"| node_models
node_models -->|"calls provider"| node_model_provider
node_composio -.->|"dispatches actions"| node_connected_apps
node_mcp -.->|"connects tools"| node_connected_apps
node_session_runtime -->|"emits events"| node_events
node_session_runtime -->|"records runs"| node_tracing
node_user -->|"reviews quality"| node_evaluations
node_user -->|"manages roles"| node_team_access
node_team_access -->|"controls access"| node_agent_api

click node_templates "https://github.com/agenta-ai/agenta/tree/main/api/oss/src/core/agent_templates"
click node_agent_api "https://github.com/agenta-ai/agenta/blob/main/api/oss/src/apis/fastapi/agent_templates/router.py"
click node_sessions_api "https://github.com/agenta-ai/agenta/blob/main/api/oss/src/apis/fastapi/sessions/router.py"
click node_session_runtime "https://github.com/agenta-ai/agenta/tree/main/api/oss/src/core/sessions"
click node_session_commands "https://github.com/agenta-ai/agenta/blob/main/api/oss/src/core/sessions/commands/service.py"
click node_background "https://github.com/agenta-ai/agenta/blob/main/api/oss/src/apis/fastapi/triggers/router.py"
click node_workflows "https://github.com/agenta-ai/agenta/blob/main/api/oss/src/core/invocations/service.py"
click node_channels "https://github.com/agenta-ai/agenta/blob/main/api/oss/src/core/channels/service.py"
click node_permissions "https://github.com/agenta-ai/agenta/blob/main/api/oss/src/core/gateways/policy/service.py"
click node_mcp "https://github.com/agenta-ai/agenta/blob/main/api/oss/src/core/gateways/mcps/service.py"
click node_composio "https://github.com/agenta-ai/agenta/blob/main/api/oss/src/core/gateway/connections/providers/composio/adapter.py"
click node_workspace "https://github.com/agenta-ai/agenta/blob/main/api/oss/src/core/mounts/service.py"
click node_models "https://github.com/agenta-ai/agenta/blob/main/api/oss/src/core/gateways/llms/service.py"
click node_events "https://github.com/agenta-ai/agenta/blob/main/api/oss/src/core/events/service.py"
click node_tracing "https://github.com/agenta-ai/agenta/blob/main/api/oss/src/apis/fastapi/tracing/router.py"
click node_evaluations "https://github.com/agenta-ai/agenta/blob/main/api/oss/src/core/evaluations/service.py"
click node_team_access "https://github.com/agenta-ai/agenta/blob/main/api/oss/src/core/access/permissions/service.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_templates,node_agent_api,node_user toneBlue
class node_sessions_api,node_session_runtime,node_session_commands,node_background,node_workflows,node_channels toneAmber
class node_mcp,node_composio,node_workspace,node_models toneMint
class node_events,node_tracing,node_evaluations toneRose
class node_permissions,node_team_access,node_connected_apps,node_model_provider toneIndigo
```

## Components

### Agent authoring

- [Agent definitions](https://github.com/agenta-ai/agenta/tree/main/api/oss/src/core/agent_templates): `api/oss/src/core/agent_templates`
- [Agent APIs](https://github.com/agenta-ai/agenta/blob/main/api/oss/src/apis/fastapi/agent_templates/router.py): `api/oss/src/apis/fastapi/agent_templates/router.py`

### Agent runtime

- [Session API](https://github.com/agenta-ai/agenta/blob/main/api/oss/src/apis/fastapi/sessions/router.py): `api/oss/src/apis/fastapi/sessions/router.py`
- [Session runtime](https://github.com/agenta-ai/agenta/tree/main/api/oss/src/core/sessions): `api/oss/src/core/sessions`
- [Session commands](https://github.com/agenta-ai/agenta/blob/main/api/oss/src/core/sessions/commands/service.py): `api/oss/src/core/sessions/commands/service.py`
- [Background triggers](https://github.com/agenta-ai/agenta/blob/main/api/oss/src/apis/fastapi/triggers/router.py): `api/oss/src/apis/fastapi/triggers/router.py`
- [Workflows](https://github.com/agenta-ai/agenta/blob/main/api/oss/src/core/invocations/service.py): `api/oss/src/core/invocations/service.py`
- [Chat channels](https://github.com/agenta-ai/agenta/blob/main/api/oss/src/core/channels/service.py): `api/oss/src/core/channels/service.py`

### Tools and resources

- [MCP integrations](https://github.com/agenta-ai/agenta/blob/main/api/oss/src/core/gateways/mcps/service.py): `api/oss/src/core/gateways/mcps/service.py`
- [Composio apps](https://github.com/agenta-ai/agenta/blob/main/api/oss/src/core/gateway/connections/providers/composio/adapter.py): `api/oss/src/core/gateway/connections/providers/composio/adapter.py`
- [Workspace resources](https://github.com/agenta-ai/agenta/blob/main/api/oss/src/core/mounts/service.py): `api/oss/src/core/mounts/service.py`
- [Model gateways](https://github.com/agenta-ai/agenta/blob/main/api/oss/src/core/gateways/llms/service.py): `api/oss/src/core/gateways/llms/service.py`

### Observability

- [Run events](https://github.com/agenta-ai/agenta/blob/main/api/oss/src/core/events/service.py): `api/oss/src/core/events/service.py`
- [Run tracing](https://github.com/agenta-ai/agenta/blob/main/api/oss/src/apis/fastapi/tracing/router.py): `api/oss/src/apis/fastapi/tracing/router.py`
- [Evaluations](https://github.com/agenta-ai/agenta/blob/main/api/oss/src/core/evaluations/service.py): `api/oss/src/core/evaluations/service.py`

### Platform controls

- [Tool permissions](https://github.com/agenta-ai/agenta/blob/main/api/oss/src/core/gateways/policy/service.py): `api/oss/src/core/gateways/policy/service.py`
- [Team access](https://github.com/agenta-ai/agenta/blob/main/api/oss/src/core/access/permissions/service.py): `api/oss/src/core/access/permissions/service.py`

### Other components

- **User or team**
- **Connected applications**
- **Model provider**

## Connections

- User or team → Agent APIs: defines agent
- Agent APIs → Agent definitions: manages definitions
- User or team → Session API: starts chat
- Session API → Session runtime: handles session
- Session runtime → Session commands: processes commands
- Session runtime → Chat channels: serves chat
- User or team → Background triggers: configures runs
- Background triggers → Workflows: starts runs
- Workflows → Session runtime: runs agent
- Session runtime → Tool permissions: checks actions
- Session runtime → MCP integrations: uses tools
- Session runtime → Composio apps: uses integrations
- Session runtime → Workspace resources: uses resources
- Session runtime → Model gateways: requests completions
- Model gateways → Model provider: calls provider
- Composio apps → Connected applications: dispatches actions
- MCP integrations → Connected applications: connects tools
- Session runtime → Run events: emits events
- Session runtime → Run tracing: records runs
- User or team → Evaluations: reviews quality
- User or team → Team access: manages roles
- Team access → Agent APIs: controls access