How wrtnlabs/agentica works
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.