How thomassuedbroecker/watsonx-agent-langgraph-deployment-example works
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