Skip to content

README.md

Latest commit

 

History

History
543 lines (385 loc) · 16.7 KB

README.md

File metadata and controls

543 lines (385 loc) · 16.7 KB

IBM i Agent Infrastructure

Production-ready agent infrastructure for IBM i system administration and performance monitoring. Built on Agno AgentOS with specialized IBM i agents that use MCP (Model Context Protocol) tools.

Architecture

graph TB
    UI[Agent UI<br/>Web Interface]

    subgraph "AgentOS Stack"
        Agents[IBM i Agents<br/>Performance · Discovery<br/>Browse · Search]
        MCP[<b>IBM i MCP Server</b><br/>Central Tool Provider]
        DB[(PostgreSQL<br/>Sessions & Memory)]
    end

    LLM[AI Models<br/>watsonx · OpenAI · Anthropic]
    IBM_i[IBM i System<br/>Db2 Database]

    UI -->|User Queries| Agents
    Agents <-->|<b>MCP Protocol</b><br/><b>Tool Calls</b>| MCP
    Agents -.->|Inference| LLM
    Agents -->|Persist| DB
    MCP -->|SQL Queries<br/>System Services| IBM_i

    %% Styling with better contrast
    classDef ui fill:#0288d1,stroke:#01579b,stroke-width:3px,color:#fff
    classDef agents fill:#ff6f00,stroke:#e65100,stroke-width:3px,color:#fff
    classDef mcp fill:#2e7d32,stroke:#1b5e20,stroke-width:4px,color:#fff
    classDef external fill:#7b1fa2,stroke:#4a148c,stroke-width:2px,color:#fff
    classDef database fill:#c2185b,stroke:#880e4f,stroke-width:2px,color:#fff

    class UI ui
    class Agents agents
    class MCP mcp
    class LLM,IBM_i external
    class DB database
Loading

Architecture Overview

The IBM i Agent Infrastructure is built around the MCP Server as the central component, providing all agents with unified access to IBM i system data and services.

Key Components:

  • Agent UI: Web-based chat interface for interacting with specialized agents
  • IBM i Agents: Four specialized agents (Performance, Discovery, Browse, Search) that orchestrate IBM i operations
  • MCP Server ⭐: Central tool provider enabling agents to query IBM i databases and system services via standardized protocol
  • PostgreSQL: Persistent storage for agent sessions, memory, and conversation history
  • AI Models: Multi-provider LLM support (watsonx, OpenAI, Anthropic) for agent intelligence
  • IBM i System: Production IBM i environment with Db2 database

How It Works:

  1. Users interact with agents through the web UI
  2. Agents leverage the MCP Server to access IBM i data via tool calls
  3. MCP Server executes SQL queries and retrieves system information
  4. Agents use AI models for reasoning and natural language understanding
  5. All interactions are persisted in PostgreSQL for continuity

Prerequisites

Note: The IBM i MCP server runs automatically as part of the Docker Compose stack - no separate setup required!

Quick Start

Get the IBM i Agent Infrastructure running in 3 steps:

1. Configure API Keys

Navigate to the project directory:

cd app

Create infra/.env with your API keys (choose at least one provider):

# AI Model Provider (Choose at least one)
# Anthropic - Get from console.anthropic.com (default model)
ANTHROPIC_API_KEY=sk-your_anthropic_key

# watsonx (IBM Cloud) - Get from cloud.ibm.com
WATSONX_API_KEY=your_ibm_cloud_api_key
WATSONX_PROJECT_ID=your_project_id

# OpenAI - Get from platform.openai.com/api-keys
OPENAI_API_KEY=sk-your_openai_key

📖 For detailed configuration options, including MCP settings, database configuration, and agent customization, see the Configuration Guide

2. Start the Application

Using ag CLI (recommended):

source .venv/bin/activate
ag infra up

Or using Docker Compose directly:

docker compose up -d --build

This starts:

3. Access and Use the Application

Once the application is running, you can interact with the agents in several ways:

  1. Open source Agent UI
  2. Direct API calls
  3. AgentOS Control Plane

Option 1: Agent UI

Open http://localhost:3000 in your browser to interact with the agents via a user-friendly interface: alt text

  • add AgentOS endpoint http://localhost:8000

Option 2: Direct API Calls (Recommended for Testing)

Open http://localhost:8000/docs in your browser to access the Swagger UI where you can:

  • Browse all available agents and endpoints
  • Test agents directly in the browser
  • View request/response schemas
  • See example payloads

Use curl or any HTTP client to call the agents:

