# sebharvey/testaiagent architecture

> Architecture diagram of the GitHub repository sebharvey/testaiagent, 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/sebharvey/testaiagent
- Repository: https://github.com/sebharvey/testaiagent

## Overview

##### Project Type & Purpose
- This is a serverless AI agent built on .NET isolated Azure Functions.
- It integrates with Anthropic’s Claude API for natural language processing while also using an extensible framework to integrate custom tools (such as a weather tool and flight search tool).
- The primary purpose is to process HTTP requests (user messages), maintain conversation state, and, when needed, call external service APIs (e.g., Claude, Weather, Google Flights) via custom tools.

##### File Structure
- Top-level directories:
- /src: Contains all source code, with subdirectories for tests, the web component (likely for static frontend assets), and the main agent project.
- /src/TestAiAgent: Contains the core logic including Functions (entry point through MessageFunction), LanguageModel (ClaudeClient and related extensions), Models (data contracts for requests/responses), Orchestrator (AgentOrchestrator), and Tooling (tool implementations and the ToolRegistry).
- /src/TestAiAgent.Tests: Contains unit tests that target the agent’s functionality.
- The project’s structure indicates clear separation of concerns, with dedicated areas for:
- Azure Functions API endpoints (e.g., MessageFunction)
- External communication (ClaudeClient communicating with the Claude API)
- Business logic that orchestrates conversation flow (AgentOrchestrator)
- Extensible tool management (ToolRegistry and individual tool implementations under Tooling)
- Configuration files (in the Properties folder and launchSettings.json) indicate deployment specifics and dependency management (including ARM templates for Azure resources).

##### Key Architectural Components
a. Core Azure Functions API Layer
- Component: MessageFunction (HTTP-triggered function)
- Role: Entry point for processing incoming HTTP POST requests at the /api/messages endpoint and handling session management.

b. Orchestration Layer
- Component: AgentOrchestrator
- Role: Coordinates input from the MessageFunction, manages the conversation state, queries the tool registry, and routes messages to the ClaudeClient.

c. Language Model Integration
- Component: ClaudeClient
- Role: Prepares and sends requests to the Claude API, processes the responses from the natural language model, and determines whether a tool should be used.

d. Tooling & Extension Framework
- Component: ToolRegistry
- Components: Concrete tools such as WeatherTool, FlightSearchTool, etc.
- Role: Manages and provides available tools for execution. The tools interact with external APIs (e.g., Weather API, Google Flights) to accomplish specific tasks.

e. External Services
- Components: External APIs like Claude API, Weather API, and additional APIs (e.g., Google Flights) referenced by the tools.
- Interaction: The Claude Client communicates with the Claude API while each tool (such as WeatherTool) communicates with its respective external API.

##### Relationships and Interactions
- Data Flow Overview:
- A User sends an HTTP POST request to the MessageFunction.
- MessageFunction handles deserialization, session history operations, and then calls AgentOrchestrator.
- AgentOrchestrator coordinates with both the ToolRegistry and the ClaudeClient.
- ClaudeClient communicates with the external Claude API. Based on the response (e.g., a tool usage request), the orchestrator may trigger a specific tool.
- The ToolRegistry provides the tool instance (e.g., WeatherTool) and that tool makes a call to its external API.
- The response from the tool goes back through the orchestrator to enrich session history and generate the final response sent back to the MessageFunction and eventually to the user.

##### Architectural Patterns & Design Principles
- Separation of concerns is well-demonstrated with clear boundaries between:
- API handling (Azure Functions)
- Orchestration logic
- External service communication (handled by the ClaudeClient and tools)
- Extensibility: The ToolRegistry is designed to allow the addition of new tools without major refactoring.
- Serverless design: Emphasizes stateless function execution with external state management (session chat histories maintained by the orchestrator).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Nodes
    U["User"]

    subgraph "API Layer"
        MF["MessageFunction (HTTP Trigger)"]
    end

    subgraph "Orchestration Layer"
        AO["AgentOrchestrator"]
    end

    subgraph "Language Model Integration"
        CC["ClaudeClient"]
        CA["Claude API"]
    end

    subgraph "Tooling & Extension Framework"
        TR["ToolRegistry"]
        WT["WeatherTool"]
        FT["FlightSearchTool"]
        WA["Weather API"]
        GF["Google Flights"]
    end

    %% Flow Connections
    U -->|"HTTP_POST"| MF
    MF -->|"ProcessMessage"| AO
    AO -->|"CallClaude"| CC
    CC -->|"SendRequest"| CA
    CA -->|"ReceiveResponse"| CC
    CC -->|"ReturnDecision"| AO
    AO -->|"ToolExecution"| TR
    TR -->|"ExecuteWeatherTool"| WT
    TR -->|"ExecuteFlightSearchTool"| FT
    WT -->|"CallAPI"| WA
    FT -->|"CallAPI"| GF
    WT -->|"ReturnResult"| TR
    FT -->|"ReturnResult"| TR
    TR -->|"ToolResponse"| AO
    AO -->|"ReturnFinalResponse"| MF
    MF -->|"HTTP_Response"| U

    %% Click Events
    click MF "https://github.com/sebharvey/testaiagent/blob/master/src/TestAiAgent/Functions/MessageFunction.cs"
    click AO "https://github.com/sebharvey/testaiagent/blob/master/src/TestAiAgent/Orchestrator/AgentOrchestrator.cs"
    click CC "https://github.com/sebharvey/testaiagent/blob/master/src/TestAiAgent/LanguageModel/ClaudeClient.cs"
    click TR "https://github.com/sebharvey/testaiagent/blob/master/src/TestAiAgent/Tooling/ToolRegistry.cs"
    click WT "https://github.com/sebharvey/testaiagent/blob/master/src/TestAiAgent/Tooling/Tools/WeatherTool.cs"
    click FT "https://github.com/sebharvey/testaiagent/blob/master/src/TestAiAgent/Tooling/Tools/FlightSearchTool.cs"

    %% Styles
    class U default
    class MF api
    class AO orchestrator
    class CC lm
    class CA external
    class TR tool
    class WT tool
    class FT tool
    class WA external
    class GF external

    %% Class Definitions for Colors
    classDef api fill:#cce5ff,stroke:#1f78b4,stroke-width:2px;
    classDef orchestrator fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef lm fill:#f3e5f5,stroke:#8e24aa,stroke-width:2px;
    classDef tool fill:#fff3cd,stroke:#ffc107,stroke-width:2px;
    classDef external fill:#eeeeee,stroke:#999999,stroke-dasharray: 5, 5,stroke-width:2px;
```
