connectivity-agent 0.1.7

An AI agent that diagnoses network connectivity issues using OpenAI's Responses API

Connectivity Agent

A demonstration project showing how to build a multi-tool AI Agent using OpenAI’s Responses API. Although intended as an example, it also works amazingly well for network connectivity checking.

Overview

The agent runs in a terminal. It chooses which network tools to use for your query, interprets their output, and explains the results in plain language.

The included tools are:

• ping
• curl
• netstat
• tracert
• nslookup
• ipconfig

Why This Example Might Be Useful

If you're learning the Responses API or experimenting with AI agents that use multiple tools, this example shows a simple pattern without extra framework code. The source is in a single file.

It is also a powerful diagnostic tool in its own right.

Example Queries

Basic Connectivity >> How is the connection to google?

Comprehensive Analysis >> Describe the connectivity to www.amazon.com. Be exhaustive.

Performance Comparison >> Compare response times between AWS on the East and West coast.

DNS Troubleshooting >> I can't reach example.com. Is it a DNS problem?

Local Network Diagnostics >> Show me my current network configuration and default gateway.

Port Analysis >> What services are currently listening on my machine?

Route Investigation >> Why might packets to cloudflare.com be taking an unusual path?

Multi-Protocol Testing >> Can I reach github.com? Check both ping and HTTP connectivity.

Security Assessment >> Are there any unexpected connections to external IP addresses?

Network Path Optimization >> Which endpoint has better routing from my location: https://www.nasa.gov or https://www.esa.int ?

Self Check >> Run a self-diagnostic.

Requirements

• Python 3.9 or higher
• OpenAI API Key

Installation

Installing from PyPI

Once published, you can install the package directly:

pip install connectivity-agent

Installing from Source

1. Clone the repository:

git clone https://github.com/brocla/connectivity_agent.git
cd connectivity_agent

2. Install the package:

pip install -e .

Or install the required dependencies manually:

pip install openai>=2.8.0

API Key Setup

The Connectivity Agent requires an OpenAI API key to function. You can obtain an API key from OpenAI's platform.

Setting Up Your API Key

You have two options for providing your API key:

Option 1: Environment Variable (Recommended)

Set the OPENAI_API_KEY environment variable:

On Windows:

setx OPENAI_API_KEY "your-api-key-here"

On Linux/Mac:

export OPENAI_API_KEY="your-api-key-here"

To make it permanent on Linux/Mac, add the export command to your ~/.bashrc or ~/.zshrc file.

Option 2: Direct Configuration

The OpenAI Python client will automatically look for the API key in the environment variable. Alternatively, you can modify the code to pass the key directly (not recommended for security reasons).

Usage

After installation and API key setup, run the agent:

If installed via pip:

connectivity-agent

If running from source:

python connectivity_agent.py

The agent will start an interactive REPL where you can ask connectivity-related questions.

Kudos

Thanks to Thomas Ptacek for his article You Should Write an Agent