# Check IBM i system performance
curl -X 'POST' \
  'http://localhost:8000/agents/ibmi-performance-monitor/runs' \
  -H 'accept: application/json' \
  -H 'Content-Type: multipart/form-data' \
  -F 'message=Check my system status' \
  -F 'stream=false'

Option 3: AgentOS UI (Visual Chat Interface)

  1. Open os.agno.com in your browser
  2. Click "Connect to Local" and enter http://localhost:8000
  3. Select an agent from the sidebar
  4. Start chatting with the agent

Verify Setup

Check that everything is running correctly:

# Check service health
curl http://localhost:8000/health

# List available agents
curl http://localhost:8000/agents

# View PostgreSQL database (optional)
docker compose exec postgres psql -U postgres -d agno -c "\dt"

4. Managing the Application

Stop the application:

ag infra down
# or: docker compose down

Restart the application:

ag infra restart
# or: docker compose restart

View logs:

docker compose logs -f

Check status:

docker compose ps

Troubleshooting

❌ Error: "Unable to serialize unknown type: ModelInference"

Cause: This error occurs when the WatsonX model client can't be serialized for MCP communication.

Solution: This has been fixed in the latest version of agents/utils/filtered_mcp_tools.py. Make sure you're using the latest code:

git pull
docker compose up -d --build
❌ Error: "cannot import name 'ParsedBetaContentBlockStopEvent' from 'anthropic'"

Cause: Incompatible version of the Anthropic SDK.

Solution: Update the Anthropic SDK version in pyproject.toml to >=0.80.0 and regenerate requirements:

./scripts/generate_requirements.sh
docker compose up -d --build
🔌 MCP Connection Errors

Symptoms: "Failed to connect to MCP server" or timeout errors

Solutions:

  1. Verify MCP server container is running:

    docker compose ps ibmi-mcp-server
curl http://localhost:3010/health

  2. Check MCP server logs:

    docker compose logs ibmi-mcp-server

  3. Verify network configuration:

    • The MCP server runs automatically in Docker Compose on ibmi-mcp-server:3010
    • Default MCP_URL in .env should be: http://ibmi-mcp-server:3010/mcp
    • See Configuration Guide for details

  4. Restart the MCP server:

    docker compose restart ibmi-mcp-server
🔑 API Key Issues

Symptoms: "Invalid API key" or authentication errors

Solutions:

  1. Verify API keys are set correctly in infra/.env:

    # Check if env file exists and has correct format
cat infra/.env | grep API_KEY

  2. Restart after changing .env:

    docker compose down
docker compose up -d

  3. Test API keys directly:

📊 Database Connection Issues

Symptoms: "Failed to connect to database" errors

Solutions:

  1. Check PostgreSQL is running:

    docker compose ps postgres

  2. Verify database credentials match in infra/.env and compose.yml

  3. Reset database (warning: deletes all data):

    docker compose down -v
docker compose up -d
🐛 Enable Debug Mode

To get more detailed logs for troubleshooting:

  1. In infra/.env:

    DEBUG=true
LOG_LEVEL=DEBUG

  2. In infra/config.yaml (for specific agent):

    agents:
  ibmi-performance-monitor:
    debug_mode: true

  3. Restart and view logs:

    docker compose restart
docker compose logs -f agent-api
📖 View Agent Logs 
# All services
docker compose logs -f

# Specific service
docker compose logs -f agent-api

# Last 100 lines
docker compose logs --tail=100 agent-api

# Follow with timestamps
docker compose logs -f -t agent-api

IBM i Agents

The infrastructure includes specialized agents for IBM i administration:

Performance Agent

Monitor and analyze IBM i system performance.

Capabilities:

  • System status and activity monitoring
  • CPU utilization analysis
  • Memory pool tracking
  • Job performance analysis
  • HTTP server metrics

API Endpoint: /agents/ibmi-performance-monitor

SysAdmin Agents

Three specialized agents for system administration:

Discovery Agent (/agents/ibmi-sysadmin-discovery):

  • High-level system overviews
  • Service category summaries
  • Component inventories

Browse Agent (/agents/ibmi-sysadmin-browse):

  • Detailed service exploration
  • Schema-based browsing
  • Object type filtering

Search Agent (/agents/ibmi-sysadmin-search):

  • Service name searches
  • Example code lookup
  • Documentation searches

Workflows (Beta)

Pre-built workflows for common IBM i tasks (see workflows/):

  • Simple Performance Check: Quick system health assessment
  • Performance Investigation: Deep dive into performance issues
  • Capacity Planning: Resource utilization forecasting
  • Database Tuning: Db2 performance optimization
  • System Health Audit: Comprehensive system analysis

