---
title: "Building AI Agents"
description: "Core concepts for developing AI agents for IBM i systems using agno and MCP toolset filtering."
---
# 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](https://docs.agno.com/introduction) 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:
```python
# 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.
<Note>
**Framework Focus**: This documentation focuses on **[agno](https://docs.agno.com/introduction)**, a modern Python AI agent framework. Documentation for LangChain and LangGraph integration will be added in future releases.
</Note>
## Core Concepts
### Agent Architecture with agno
IBM i agents built with agno follow a specialized architecture that combines:
<CardGroup cols={2}>
<Card title="Toolset Filtering" icon="filter">
Use FilteredMCPTools to limit agents to specific IBM i domains (performance, discovery, etc.)
</Card>
<Card title="Domain Specialization" icon="bullseye">
Create focused agents for specific IBM i administrative tasks and workflows
</Card>
<Card title="MCP Integration" icon="plug">
Connect to your IBM i MCP server with streamable HTTP transport for reliable tool access
</Card>
<Card title="Persistent Memory" icon="database">
Maintain conversation context and system knowledge across sessions
</Card>
</CardGroup>
### 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
```python
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
```python
# Filter tools by title content
title_filtered = FilteredMCPTools(
annotation_filters={
"title": lambda title: title and "system" in title.lower()
}
)
```
#### Combined Filters (AND logic)
```python
# 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
```python
# 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:
<Tabs>
<Tab title="Performance Agent">
**Toolset**: `performance`
**Focus**: System performance monitoring and resource analysis
```python
# 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.
</Tab>
<Tab title="Discovery Agent">
**Toolset**: `sysadmin_discovery`
**Focus**: High-level system service discovery and categorization
```python
# From create_sysadmin_discovery_agent()
discovery_tools = FilteredMCPTools(
url=mcp_url,
transport=transport,
annotation_filters={"toolsets": ["sysadmin_discovery"]}
)
agent = Agent(
name="IBM i SysAdmin Discovery",
instructions=[
"You help administrators get high-level overviews and summaries of system components.",
"Your discovery tools include:",
"- Service category listings and counts",
"- Schema-based service summaries",
"- SQL object type categorization"
],
tools=[discovery_tools]
)
```
**Use Case**: Getting inventory and understanding system service organization
</Tab>
<Tab title="Browse Agent">
**Toolset**: `sysadmin_browse`
**Focus**: Detailed exploration of system services
```python
# From create_sysadmin_browse_agent()
browse_tools = FilteredMCPTools(
url=mcp_url,
transport=transport,
annotation_filters={"toolsets": ["sysadmin_browse"]}
)
agent = Agent(
name="IBM i SysAdmin Browser",
instructions=[
"You help administrators explore and examine system services in detail.",
"Your browsing tools include:",
"- Listing services by specific categories",
"- Exploring services within specific schemas (QSYS2, SYSTOOLS, etc.)",
"- Filtering services by SQL object type (VIEW, PROCEDURE, FUNCTION, etc.)"
],
tools=[browse_tools]
)
```
**Use Case**: Deep-dive exploration of specific service categories or schemas
</Tab>
<Tab title="Search Agent">
**Toolset**: `sysadmin_search`
**Focus**: Finding specific services and examples
```python
# From create_sysadmin_search_agent()
search_tools = FilteredMCPTools(
url=mcp_url,
transport=transport,
annotation_filters={"toolsets": ["sysadmin_search"]}
)
agent = Agent(
name="IBM i SysAdmin Search",
instructions=[
"You help administrators find specific services, examples, and usage information.",
"Your search capabilities include:",
"- Case-insensitive service name searching",
"- Locating services across all schemas",
"- Searching example code and usage patterns"
],
tools=[search_tools]
)
```
**Use Case**: Targeted lookup of specific services or code examples
</Tab>
</Tabs>
### Multi-Agent Operating System
The `/agents/ibmi_agentos.py` example shows how to deploy multiple specialized agents using agno's `AgentOS`:
```python
# 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
```python
# 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
```python
# 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:
```python
# 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:
```python
# 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:
```python
# 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:
```bash
# 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:
```python
# 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:
```python
# 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
1. **Running MCP Server**: Complete the [Quick Start Guide](/quickstart)
2. **Python Environment**: Python 3.8+ with uv or pip
3. **Environment Configuration**: IBM i connection details
### Setup and Run
```bash
# 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
<Note>
**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.
</Note>
## Best Practices for IBM i Agents
<AccordionGroup>
<Accordion title="Toolset Design" icon="filter">
- **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
</Accordion>
<Accordion title="agno Integration Patterns" icon="cog">
- **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
</Accordion>
<Accordion title="IBM i Specialization" icon="server">
- **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
</Accordion>
<Accordion title="Production Deployment" icon="rocket">
- **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
</Accordion>
</AccordionGroup>
## Next Steps
<CardGroup cols={3}>
<Card title="Quick Start" icon="rocket" href="/quickstart">
Set up your IBM i MCP server with proper toolsets
</Card>
<Card title="SQL Tools Building" icon="database" href="/sql-tools/building-tools">
Understand the underlying tools that power agent capabilities
</Card>
<Card title="Configuration" icon="gear" href="/configuration">
Learn about MCP server configuration and toolset organization
</Card>
</CardGroup>
<Note>
**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.
</Note>
