Cognitive API Agent

A sophisticated AI-powered application that serves as a natural language interface for any modern web API. It reasons, clarifies, and executes commands, turning complex technical interactions into simple conversations.

How It Works in 30 Seconds

1. Provide an API URL. The agent reads its documentation instantly.

2. Chat Your Command in plain English (e.g., "Create a new user named Virat").

3. The Agent Thinks, asks for missing details, and shows its plan for you to approve.

4. Confirm & Execute. With your approval, the agent performs the action.

Setup Guide: From Zero to Running

1

Prerequisites

Ensure you have Python (3.8+) and a virtual environment tool (like `venv`) installed on your system.

2

Create Project Structure

Organize your project folder as shown. This separation of concerns is key to a maintainable application.

/YourProject/
├── app.py
├── .env
├── requirements.txt
└── /src
    ├── __init__.py
    ├── api_client.py
    ├── llm_agent.py
    └── tools.py

3

Install Dependencies

Create `requirements.txt` with the content below, then run the installation command from your terminal.

streamlit
pydantic
pydantic-ai
python-dotenv
httpx
pandas
openai

pip install -r requirements.txt

4

Set Your API Key

Create a `.env` file in the root folder and add your secret OpenAI API key. This keeps your key secure and out of the code.

OPENAI_API_KEY="sk-YourSecretKeyGoesHere"

5

Populate the Code

Copy the code from the "Code Details" section below into their respective files (`app.py`, `src/api_client.py`, etc.).

6

Launch the Agent

Run the application from your terminal. Your browser should open with the chat interface, ready for your commands.

streamlit run app.py

System Architecture & Workflow

The application follows a robust, decision-driven workflow. Click each step to see how a user's request is intelligently processed.

The Cognitive Agent's Brain

The agent's intelligence is defined by a powerful **System Prompt** that forces it to make a logical choice. It doesn't just respond; it decides on a structured action.

Core Instruction

"If the request is INCOMPLETE, you MUST respond with a `Question` object. If the request is COMPLETE, you MUST respond with an `APIRequest` object. Never make up data."

This mandatory choice between asking for more information or formulating a complete API call is the key to the agent's reliability and intelligence.