Building AI Agents for IBM i

This guide covers the core concepts for building AI agents that work with IBM i systems using the agno framework and the MCP (Model Context Protocol) server. Focus is on using FilteredMCPTools to create specialized agents with ta### Connection Security The MCP server supports secure connections and authentication:

# Production security configuration
secure_tools = FilteredMCPTools(
    url="https://your-ibmi-server:3010/mcp",  # Use HTTPS in production
    transport="streamable-http",
    annotation_filters={"toolsets": ["performance"]},
    # Additional security headers can be configured in the MCP server
)

Best Practices for IBM i Agents.

Framework Focus: This documentation focuses on agno, a modern Python AI agent framework. Documentation for LangChain and LangGraph integration will be added in future releases.

Core Concepts

Agent Architecture with agno

IBM i agents built with agno follow a specialized architecture that combines:

Toolset Filtering

Use FilteredMCPTools to limit agents to specific IBM i domains (performance, discovery, etc.)

Domain Specialization

Create focused agents for specific IBM i administrative tasks and workflows

MCP Integration

Connect to your IBM i MCP server with streamable HTTP transport for reliable tool access

Persistent Memory

Maintain conversation context and system knowledge across sessions

FilteredMCPTools: The Foundation

The key innovation in this IBM i MCP implementation is FilteredMCPTools, which extends agno’s standard MCPTools class to filter available tools based on annotations. This allows creating specialized agents with access only to relevant toolsets.

How FilteredMCPTools Works

Annotation-Based Filtering

The MCP server attaches metadata annotations to each tool, including a toolsets annotation that categorizes tools by domain. FilteredMCPTools leverages these annotations to create specialized agent experiences.

Available Toolsets

Based on the prebuilt configurations, the following toolsets are available:

performance: System performance monitoring, memory analysis, CPU metrics
sysadmin_discovery: High-level system service discovery and categorization
sysadmin_browse: Detailed browsing of system services by schema and type
sysadmin_search: Search capabilities for finding specific services and examples

Basic FilteredMCPTools Usage

from ibmi_agents.tools.filtered_mcp_tools import FilteredMCPTools

# Create tools filtered to performance toolset only
performance_tools = FilteredMCPTools(
    url="http://127.0.0.1:3010/mcp",
    transport="streamable-http",
    annotation_filters={"toolsets": ["performance"]}
)

# Multiple toolsets
multi_tools = FilteredMCPTools(
    url="http://127.0.0.1:3010/mcp", 
    transport="streamable-http",
    annotation_filters={"toolsets": ["performance", "sysadmin_discovery"]}
)

# Custom annotation filtering
safe_tools = FilteredMCPTools(
    url="http://127.0.0.1:3010/mcp",
    transport="streamable-http", 
    annotation_filters={
        "readOnlyHint": True,
        "destructiveHint": False
    }
)

Advanced Filtering Patterns

FilteredMCPTools supports sophisticated filtering strategies:

Callable Filters

# Filter tools by title content
title_filtered = FilteredMCPTools(
    annotation_filters={
        "title": lambda title: title and "system" in title.lower()
    }
)

Combined Filters (AND logic)

# Tools must match ALL conditions
strict_filter = FilteredMCPTools(
    annotation_filters={
        "toolsets": ["performance"],
        "readOnlyHint": True,
        "title": lambda t: len(t) < 50 if t else False
    }
)

Legacy Compatibility

# Backward compatible toolsets parameter
legacy_tools = FilteredMCPTools(
    toolsets="performance"  # Equivalent to annotation_filters={"toolsets": ["performance"]}
)

IBM i Agent Patterns

Specialized Agents by Toolset

The existing agents in /agents/src/ibmi_agents/agents/ demonstrate four key patterns for IBM i system administration:

Performance Agent
Discovery Agent
Browse Agent
Search Agent

Toolset: performance
Focus: System performance monitoring and resource analysis

# From create_performance_agent()
performance_tools = FilteredMCPTools(
    url=mcp_url,
    transport=transport,
    annotation_filters={"toolsets": ["performance"]}
)

