README_AGENTS.md

# Network Infrastructure AI Assistant

This project implements an AI-powered network infrastructure assistant with specialized port recommendation capabilities using the OpenAI Agents SDK.

## Architecture Overview

The system follows a modular architecture based on the OpenAI Agents SDK:

### Core Components

1. **`retriever_tool.py`** - Network information retrieval tool
   - Uses FAISS vector database for semantic search
   - Searches through network documentation and device configurations
   - Returns relevant network information with similarity scores

2. **`port_recommnedations.py`** - Specialized port recommendations agent
   - Expert agent focused on port/interface recommendations
   - Understands MLAG configurations and redundancy requirements
   - Provides specific device names and port numbers

3. **`app.py`** - Main orchestrator application
   - Combines retrieval tool and port recommendations agent
   - Provides Gradio web interface
   - Routes queries to appropriate tools based on context

4. **`port_recommendations_standalone.py`** - Standalone port recommendations
   - Direct access to port recommendations agent
   - Useful for testing and scripting

## Key Features

### Port Recommendations
- Automatic redundancy across MLAG pairs (leaf01/leaf02, leaf03/leaf04, etc.)
- Same port numbers across paired devices when possible
- Support for single port requests (without redundancy)
- Detailed responses with device names and specific port identifiers

### Network Information Retrieval
- Semantic search through network documentation
- Device-specific configuration lookup
- Fabric-wide information queries

## Usage Examples

### Port Recommendations
```python
# Various ways to request ports
"I need an unused port"                                    # Returns 2 ports with redundancy
"I need an unused port without redundancy"                 # Returns 1 port
"I need to dual connect a server to the network"          # Returns MLAG pair
"What ports are available on leaf01?"                     # Device-specific query
```

### General Network Queries
```python
"What is the BGP configuration?"
"Show me the VLAN settings"
"What's the loopback pool configuration?"
```

## Running the System

### Web Interface
```bash
python app.py
```
This launches a Gradio web interface where you can ask questions about the network infrastructure.

### Standalone Port Recommendations
```bash
python port_recommendations_standalone.py
```
This runs a test suite with various port recommendation queries.

### Testing Individual Components
```python
from port_recommnedations import port_recommendations_agent
from retriever_tool import retrieve_network_information

# Test retrieval tool
result = retrieve_network_information("unused ports")

# Test port agent (requires async)
import asyncio
from agents import Runner

async def test():
    result = await Runner.run(port_recommendations_agent, "I need a port")
    print(result.final_output)

asyncio.run(test())
```

## File Structure

```
agent-sdk/
├── retriever_tool.py                 # Network information retrieval
├── port_recommnedations.py           # Specialized port agent
├── app.py                            # Main orchestrator with Gradio UI
├── port_recommendations_standalone.py # Standalone port recommendations
├── faiss_index/                      # Vector database
├── prompts.yaml                      # Prompt templates
└── README_AGENTS.md                  # This file
```

## Dependencies

- `openai-agents`: OpenAI Agents SDK
- `langchain-community`: FAISS and embeddings
- `sentence-transformers`: Text embeddings
- `gradio`: Web interface
- `PyYAML`: Configuration files

## Agent Design Principles

Based on the OpenAI Agents SDK documentation:

1. **Function Tools**: The retriever uses `@function_tool` decorator for automatic tool setup
2. **Agents as Tools**: Port recommendations agent is used as a tool in the main orchestrator
3. **Specialized Instructions**: Each agent has domain-specific instructions and behaviors
4. **Tool Routing**: Main agent routes queries to appropriate specialized tools

## Port Recommendation Rules

The port recommendations agent follows these key rules:

1. **Default Redundancy**: Always recommend two ports across different devices unless specifically requested otherwise
2. **MLAG Pairing**: Recommend ports across MLAG pairs (odd/even leaf switches)
3. **Port Alignment**: Try to use the same port number across paired devices
4. **Specific Responses**: Include device names and exact port identifiers
5. **Query First**: Will return only data from the leaf switches

## Future Enhancements

- Add more specialized agents (security policies, VLAN management, etc.)
- Implement caching for frequently requested information
- Add support for configuration changes and validation
- Integrate with network management systems