Skip to content

Building AI agents, atomically

Update README

KennyVaneetvelde5a8aef08734b
diff --git a/atomic-examples/mcp-agent/README.md b/atomic-examples/mcp-agent/README.md
index 9142832..1a5216b 100644
--- a/atomic-examples/mcp-agent/README.md
+++ b/atomic-examples/mcp-agent/README.md
@@ -88,13 +88,64 @@ This example shows the flexibility of the MCP architecture with two distinct tra
## Example Queries
+The example includes a set of basic arithmetic tools that demonstrate the agent's capability to break down and solve complex mathematical expressions:
+
+### Available Demo Tools
+
+- **AddNumbers**: Adds two numbers together (number1 + number2)
+- **SubtractNumbers**: Subtracts the second number from the first (number1 - number2)
+- **MultiplyNumbers**: Multiplies two numbers together (number1 * number2)
+- **DivideNumbers**: Divides the first number by the second (handles division by zero)
+
+### Conversation Flow
+
+When you interact with the agent, it:
+
+1. Analyzes your input to break it down into sequential operations
+2. Selects appropriate tools for each operation
+3. Shows its reasoning for each tool selection
+4. Executes the tools in sequence
+5. Maintains context between operations to build up the final result
+
+For example, when calculating `(5-9)*0.123`:
+
+1. First uses `SubtractNumbers` to compute (5-9) = -4
+2. Then uses `MultiplyNumbers` to compute (-4 * 0.123) = -0.492
+3. Provides the final result with clear explanation
+
+For more complex expressions like `((4**3)-10)/100)**2`, the agent:
+
+1. Breaks down the expression into multiple steps
+2. Uses `MultiplyNumbers` repeatedly for exponentiation (4**3)
+3. Uses `SubtractNumbers` for the subtraction operation
+4. Uses `DivideNumbers` for division by 100
+5. Uses `MultiplyNumbers` again for the final squaring operation
+
+Each step in the conversation shows:
+- The tool being executed
+- The parameters being used
+- The intermediate result
+- The agent's reasoning for the next step
+
Try queries like:
-- "What is 2+2?"
-- "Please calculate the square root of 144"
-- "Can you tell me what time it is?"
-- "Generate a random number between 1 and 100"
-- "plz do the sum of (59-33) and (33*0.123) and then multiply that by 0.99, take that, and square it"
+```python
+# Simple arithmetic
+"What is 2+2?"
+# Uses AddNumbers tool directly
+
+# Complex expressions
+"(5-9)*0.123"
+# Uses SubtractNumbers followed by MultiplyNumbers
+
+# Multi-step calculations
+"((4**3)-10)/100)**2"
+# Uses multiple tools in sequence to break down the complex expression
+
+# Natural language queries
+"Calculate the difference between 50 and 23, then multiply it by 3"
+# Understands natural language and breaks it down into appropriate tool calls
+```
## Learn More
diff --git a/atomic-examples/mcp-agent/example-client/README.md b/atomic-examples/mcp-agent/example-client/README.md
deleted file mode 100644
index 12b2c23..0000000
--- a/atomic-examples/mcp-agent/example-client/README.md
+++ /dev/null
@@ -1,149 +0,0 @@
-# MCP Agent Example
-
-This example demonstrates how to build an interactive agent that intelligently selects and uses MCP tools based on user queries. It showcases:
-
-- Dynamic discovery of available MCP tools
-- Support for both STDIO and SSE transport methods
-- Intelligent tool selection using OpenAI models
-- Parameter extraction from natural language queries
-- Tool execution with extracted parameters
-- Pretty output formatting using Rich
-
-## Features
-
-- **Dual Transport Support**: Use either STDIO or SSE transport for communicating with MCP tools
-- **Tool Discovery**: Automatically fetches all available tools from the MCP server
-- **Smart Selection**: Uses LLMs to understand user queries and select the most appropriate tool
-- **Parameter Extraction**: Extracts tool parameters directly from natural language queries
-- **Interactive Chat**: Engage in a continuous conversation, with the agent selecting appropriate tools as needed
-- **Rich Output**: Beautiful console output with colors and tables
-
-## Setup
-
-1. Install dependencies:
- ```bash
- poetry install
- ```
-
-2. Set up your OpenAI API key in a `.env` file or as an environment variable:
- ```bash
- export OPENAI_API_KEY=your_api_key
- ```
-
-3. For SSE mode, ensure the MCP server is running at `http://localhost:6969` (default)
-
-4. For STDIO mode, no external server is needed, as the client will launch the appropriate process
-
-## Usage
-
-Run the example with the desired transport method:
-
-```bash
-# Default (STDIO mode)
-poetry run python -m example_client.main
-
-# Explicitly select STDIO mode
-poetry run python -m example_client.main --transport stdio
-
-# Use SSE mode instead
-poetry run python -m example_client.main --transport sse
-```
-
-The script will:
-1. Initialize the appropriate transport method (STDIO or SSE)
-2. Fetch all available MCP tools
-3. Display them in a table
-4. Start an interactive chat session
-5. Process your queries, selecting and executing the right tools
-6. Clean up resources when you exit
-
-## Transport Methods
-
-### STDIO Transport
-
-STDIO transport launches a local subprocess and communicates with it using standard input/output. This is useful for:
-
-- Local development without a separate server
-- Testing new tools
-- Offline usage scenarios
-
-Configuration is done in `main_stdio.py` via the `MCPConfig` class:
-```python
-@dataclass
-class MCPConfig:
- openai_model: str = "gpt-4o-mini"
- openai_api_key: str = os.getenv("OPENAI_API_KEY")
- mcp_stdio_server_command: str = "poetry run example-mcp-server --mode stdio"
-```
-
-### SSE Transport
-
-SSE (Server-Sent Events) transport connects to a remote HTTP server. This is useful for:
-
-- Production deployments
-- Sharing tools across multiple clients
-- Centralized tool management
-
-Configuration is done in `main_sse.py` via the `MCPConfig` class:
-```python
-@dataclass
-class MCPConfig:
- mcp_server_url: str = "http://localhost:6969"
- openai_model: str = "gpt-4o-mini"
- openai_api_key: str = os.getenv("OPENAI_API_KEY")
-```
-
-## Agent Logic
-
-The agent uses several key components:
-
-1. **Orchestrator Agent**: Analyzes queries and determines which tool to use or when to provide a direct response
-2. **Tool Factory**: Fetches and instantiates appropriate tool classes
-3. **Memory**: Maintains conversation history for context-aware responses
-4. **System Prompt Generator**: Creates optimized prompts for the LLM
-
-## Interactive Chat
-
-During the interactive session, you can:
-
-- Ask natural language questions
-- Request specific calculations or operations
-- Get direct answers for simple queries
-- See which tools are being selected and why
-- Exit by typing 'exit' or 'quit'
-
-## Example Queries
-
-Try queries like:
-
-- "What is 2+2?"
-- "Please calculate the square root of 144"
-- "Can you tell me what time it is?"
-- "Generate a random number between 1 and 100"
-- "plz do the sum of (59-33) and (33*0.123) and then multiply that by 0.99, take that, and square it"
-
-## Extending
-
-To extend this example:
-
-1. Add new tools to your MCP server
-2. Configure either the STDIO command or SSE server URL in the config
-3. Customize the agent's system prompt in the `SystemPromptGenerator`
-
-## Requirements
-
-- Python 3.9+
-- OpenAI API key
-- Poetry for dependency management
-- For SSE mode: MCP server running at configured URL (default: http://localhost:6969)
-
-## Code Structure
-
-- `main.py`: Entry point that parses arguments and selects the appropriate transport
-- `main_stdio.py`: Implementation using STDIO transport
-- `main_sse.py`: Implementation using SSE transport
-- `example-mcp-server/`: Example server implementation
-
----
-
-**This example is intended for educational and demonstration purposes.**