agent = Agent(
    name="IBM i Performance Monitor",
    instructions=[
        "You are a specialized IBM i performance monitoring assistant.",
        "You have access to comprehensive performance monitoring tools including:",
        "- System status and activity monitoring",
        "- Memory pool analysis", 
        "- Temporary storage tracking",
        "- HTTP server performance metrics",
        "- Active job analysis and CPU consumption tracking"
    ],
    tools=[performance_tools]
)

Available Tools: system_status, memory_pools, temp_storage_buckets, system_activity, etc.

Multi-Agent Operating System

The /agents/ibmi_agentos.py example shows how to deploy multiple specialized agents using agno’s AgentOS:

# Multiple specialized agents running together
agent_os = AgentOS(
    os_id="ibmi-multi-agent-os",
    description="IBM i Multi-Agent System with Specialized Toolsets",
    agents=[
        create_performance_agent(debug_filtering=True),
        create_sysadmin_discovery_agent(debug_filtering=True), 
        create_sysadmin_browse_agent(debug_filtering=True),
        create_sysadmin_search_agent(debug_filtering=True)
    ]
)

# Access via web interface at http://localhost:7777
agent_os.serve(app="ibmi_agentos:app", reload=True)

Benefits of Multi-Agent Architecture:

Domain Expertise: Each agent specializes in specific IBM i domains
Focused Tools: Agents only see relevant tools, improving performance and accuracy
Parallel Operations: Users can interact with different agents simultaneously
Modular Development: Easy to add new specialized agents for emerging needs

Advanced Agent Configuration

agno Agent Features for IBM i

The existing agents demonstrate key agno features optimized for IBM i environments:

Persistent Memory and Context

# From ibmi_agents.py - all agents use SqliteDb for persistence
db = SqliteDb(
    db_file=f"tmp/ibmi_{agent_type}_agent.db",
    memory_table=f"ibmi_{agent_type}_memory",
    session_table=f"ibmi_{agent_type}_sessions",
    metrics_table=f"ibmi_{agent_type}_metrics",
    eval_table=f"ibmi_{agent_type}_evals",
    knowledge_table=f"ibmi_{agent_type}_knowledge"
)

agent = Agent(
    db=db,
    enable_agentic_memory=True,    # Agent remembers context
    enable_user_memories=True,     # Remembers user preferences  
    search_knowledge=True,         # Can search previous interactions
    add_history_to_context=True,   # Includes conversation history
    read_chat_history=True         # Reads past conversations
)

Debug and Monitoring

# Enable detailed filtering and tool debugging
filtered_tools = FilteredMCPTools(
    annotation_filters={"toolsets": ["performance"]},
    debug_filtering=True  # Shows tool filtering decisions
)

agent = Agent(
    tools=[filtered_tools],
    debug_mode=True,        # Detailed logging
    markdown=True           # Rich formatted responses
)

Connection Management

IBM i agents require proper MCP connection handling with async context managers:

# Proper connection management for FilteredMCPTools
async def run_agent_analysis():
    tools = FilteredMCPTools(
        url="http://127.0.0.1:3010/mcp",
        transport="streamable-http",
        annotation_filters={"toolsets": ["performance"]}
    )
    
    # Use async context manager for proper cleanup
    async with tools:
        agent = Agent(
            name="Performance Analyst",
            model=OpenAIChat(id="gpt-4o"),
            tools=[tools]
        )
        
        response = await agent.arun("Check system performance")
        return response

Factory Pattern for Agent Creation

The existing code demonstrates a factory pattern for consistent agent creation:

# From ibmi_agents.py
AVAILABLE_AGENTS = {
    "performance": create_performance_agent,
    "discovery": create_sysadmin_discovery_agent,
    "browse": create_sysadmin_browse_agent,
    "search": create_sysadmin_search_agent,
}

