# thomassuedbroecker/watsonx-agent-langgraph-deployment-example architecture

> Architecture diagram of the GitHub repository thomassuedbroecker/watsonx-agent-langgraph-deployment-example, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-23). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thomassuedbroecker/watsonx-agent-langgraph-deployment-example
- Repository: https://github.com/thomassuedbroecker/watsonx-agent-langgraph-deployment-example

## Overview

##### Project type and purpose
- This is a full-stack example/demo project showing how to build, package, deploy, and consume a custom AI agent (“langgraph-arxiv-research”) on IBM’s watsonx.ai cloud.
- The top-level “agents/langgraph-arxiv-research” directory contains the agent’s Python service code, schemas, build/deploy scripts, and tests.
- The “ui/code” directory contains two client apps (REST and SDK), configuration loaders, authentication helpers, and deployment utilities for interacting with the deployed agent.

##### File structure
- agents/langgraph-arxiv-research
- src/langgraph_react_agent – the core agent class and tools (ArXiv search, weather).
- schema – JSON request/response contracts.
- ai_service.py – the entry-point web service wrapping the agent.
- scripts/build_package.py & deploy.py – package builder and cloud deployment.
- tests – unit tests for tool integrations.
- ui/code
- app_rest.py – simple REST client for end-user UI.
- app_sdk.py – uses IBM watsonx SDK to invoke the agent.
- modules/{load_config, simple_auth, watsonx, watsonx_deployment} – config loader, auth handler, SDK wrappers, and deployment helpers.
- .env_template & config.toml_template – environment and service configuration.

##### README for additional insights
- The README points to a blog post that walks through “Develop and Deploy Custom AI Agents to watsonx.ai on IBM Cloud.”

a. Main components
1) Developer Workstation
– Agent source code, schema definitions, build and deploy scripts, tests.
2) CI/Build process (optional)
– build_package.py creates a Python package (wheel).
3) Deployment to IBM Cloud / watsonx.ai
– deploy.py uses the watsonx_deployment module to push the service.
4) Deployed Agent Service on watsonx.ai
– ai_service.py exposes a REST endpoint using the JSON schemas.
– Internally runs LangGraph React Agent; loads tools for ArXiv and weather.
5) External Services
– ArXiv API
– Weather API
6) UI Clients
– REST client (app_rest.py)
– SDK client (app_sdk.py)
– Both use load_config to read endpoints & creds, simple_auth to obtain tokens, watsonx module to call the AI service.

b. Relationships and interactions
- Developer → runs build_package.py → produces distributable package
- Developer → runs deploy.py → registers and deploys the agent on watsonx.ai
- End user → interacts with UI (REST or SDK) → UI loads config, authenticates, invokes the Watsonx endpoint
- Watsonx.ai sidecar → routes request to the agent service container (ai_service.py)
- Agent service → processes input via LangGraph React Agent → may call out to ArXiv API or Weather API → aggregates results → returns JSON response
- UI → receives JSON response → renders or prints result to user

c. Architectural patterns and principles
- Microservice style: agent logic isolated in its own service container
- Config-driven deployment: all endpoints, creds, and parameters in TOML / env templates
- Clear separation of concerns: packaging/deployment, agent logic, client consumption