Development Setup

To setup your local virtual environment:

Install uv

We use uv for python environment and package management. Install it by following the the uv documentation or use the command below for unix-like systems:

curl -LsSf https://astral.sh/uv/install.sh | sh

Create Virtual Environment & Install Dependencies

Run the dev_setup.sh script. This will create a virtual environment and install project dependencies:

./scripts/dev_setup.sh

Activate Virtual Environment

Activate the created virtual environment:

source .venv/bin/activate

(On Windows, the command might differ, e.g., .venv\Scripts\activate)

Managing Python Dependencies

If you need to add or update python dependencies:

Modify pyproject.toml

Add or update your desired Python package dependencies in the [dependencies] section of the pyproject.toml file.

Generate requirements.txt

The requirements.txt file is used to build the application image. After modifying pyproject.toml, regenerate requirements.txt using:

./scripts/generate_requirements.sh

To upgrade all existing dependencies to their latest compatible versions, run:

./scripts/generate_requirements.sh upgrade

Rebuild Docker Images

Rebuild your Docker images to include the updated dependencies:

docker compose up -d --build

Running Tests

This project comes with a set of integration tests that you can use to ensure the application is working as expected.

First, start the application:

docker compose up -d

Then, run the tests:

pytest tests/

Then close the application again:

docker compose down

Community & Support

Need help, have a question, or want to connect with the community?

Running in Production

This repository includes a Dockerfile for building a production-ready container image of the application.

The general process to run in production is:

  1. Update the scripts/build_image.sh file and set your IMAGE_NAME and IMAGE_TAG variables.
  2. Build and push the image to your container registry:
./scripts/build_image.sh
  1. Run in your cloud provider of choice.

Detailed Steps

  1. Configure for Production
  • Ensure your production environment variables (e.g., OPENAI_API_KEY, database connection strings) are securely managed. Most cloud providers offer a way to set these as environment variables for your deployed service.
  • Review the agent configurations in the /agents directory and ensure they are set up for your production needs (e.g., correct model versions, any production-specific settings).
  1. Build Your Production Docker Image

  • Update the scripts/build_image.sh script to set your desired IMAGE_NAME and IMAGE_TAG (e.g., your-repo/agent-api:v1.0.0).

  • Run the script to build and push the image:

    ./scripts/build_image.sh
  1. Deploy to a Cloud Service With your image in a registry, you can deploy it to various cloud services that support containerized applications. Some common options include:

  • Serverless Container Platforms:

    • Google Cloud Run: A fully managed platform that automatically scales your stateless containers. Ideal for HTTP-driven applications.
    • AWS App Runner: Similar to Cloud Run, AWS App Runner makes it easy to deploy containerized web applications and APIs at scale.
    • Azure Container Apps: Build and deploy modern apps and microservices using serverless containers.

  • Container Orchestration Services:

    • Amazon Elastic Container Service (ECS): A highly scalable, high-performance container orchestration service that supports Docker containers. Often used with AWS Fargate for serverless compute or EC2 instances for more control.
    • Google Kubernetes Engine (GKE): A managed Kubernetes service for deploying, managing, and scaling containerized applications using Google infrastructure.
    • Azure Kubernetes Service (AKS): A managed Kubernetes service for deploying and managing containerized applications in Azure.

  • Platform as a Service (PaaS) with Docker Support

    • Railway.app: Offers a simple way to deploy applications from a Dockerfile. It handles infrastructure, scaling, and networking.
    • Render: Another platform that simplifies deploying Docker containers, databases, and static sites.
    • Heroku: While traditionally known for buildpacks, Heroku also supports deploying Docker containers.

  • Specialized Platforms:

    • Modal: A platform designed for running Python code (including web servers like FastAPI) in the cloud, often with a focus on batch jobs, scheduled functions, and model inference, but can also serve web endpoints.

The specific deployment steps will vary depending on the chosen provider. Generally, you'll point the service to your container image in the registry and configure aspects like port mapping (the application runs on port 8000 by default inside the container), environment variables, scaling parameters, and any necessary database connections.

  1. Database Configuration
  • The default docker-compose.yml sets up a PostgreSQL database for local development. In production, you will typically use a managed database service provided by your cloud provider (e.g., AWS RDS, Google Cloud SQL, Azure Database for PostgreSQL) for better reliability, scalability, and manageability.
  • Ensure your deployed application is configured with the correct database connection URL for your production database instance. This is usually set via an environment variables.

Resources