def create_agent(agent_type: str, **kwargs) -> Agent:
    """Create an agent of the specified type with consistent configuration."""
    if agent_type not in AVAILABLE_AGENTS:
        available = ", ".join(AVAILABLE_AGENTS.keys())
        raise ValueError(f"Unknown agent type '{agent_type}'. Available: {available}")
    
    return AVAILABLE_AGENTS[agent_type](**kwargs)

# Usage
performance_agent = create_agent("performance", debug_filtering=True)
discovery_agent = create_agent("discovery", model_id="gpt-3.5-turbo")

Testing and Development

Agent Evaluation Framework

The /agents/src/ibmi_agents/evals/ directory contains evaluation frameworks for testing agent reliability:

# From performance_agent_reliability_evals.py  
from agno.evals import Eval
from agno.evals.metrics import SimpleMatchMetric

def performance_agent_reliability_evals() -> List[Eval]:
    """Evaluation suite for testing performance agent reliability."""
    return [
        Eval(
            id="performance_basic_queries",
            description="Test basic performance monitoring queries",
            test_cases=[
                {
                    "input": "What is the current system status?",
                    "expected": "system_status",  # Expected tool to be used
                },
                {
                    "input": "Show me memory pool information",  
                    "expected": "memory_pools"
                }
            ],
            metric=SimpleMatchMetric()
        )
    ]

Development Environment Setup

The agents directory includes a complete development environment:

# Navigate to agents directory
cd agents/

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e .

# Environment configuration
cp .env.example .env
# Edit .env with your IBM i connection details

# Run individual agents
python agentos_with_filtered_tools.py    # Single performance agent
python ibmi_agentos.py                   # Multi-agent system
python test_tool_filtering.py            # Test filtering functionality

Security and IBM i Integration

IBM i Authority Model Integration

IBM i agents should respect the system’s built-in authority model:

# Use read-only tools for security-conscious deployments
readonly_tools = FilteredMCPTools(
    url="http://127.0.0.1:3010/mcp",
    transport="streamable-http",
    annotation_filters={
        "readOnlyHint": True,        # MCP standard read-only annotation
        "destructiveHint": False     # MCP standard non-destructive annotation
    }
)

# Create security-focused agents
security_agent = Agent(
    name="IBM i Security Analyst", 
    tools=[readonly_tools],
    instructions=[
        "You are a read-only IBM i security and compliance analyst.",
        "You can only view and analyze data - never modify system settings.", 
        "Focus on identifying security risks and compliance issues.",
        "Recommend actions but never attempt to execute them directly."
    ]
)

Connection Security

The MCP server supports secure connections and authentication:

# Production security configuration
secure_tools = FilteredMCPTools(
    url="https://your-ibmi-server:3010/mcp",  # Use HTTPS in production
    transport="streamable-http",
    annotation_filters={"toolsets": ["performance"]},
    # Additional security headers can be configured in the MCP server
)

Quick Start: Running Example Agents

Prerequisites

Running MCP Server: Complete the Quick Start Guide
Python Environment: Python 3.8+ with uv or pip
Environment Configuration: IBM i connection details

Setup and Run

# Navigate to agents directory  
cd agents/

# Install dependencies (uv recommended)
uv sync
# OR pip install -e .

# Configure environment
cp .env.example .env
# Edit .env with your IBM i connection details:
# OPENAI_API_KEY=your_key
# DB2i_HOST=your-ibmi-system  
# DB2i_USER=your-username
# DB2i_PASS=your-password

# Run single performance agent
python agentos_with_filtered_tools.py
# Access at http://localhost:7777

# Run multi-agent system  
python ibmi_agentos.py
# Access multiple specialized agents at http://localhost:7777

# Test tool filtering
python test_tool_filtering.py

Web Interface

Both examples provide web interfaces where you can:

Chat with agents about IBM i system status
Select specific agents for specialized tasks (in multi-agent mode)
View tool calls and debug agent decision-making
Access conversation history and agent memory

Future Framework Support

Coming Soon: Documentation for building IBM i agents using LangChain and LangGraph will be added to this guide in future releases. The FilteredMCPTools approach and toolset concepts will remain consistent across frameworks.