d. Key technologies and libraries
- Python 3 with LangGraph React Agent library
- TOML for configurations
- IBM watsonx SDK for service registration and invocation
- JSON Schema for request/response contracts
- External HTTP calls to ArXiv & weather APIs

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Developer Workstation
    subgraph "Developer Workstation"
        direction TB
        DW_Source["Agent Source Code"]:::dev
        DW_Schema["Schema Definitions"]:::dev
        DW_BuildScript["build_package.py"]:::build
        DW_DeployScript["deploy.py"]:::build
        DW_Tests["Unit Tests"]:::dev
    end

    %% CI/Build Process
    subgraph "CI/Build Process"
        direction TB
        CI_Package["Package Builder"]:::build
    end

    %% Deployment to IBM Cloud / watsonx.ai
    subgraph "Deployment"
        direction TB
        Deploy_Helper["watsonx_deployment Module"]:::build
    end

    %% Deployed Agent Service
    subgraph "IBM Cloud / watsonx.ai" 
        direction TB
        Cloud_Service["ai_service.py"]:::cloud
        Agent_Core["Agent Core (agent.py)"]:::cloud
        Agent_Tools["Tool Integrations (tools.py)"]:::cloud
    end

    %% UI Clients
    subgraph "UI Clients"
        direction TB
        UI_REST["REST Client (app_rest.py)"]:::ui
        UI_SDK["SDK Client (app_sdk.py)"]:::ui
        UI_Config["load_config Module"]:::ui
        UI_Auth["simple_auth Module"]:::ui
        UI_SDKWrapper["watsonx Module"]:::ui
        UI_Env[".env_template"]:::ui
        UI_ConfigTOML["config.toml_template"]:::ui
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Ext_Arxiv["ArXiv API"]:::external
        Ext_Weather["Weather API"]:::external
    end

    %% Connections
    DW_Source --> DW_BuildScript
    DW_BuildScript --> CI_Package
    CI_Package --> DW_DeployScript
    DW_DeployScript --> Deploy_Helper
    Deploy_Helper --> Cloud_Service
    Cloud_Service --> Agent_Core
    Agent_Core --> Agent_Tools
    Agent_Tools --> Ext_Arxiv
    Agent_Tools --> Ext_Weather

    UI_REST --> UI_Config
    UI_SDK --> UI_Config
    UI_Config --> UI_Auth
    UI_Auth --> UI_SDKWrapper
    UI_SDKWrapper --> Cloud_Service
    UI_REST --> Cloud_Service

    Cloud_Service --> UI_REST
    Cloud_Service --> UI_SDK

    %% Click Events
    click DW_Source "https://github.com/thomassuedbroecker/watsonx-agent-langgraph-deployment-example/tree/main/agents/langgraph-arxiv-research/src/langgraph_react_agent"
    click DW_Schema "https://github.com/thomassuedbroecker/watsonx-agent-langgraph-deployment-example/tree/main/agents/langgraph-arxiv-research/schema"
    click DW_BuildScript "https://github.com/thomassuedbroecker/watsonx-agent-langgraph-deployment-example/blob/main/agents/langgraph-arxiv-research/scripts/build_package.py"
    click DW_DeployScript "https://github.com/thomassuedbroecker/watsonx-agent-langgraph-deployment-example/blob/main/agents/langgraph-arxiv-research/scripts/deploy.py"
    click DW_Tests "https://github.com/thomassuedbroecker/watsonx-agent-langgraph-deployment-example/tree/main/agents/langgraph-arxiv-research/tests"
    click CI_Package "https://github.com/thomassuedbroecker/watsonx-agent-langgraph-deployment-example/blob/main/agents/langgraph-arxiv-research/scripts/build_package.py"
    click Deploy_Helper "https://github.com/thomassuedbroecker/watsonx-agent-langgraph-deployment-example/blob/main/ui/code/modules/watsonx_deployment.py"
    click Cloud_Service "https://github.com/thomassuedbroecker/watsonx-agent-langgraph-deployment-example/blob/main/agents/langgraph-arxiv-research/ai_service.py"
    click Agent_Core "https://github.com/thomassuedbroecker/watsonx-agent-langgraph-deployment-example/blob/main/agents/langgraph-arxiv-research/src/langgraph_react_agent/agent.py"
    click Agent_Tools "https://github.com/thomassuedbroecker/watsonx-agent-langgraph-deployment-example/blob/main/agents/langgraph-arxiv-research/src/langgraph_react_agent/tools.py"
    click UI_REST "https://github.com/thomassuedbroecker/watsonx-agent-langgraph-deployment-example/blob/main/ui/code/app_rest.py"
    click UI_SDK "https://github.com/thomassuedbroecker/watsonx-agent-langgraph-deployment-example/blob/main/ui/code/app_sdk.py"
    click UI_Config "https://github.com/thomassuedbroecker/watsonx-agent-langgraph-deployment-example/blob/main/ui/code/modules/load_config.py"
    click UI_Auth "https://github.com/thomassuedbroecker/watsonx-agent-langgraph-deployment-example/blob/main/ui/code/modules/simple_auth.py"
    click UI_SDKWrapper "https://github.com/thomassuedbroecker/watsonx-agent-langgraph-deployment-example/blob/main/ui/code/modules/watsonx.py"
    click UI_Env "https://github.com/thomassuedbroecker/watsonx-agent-langgraph-deployment-example/blob/main/ui/code/.env_template"
    click UI_ConfigTOML "https://github.com/thomassuedbroecker/watsonx-agent-langgraph-deployment-example/blob/main/ui/code/config.toml_template"

    %% Styles
    classDef build fill:#e5ffe5,stroke:#2d662d,color:#2d662d
    classDef cloud fill:#e5f0ff,stroke:#336699,color:#336699
    classDef ui fill:#fff5cc,stroke:#b38f00,color:#b38f00
    classDef external fill:#f0f0f0,stroke:#666666,color:#666666
    classDef dev fill:#f9f9f9,stroke:#333333,color:#333333
```
