# maestroerror/laragent architecture

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

- Interactive diagram: https://gitdiagram.com/maestroerror/laragent
- Repository: https://github.com/maestroerror/laragent

## Overview

LarAgent is a Laravel framework for defining conversational AI agents. A user invokes an agent directly or through the documented OpenAI-compatible API; the agent prepares a request for a configured provider, supports tool calls and structured or multimodal interactions, and maintains conversation context and history. Context storage, truncation, events, and usage tracking provide supporting capabilities. The README documents broader features, but several implementations were not sampled, so their internal connections are not asserted here.

Main entry points: [`src/Agent.php`](https://github.com/maestroerror/laragent/blob/main/src/Agent.php) (Agent), [`src/API/Completions.php`](https://github.com/maestroerror/laragent/blob/main/src/API/Completions.php) (Completions), [`src/API/Completion/Controllers/SingleAgentController.php`](https://github.com/maestroerror/laragent/blob/main/src/API/Completion/Controllers/SingleAgentController.php) (Single-agent API), [`src/API/Completion/Controllers/MultiAgentController.php`](https://github.com/maestroerror/laragent/blob/main/src/API/Completion/Controllers/MultiAgentController.php) (Multi-agent API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent["Agent runtime"]
  node_agent["Agent<br/>[Agent.php]"]
  node_tooling["Agent tools<br/>[Tool.php]"]
  node_messages["Message models"]
end

subgraph group_api["API exposure"]
  node_single_api["Single-agent API"]
  node_multi_api["Multi-agent API"]
  node_completions["Completions<br/>[Completions.php]"]
end

subgraph group_providers["LLM providers"]
  node_driver_contract["Driver contract<br/>[LlmDriver.php]"]
  node_openai_driver["OpenAI drivers"]
  node_other_drivers["Provider drivers<br/>[ClaudeDriver.php]"]
  node_driver_config["Driver configuration<br/>[DriverConfig.php]"]
end

subgraph group_context["Context and memory"]
  node_history[("Chat histories")]
  node_context_manager["Context manager<br/>[ContextManager.php]"]
  node_identity["Session identity"]
  node_identity_storage[("Identity storage")]
  node_storage_manager["Storage failover<br/>[StorageManager.php]"]
  node_storage_drivers["Storage drivers<br/>[CacheStorage.php]"]
  node_truncation["History truncation"]
end

subgraph group_support["Agent capabilities"]
  node_structured["Structured output"]
  node_events["Lifecycle events<br/>[Events.php]"]
  node_usage[("Usage tracking<br/>[UsageStorage.php]")]
end

node_user(("Application user"))
node_llm_service{{"LLM provider"}}

node_user -->|"invokes"| node_agent
node_user -->|"submits completion"| node_single_api
node_user -->|"submits completion"| node_multi_api
node_single_api -->|"delegates to"| node_completions
node_multi_api -->|"delegates to"| node_completions
node_completions -->|"uses"| node_agent
node_agent -->|"sends requests"| node_driver_contract
node_agent -->|"maintains history"| node_history
node_agent -->|"offers tools"| node_tooling
node_agent -->|"supports output schemas"| node_structured
node_agent -->|"uses tool-call messages"| node_messages
node_driver_contract -->|"sends prompts"| node_llm_service
node_openai_driver -.->|"calls provider"| node_llm_service
node_other_drivers -.->|"calls provider"| node_llm_service
node_driver_config -->|"configures"| node_openai_driver
node_agent -->|"uses context"| node_context_manager
node_agent -->|"creates identity"| node_identity
node_agent -->|"supports truncation"| node_truncation
node_identity_storage -->|"persists identities"| node_storage_manager
node_storage_manager -.->|"reads and writes"| node_storage_drivers
node_agent -->|"dispatches lifecycle events"| node_events
node_agent -.->|"tracks usage"| node_usage

click node_agent "https://github.com/maestroerror/laragent/blob/main/src/Agent.php"
click node_tooling "https://github.com/maestroerror/laragent/blob/main/src/Tool.php"
click node_messages "https://github.com/maestroerror/laragent/blob/main/src/Messages/ToolCallMessage.php"
click node_single_api "https://github.com/maestroerror/laragent/blob/main/src/API/Completion/Controllers/SingleAgentController.php"
click node_multi_api "https://github.com/maestroerror/laragent/blob/main/src/API/Completion/Controllers/MultiAgentController.php"
click node_completions "https://github.com/maestroerror/laragent/blob/main/src/API/Completions.php"
click node_driver_contract "https://github.com/maestroerror/laragent/blob/main/src/Core/Contracts/LlmDriver.php"
click node_openai_driver "https://github.com/maestroerror/laragent/blob/main/src/Drivers/OpenAi/BaseOpenAiDriver.php"
click node_other_drivers "https://github.com/maestroerror/laragent/blob/main/src/Drivers/Anthropic/ClaudeDriver.php"
click node_driver_config "https://github.com/maestroerror/laragent/blob/main/src/Core/DTO/DriverConfig.php"
click node_history "https://github.com/maestroerror/laragent/blob/main/src/History/InMemoryChatHistory.php"
click node_context_manager "https://github.com/maestroerror/laragent/blob/main/src/Context/ContextManager.php"
click node_identity "https://github.com/maestroerror/laragent/blob/main/src/Context/SessionIdentity.php"
click node_identity_storage "https://github.com/maestroerror/laragent/blob/main/src/Context/Storages/IdentityStorage.php"
click node_storage_manager "https://github.com/maestroerror/laragent/blob/main/src/Context/StorageManager.php"
click node_storage_drivers "https://github.com/maestroerror/laragent/blob/main/src/Context/Drivers/CacheStorage.php"
click node_truncation "https://github.com/maestroerror/laragent/blob/main/src/Context/Truncation/SimpleTruncationStrategy.php"
click node_structured "https://github.com/maestroerror/laragent/blob/main/src/Core/Helpers/SchemaGenerator.php"
click node_events "https://github.com/maestroerror/laragent/blob/main/src/Core/Traits/Events.php"
click node_usage "https://github.com/maestroerror/laragent/blob/main/src/Usage/UsageStorage.php"

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_agent,node_tooling,node_messages,node_user toneBlue
class node_single_api,node_multi_api,node_completions toneAmber
class node_driver_contract,node_openai_driver,node_other_drivers,node_driver_config toneMint
class node_history,node_context_manager,node_identity,node_identity_storage,node_storage_manager,node_storage_drivers,node_truncation toneRose
class node_structured,node_events,node_usage,node_llm_service toneIndigo
```

## Components

### Agent runtime

- [Agent](https://github.com/maestroerror/laragent/blob/main/src/Agent.php): `src/Agent.php`
- [Agent tools](https://github.com/maestroerror/laragent/blob/main/src/Tool.php): `src/Tool.php`
- [Message models](https://github.com/maestroerror/laragent/blob/main/src/Messages/ToolCallMessage.php): `src/Messages/ToolCallMessage.php`

### API exposure

- [Single-agent API](https://github.com/maestroerror/laragent/blob/main/src/API/Completion/Controllers/SingleAgentController.php): `src/API/Completion/Controllers/SingleAgentController.php`
- [Multi-agent API](https://github.com/maestroerror/laragent/blob/main/src/API/Completion/Controllers/MultiAgentController.php): `src/API/Completion/Controllers/MultiAgentController.php`
- [Completions](https://github.com/maestroerror/laragent/blob/main/src/API/Completions.php): `src/API/Completions.php`

### LLM providers

- [Driver contract](https://github.com/maestroerror/laragent/blob/main/src/Core/Contracts/LlmDriver.php): `src/Core/Contracts/LlmDriver.php`
- [OpenAI drivers](https://github.com/maestroerror/laragent/blob/main/src/Drivers/OpenAi/BaseOpenAiDriver.php): `src/Drivers/OpenAi/BaseOpenAiDriver.php`
- [Provider drivers](https://github.com/maestroerror/laragent/blob/main/src/Drivers/Anthropic/ClaudeDriver.php): `src/Drivers/Anthropic/ClaudeDriver.php`
- [Driver configuration](https://github.com/maestroerror/laragent/blob/main/src/Core/DTO/DriverConfig.php): `src/Core/DTO/DriverConfig.php`

### Context and memory

- [Chat histories](https://github.com/maestroerror/laragent/blob/main/src/History/InMemoryChatHistory.php): `src/History/InMemoryChatHistory.php`
- [Context manager](https://github.com/maestroerror/laragent/blob/main/src/Context/ContextManager.php): `src/Context/ContextManager.php`
- [Session identity](https://github.com/maestroerror/laragent/blob/main/src/Context/SessionIdentity.php): `src/Context/SessionIdentity.php`
- [Identity storage](https://github.com/maestroerror/laragent/blob/main/src/Context/Storages/IdentityStorage.php): `src/Context/Storages/IdentityStorage.php`
- [Storage failover](https://github.com/maestroerror/laragent/blob/main/src/Context/StorageManager.php): `src/Context/StorageManager.php`
- [Storage drivers](https://github.com/maestroerror/laragent/blob/main/src/Context/Drivers/CacheStorage.php): `src/Context/Drivers/CacheStorage.php`
- [History truncation](https://github.com/maestroerror/laragent/blob/main/src/Context/Truncation/SimpleTruncationStrategy.php): `src/Context/Truncation/SimpleTruncationStrategy.php`

### Agent capabilities

- [Structured output](https://github.com/maestroerror/laragent/blob/main/src/Core/Helpers/SchemaGenerator.php): `src/Core/Helpers/SchemaGenerator.php`
- [Lifecycle events](https://github.com/maestroerror/laragent/blob/main/src/Core/Traits/Events.php): `src/Core/Traits/Events.php`
- [Usage tracking](https://github.com/maestroerror/laragent/blob/main/src/Usage/UsageStorage.php): `src/Usage/UsageStorage.php`

### Other components

- **Application user**
- **LLM provider**

## Connections

- Application user → Agent: invokes
- Application user → Single-agent API: submits completion
- Application user → Multi-agent API: submits completion
- Single-agent API → Completions: delegates to (evidence: `src/API/Completion/Controllers/SingleAgentController.php`)
- Multi-agent API → Completions: delegates to (evidence: `src/API/Completion/Controllers/MultiAgentController.php`)
- Completions → Agent: uses (evidence: `src/API/Completions.php`)
- Agent → Driver contract: sends requests (evidence: `src/Agent.php`)
- Agent → Chat histories: maintains history
- Agent → Agent tools: offers tools
- Agent → Structured output: supports output schemas
- Agent → Message models: uses tool-call messages (evidence: `src/Agent.php`)
- Driver contract → LLM provider: sends prompts (evidence: `src/Core/Contracts/LlmDriver.php`)
- OpenAI drivers → LLM provider: calls provider
- Provider drivers → LLM provider: calls provider
- Driver configuration → OpenAI drivers: configures (evidence: `src/Drivers/OpenAi/OpenAiDriver.php`)
- Agent → Context manager: uses context (evidence: `src/Agent.php`)
- Agent → Session identity: creates identity (evidence: `src/Agent.php`)
- Agent → History truncation: supports truncation (evidence: `src/Agent.php`)
- Identity storage → Storage failover: persists identities (evidence: `src/Context/Storages/IdentityStorage.php`)
- Storage failover → Storage drivers: reads and writes
- Agent → Lifecycle events: dispatches lifecycle events (evidence: `src/Core/Traits/Events.php`)
- Agent → Usage tracking: tracks usage (evidence: `src/Agent.php`)
