# wrtnlabs/agentica architecture

> Architecture diagram of the GitHub repository wrtnlabs/agentica, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/wrtnlabs/agentica
- Repository: https://github.com/wrtnlabs/agentica

## Overview

##### Project Type and Purpose
- Agentica is an “agentic AI” library that specializes in LLM function calling. It is used to define controllers using either Swagger/OpenAPI specifications or TypeScript class types. These controllers serve as definitions that the Agentica core uses to “conversate” (handle conversation input and delegate calls).
- The project is structured as a monorepo with multiple packages (core, chat, cli, benchmark, pg-vector-selector, rpc, etc.) which support different facets such as the main library capabilities, conversational UI examples, command-line tooling, benchmarking, and plugin modules.

##### Analyzing the File Structure and Key Components
- The top-level structure contains configuration files, a website, articles, and multiple packages.
- In packages/core you see the main implementation:
– It contains components for chatgpt integration (ChatGptAgent, ChatGptCallFunctionAgent, etc.), context management, event handling, and prompt streaming.
– It defines events (e.g., AgenticaCallEvent, AgenticaCancelEvent, AgenticaDescribeEvent) and internal transformation logics.
- Packages such as chat and cli provide frontend examples and command-line interfaces respectively. Benchmark and other plugin packages support additional functionality (e.g., performance measurement, vector selection).
- The README highlights that a user instantiates an Agentica instance with controller configurations and then calls a method (e.g., conversate) to start interaction.

##### Main Components
a. Client/Interface Layer
– The user or front-end (for example, the chat web app in packages/chat or the playground on the website) feeds a conversation input.
b. Agentica Core
– This central package orchestrates the workflow.
– It processes conversational input and manages internal events.
– Key subcomponents: Conversation Orchestrator, Event Dispatcher, Context Manager, and Operation/Function Caller.
c. LLM Integration Module
– Located in packages/core/src/chatgpt, containing agents like ChatGptAgent and specialized agents for call, cancel, describe, and select operations.
d. Controllers and Function Definitions
– Provided either as Swagger/OpenAPI documents or derived from TypeScript class types (as seen with typia.llm.application) in user code.
e. Supporting Modules and Plugins
– Benchmark, RPC services, and vector selector components communicate with Agentica core, supporting performance and external integrations.

##### Flow and Data Interactions (The Conversation Workflow)
- Conversation Orchestration: The Agentica core takes the input and immediately uses its context and event-management subsystem to create an agentic conversation session.
- LLM Engagement: The input is forwarded to an LLM integration module that processes the text. Here, it may generate events such as:
– AgenticaCallEvent (triggering function calls)
– AgenticaDescribeEvent (for query clarifications)
– AgenticaSelectEvent (in case of multi-options)
- Function Calling: Based on the LLM’s decisions, the workflow maps the conversation prompt to specific function calls defined by the controllers. These are processed either synchronously or asynchronously.
- Event Dispatching: After executing functions, the results are converted into Agentica events and dispatched back to the conversation session.
- Response Formation: Finally, Agentica collates results and returns a coherent answer to the user, possibly accompanied by additional context (e.g., function execution details, prompt history).

##### Architectural Patterns and Design Principles
– Event-Driven Architecture: With clearly defined events (e.g., call, cancel, execute) used in processing input responses.
– Modular Design: Separation between the core logic, LLM integration, external controller definitions, and supporting utilities.
– Plug-and-Play extensibility: Through plugin modules (benchmark, CLI, RPC interfaces) that integrate seamlessly with the main Agentica core.
– Declarative Configuration: Accepting Swagger or TypeScript definitions streamlines how function calls are composed into agent workflows.

##### Special Note on Agentica’s Conversation Workflow
- Sequential nature of the flow: User Prompt → Agentica Core → LLM Decision Making → Event Emission (call/describe/select) → Calling the actual functions as defined in contract controllers → Aggregating responses → Communicating the final answer.
- Feedback loops where the response can be further processed (e.g., follow-up prompts or adjustments in context) to support iterative conversation.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client/Interface Layer
    subgraph "Client/Interface Layer"
        CI("User/Interface\\n(Chat App / Website)"):::ui
    end

    %% Agentica Core Layer with subcomponents
    subgraph "Agentica Core"
        AC("Agentica Core Engine"):::core
        CO("Conversation Orchestrator"):::coreSub
        ED("Event Dispatcher"):::coreSub
        CM("Context Manager"):::coreSub
        OC("Operation/Function Caller"):::coreSub
    end

    %% LLM Integration Module
    subgraph "LLM Integration Module"
        LLM("LLM Integration\\n(ChatGpt Agents)"):::integration
    end

    %% Supporting Modules
    subgraph "Supporting Modules"
        BENCH("Benchmark"):::support
        CLI("CLI"):::support
        RPC("RPC Services"):::support
        PG("PG Vector Selector"):::support
    end

    %% Main Conversation Workflow Flow
    CI -->|"sendsPrompt"| AC
    AC -->|"orchestrates"| CO
    CO -->|"initiates"| ED
    ED -->|"managesContext"| CM
    CM -->|"callsFunction"| OC
    AC -->|"delegatesTo"| LLM
    LLM -->|"emitsEvents"| ED
    OC -->|"aggregatesResponse"| AC
    AC -->|"returnsAnswer"| CI

    %% Supporting Modules Integration (Plug-and-Play Extensibility)
    AC ---|"integrates with"| BENCH
    AC ---|"integrates with"| CLI
    AC ---|"integrates with"| RPC
    AC ---|"integrates with"| PG

    %% Click Events mapping to file/directory paths
    click CI "https://github.com/wrtnlabs/agentica/tree/main/packages/chat/src"
    click AC "https://github.com/wrtnlabs/agentica/tree/main/packages/core"
    click LLM "https://github.com/wrtnlabs/agentica/tree/main/packages/core/src/chatgpt"
    click BENCH "https://github.com/wrtnlabs/agentica/tree/main/packages/benchmark"
    click CLI "https://github.com/wrtnlabs/agentica/tree/main/packages/cli"
    click RPC "https://github.com/wrtnlabs/agentica/tree/main/packages/rpc"
    click PG "https://github.com/wrtnlabs/agentica/tree/main/packages/pg-vector-selector"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#339,stroke-width:2px;
    classDef core fill:#ffe6cc,stroke:#e67300,stroke-width:2px;
    classDef coreSub fill:#ffdd99,stroke:#cc6600,stroke-width:2px;
    classDef integration fill:#d9ead3,stroke:#38761d,stroke-width:2px;
    classDef support fill:#f4cccc,stroke:#cc0000,stroke-width:2px;
```