Best Practices for IBM i Agents

Toolset Design

Use FilteredMCPTools for all agents to limit scope and improve performance
Match toolsets to agent purpose: performance agents get performance tools, etc.
Combine MCP standard annotations (readOnlyHint, destructiveHint) with custom toolsets
Enable debug filtering during development to understand tool selection
Test filtering logic with different annotation combinations

agno Integration Patterns

Use AgentOS for multi-agent deployments rather than single large agents
Enable persistent memory (enable_agentic_memory=True) for context retention
Configure separate databases per agent type to avoid cross-contamination
Use async context managers for proper MCP connection cleanup
Leverage agno’s evaluation framework for testing agent reliability

IBM i Specialization

Include IBM i terminology in agent instructions (subsystems, authorities, objects)
Explain tool choices - agents should say why they’re using specific tools
Provide business context - relate technical metrics to operational impact
Respect authority models - use read-only tools when appropriate
Focus agents on specific domains rather than general-purpose system administration

Production Deployment

Use HTTPS for MCP connections in production environments
Configure proper logging with agno’s debug modes and agent databases
Implement health checks to monitor agent and MCP server connectivity
Use appropriate model tiers (GPT-3.5-turbo for routine, GPT-4 for complex analysis)
Monitor tool usage patterns to optimize toolset filtering

Next Steps

Quick Start

Set up your IBM i MCP server with proper toolsets

SQL Tools Building

Understand the underlying tools that power agent capabilities

Configuration

Learn about MCP server configuration and toolset organization

FilteredMCPTools Architecture: The key innovation is using annotation-based filtering to create specialized agents. Rather than building one large agent with access to all tools, create focused agents for specific IBM i domains. This improves performance, accuracy, and maintainability while providing clear separation of concerns for different administrative workflows.

Getting Started

Core Concepts

SQL Tools System

Agent Development

​Building AI Agents for IBM i

​Best Practices for IBM i Agents.

​Core Concepts

​Agent Architecture with agno

Toolset Filtering

Domain Specialization

MCP Integration

Persistent Memory

​FilteredMCPTools: The Foundation

​How FilteredMCPTools Works

​Annotation-Based Filtering

​Available Toolsets

​Basic FilteredMCPTools Usage

​Advanced Filtering Patterns

​Callable Filters

​Combined Filters (AND logic)

​Legacy Compatibility

​IBM i Agent Patterns

​Specialized Agents by Toolset

​Multi-Agent Operating System

​Advanced Agent Configuration

​agno Agent Features for IBM i

​Persistent Memory and Context

​Debug and Monitoring

​Connection Management

​Factory Pattern for Agent Creation

​Testing and Development

​Agent Evaluation Framework

​Development Environment Setup

​Security and IBM i Integration

​IBM i Authority Model Integration

​Connection Security

​Quick Start: Running Example Agents

​Prerequisites

​Setup and Run

​Web Interface

​Future Framework Support

​Best Practices for IBM i Agents

​Next Steps

Quick Start

SQL Tools Building

Configuration

Building AI Agents for IBM i

Best Practices for IBM i Agents.

Core Concepts

Agent Architecture with agno

FilteredMCPTools: The Foundation

How FilteredMCPTools Works

Annotation-Based Filtering

Available Toolsets

Basic FilteredMCPTools Usage

Advanced Filtering Patterns

Callable Filters

Combined Filters (AND logic)

Legacy Compatibility

IBM i Agent Patterns

Specialized Agents by Toolset

Multi-Agent Operating System

Advanced Agent Configuration

agno Agent Features for IBM i

Persistent Memory and Context

Debug and Monitoring

Connection Management

Factory Pattern for Agent Creation

Testing and Development

Agent Evaluation Framework

Development Environment Setup

Security and IBM i Integration

IBM i Authority Model Integration

Connection Security

Quick Start: Running Example Agents

Prerequisites

Setup and Run

Web Interface

Future Framework Support

Best Practices for IBM i Agents

Next Steps