# aw-agents
**AI Agents for Agentic Workflows** - Easily deploy AI agents to multiple chatbot platforms (Claude, ChatGPT, and more).
## Overview
`aw-agents` provides a unified framework for building AI agents and deploying them to different chatbot platforms with minimal boilerplate. Write your agent once, deploy everywhere.
### Key Features
- 🎯 **Write Once, Deploy Everywhere**: Single agent implementation works with Claude, ChatGPT, and future platforms
- 🔌 **Pluggable Adapters**: MCP for Claude, OpenAPI for ChatGPT
- 📦 **Batteries Included**: Built-in download agent with smart features
- 🛠️ **Easy to Extend**: Simple base class for creating new agents
- 🎨 **Clean Architecture**: Separation of agent logic and platform adapters
## Installation
```bash
# From source (recommended for development)
git clone https://github.com/thorwhalen/aw_agents.git
cd aw_agents
pip install -e .
# With Claude Desktop support (MCP)
pip install -e .[mcp]
# With ChatGPT Custom GPT support (FastAPI)
pip install -e .[api]
# With all features
pip install -e .[all]
# For development
pip install -e .[dev]
```
### Verify Installation
```bash
# Test the installation
python -c "from aw_agents.download import DownloadAgent; agent = DownloadAgent(); print('✓ Installation successful!')"
```
## Quick Start
### Using the Download Agent
The package includes a smart download agent out of the box:
```python
from aw_agents.download import DownloadAgent
agent = DownloadAgent()
# Get available tools
tools = agent.get_tools()
print([t['name'] for t in tools])
# ['download_content', 'download_multiple', 'list_downloads']
# Execute a tool
result = agent.execute_tool('download_content', {
'url': 'https://arxiv.org/pdf/2103.00020.pdf',
'context': 'Important ML Paper'
})
print(result['data']['path']) # ~/Downloads/Important_ML_Paper.pdf
```
### Deploy to Claude Desktop (MCP)
**Step 1: Create MCP Server Script**
```python
from aw_agents.download import DownloadAgent
from aw_agents.adapters import MCPAdapter
agent = DownloadAgent()
adapter = MCPAdapter(agent, "download-agent")
# This starts an MCP server for Claude Desktop
if __name__ == "__main__":
adapter.run_sync()
```
Save this as `mcp_download.py` or use the deployment script:
```bash
python scripts/deploy_mcp.py DownloadAgent --output mcp_download.py
```
**Step 2: Configure Claude Desktop**
Edit your Claude Desktop config file:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
Add this configuration:
```json
{
"mcpServers": {
"download": {
"command": "python",
"args": ["/absolute/path/to/mcp_download.py"]
}
}
}
```
**Important**: Use the absolute path to your script, not `~/` or relative paths.
**Step 3: Restart Claude Desktop**
Completely quit and restart Claude Desktop.
**Step 4: Test It**
Ask Claude:
```
Download this paper for me: https://arxiv.org/pdf/2103.00020.pdf
Context: "Attention is All You Need"
```
**Troubleshooting**:
- Check logs: `~/Library/Logs/Claude/` (macOS)
- Verify Python path in config
- Ensure dependencies are installed in the correct Python environment
### Deploy to ChatGPT Custom GPT (FastAPI)
**Step 1: Create and Start API Server**
```python
from aw_agents.download import DownloadAgent
from aw_agents.adapters import OpenAPIAdapter
agent = DownloadAgent()
adapter = OpenAPIAdapter(agent, title="Download Agent API")
# This starts a FastAPI server
if __name__ == "__main__":
adapter.run(port=8000)
```
Save this as `api_download.py` or use the deployment script:
```bash
python scripts/deploy_api.py DownloadAgent --output api_download.py
python api_download.py # Start the server
```
The server will be available at http://localhost:8000
**Step 2: Create Custom GPT**
1. Go to https://chat.openai.com/gpts/editor
2. Click "Create a GPT"
3. Name it (e.g., "Download Assistant")
4. Add instructions:
```
You help users download files from URLs. Use the download_content
action when users provide URLs. Always ask for context to generate
good filenames. You can download multiple files at once and list
previously downloaded files.
```
**Step 3: Add Actions**
1. In the GPT editor, go to "Configure" → "Actions"
2. Click "Create new action"
3. Import schema from: `http://localhost:8000/openapi.json`
4. Click "Add Action"
**Step 4: Test Your GPT**
Ask your Custom GPT:
```
Download this dataset: https://github.com/user/repo/blob/main/data.csv
Context: "Sales Data Q4"
```
**Important Notes**:
- **Local Testing**: ChatGPT servers can't access `localhost` from OpenAI's infrastructure
- **For Remote Access**:
- Use ngrok: `ngrok http 8000` (provides a public URL)
- Deploy to cloud service (AWS, GCP, Azure, Heroku)
- Use local network IP if on the same network
**Production Deployment**:
1. Deploy to cloud service with HTTPS
2. Add authentication (API keys, OAuth)
3. Update Custom GPT actions with public URL
## Architecture
```
aw_agents/
├── base.py # AgentBase, ToolExecutionResult
├── adapters/
│ ├── mcp.py # MCPAdapter for Claude
│ └── openapi.py # OpenAPIAdapter for ChatGPT
└── download/ # Download agent implementation
├── agent.py # DownloadAgent (AgentBase subclass)
└── download_core.py # Core download logic
```
### Creating Your Own Agent
```python
from aw_agents.base import AgentBase, ToolExecutionResult, create_json_schema
class MyAgent(AgentBase):
"""My custom agent."""
def get_tools(self):
return [
{
'name': 'my_tool',
'description': 'Does something useful',
'parameters': create_json_schema(
properties={
'input': {
'type': 'string',
'description': 'Input text'
}
},
required=['input']
)
}
]
def execute_tool(self, name, arguments):
if name == 'my_tool':
# Your logic here
result = self._process(arguments['input'])
return ToolExecutionResult.success_result(
data={'output': result},
message="Processed successfully"
).to_dict()
return ToolExecutionResult.error_result(
message=f"Unknown tool: {name}"
).to_dict()
def _process(self, input_text):
# Your implementation
return input_text.upper()
```
Then deploy it:
```python
# For Claude
from aw_agents.adapters import MCPAdapter
adapter = MCPAdapter(MyAgent(), "my-agent")
adapter.run_sync()
# For ChatGPT
from aw_agents.adapters import OpenAPIAdapter
adapter = OpenAPIAdapter(MyAgent())
adapter.run(port=8001)
```
## Included Agents
### Download Agent
Smart content downloader with:
- **Landing page detection**: Automatically finds actual download links
- **Context-aware file naming**: Uses conversation context for meaningful filenames
- **Special handling for**:
- GitHub (converts blob URLs to raw)
- HuggingFace (handles dataset downloads)
- Kaggle datasets
- Academic papers (arXiv, etc.)
- **Support for**: PDFs, datasets, CSV, JSON, and more
**Tools:**
- `download_content` - Download a single URL with smart handling
- `download_multiple` - Download multiple URLs at once
- `list_downloads` - List downloaded files
**Examples:**
```python
from aw_agents.download import DownloadAgent
agent = DownloadAgent()
# Download with context-aware naming
result = agent.execute_tool('download_content', {
'url': 'https://github.com/user/repo/blob/main/data.csv',
'context': 'Dataset for analysis'
})
# Automatically converts to raw.githubusercontent.com
# Saves as: Dataset_for_analysis.csv
# Download multiple files
result = agent.execute_tool('download_multiple', {
'urls': [
'https://arxiv.org/pdf/2103.00020.pdf',
'https://arxiv.org/pdf/1706.03762.pdf'
],
'contexts': [
'Attention Paper',
'Transformer Original'
]
})
# List downloaded PDFs
result = agent.execute_tool('list_downloads', {
'pattern': '*.pdf'
})
```
**Smart Features:**
1. **Landing Page Detection**:
```python
# Input: Landing page URL
agent.execute_tool('download_content', {
'url': 'https://papers.nips.cc/paper/2017/hash/xxx-Abstract.html'
})
# Agent detects HTML, finds PDF link, downloads PDF, warns about redirect
```
2. **GitHub URL Handling**:
```python
# Input: GitHub blob URL
'https://github.com/user/repo/blob/main/data.csv'
# Converts to:
'https://raw.githubusercontent.com/user/repo/main/data.csv'
```
3. **Context-Aware Naming**:
```python
# Without context:
# Filename: 2103.00020.pdf
# With context:
agent.execute_tool('download_content', {
'url': 'https://arxiv.org/pdf/2103.00020.pdf',
'context': 'Attention is All You Need - Transformer Paper'
})
# Filename: Attention_is_All_You_Need_Transformer_Paper.pdf
```
## Integration Guides
### Claude Desktop Integration
1. Create MCP server script:
```bash
python scripts/deploy_mcp.py DownloadAgent --output ~/mcp_download.py
```
2. Edit Claude Desktop config:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
3. Add to config:
```json
{
"mcpServers": {
"download": {
"command": "python",
"args": ["/absolute/path/to/mcp_download.py"]
}
}
}
```
4. Restart Claude Desktop
**Usage Examples in Claude:**
```
Download this paper: https://arxiv.org/pdf/2103.00020.pdf
Context: "Attention is All You Need paper"
I need these papers:
1. https://arxiv.org/pdf/2103.00020.pdf - "Attention Paper"
2. https://arxiv.org/pdf/1706.03762.pdf - "Transformer Original"
Show me what PDFs I've downloaded
```
### ChatGPT Custom GPT Integration
1. Create API server script:
```bash
python scripts/deploy_api.py DownloadAgent --output ~/api_download.py
python ~/api_download.py
```
2. Create Custom GPT at https://chat.openai.com/gpts/editor
3. Add actions using schema from: `http://localhost:8000/openapi.json`
4. For remote access, deploy to cloud or use ngrok:
```bash
ngrok http 8000
```
**Usage Examples in ChatGPT:**
```
Download this dataset: https://github.com/user/repo/blob/main/data.csv
Context: "Sales Data Q4 2024"
Can you download these research papers for me?
[List of URLs with contexts]
```
## Troubleshooting
### Installation Issues
**Problem**: Module not found errors
**Solution**:
```bash
# Update pip and reinstall
pip install --upgrade pip
pip uninstall aw-agents
pip install -e .[all]
```
**Problem**: Missing dependencies
**Solution**:
```bash
# Install specific feature sets
pip install -e .[mcp] # For Claude
pip install -e .[api] # For ChatGPT
pip install -e .[all] # Everything
```
### Claude Desktop Issues
**Problem**: Claude doesn't see the download tools
**Solution**:
1. Verify config file location (see paths above)
2. Use absolute path in config (not `~/` or `./`)
3. Check logs: `~/Library/Logs/Claude/` (macOS)
4. Restart Claude Desktop completely (Quit, not just close window)
5. Verify Python environment: `which python`
**Problem**: "Module not found" when Claude tries to use agent
**Solution**:
```bash
# Install in the Python environment Claude uses
which python # Check which Python Claude is using
# Use that Python to install dependencies
/path/to/python -m pip install mcp requests beautifulsoup4 graze
```
### ChatGPT Custom GPT Issues
**Problem**: Actions can't connect to localhost
**Solution**:
- ChatGPT servers can't access `localhost` from OpenAI's infrastructure
- Options:
1. **For testing**: Use ngrok to expose local server
```bash
ngrok http 8000
# Use the ngrok URL in your Custom GPT actions
```
2. **For production**: Deploy to cloud service (AWS, GCP, Azure, Heroku)
3. **Same network**: Use your local IP address
**Problem**: Schema import fails
**Solution**:
1. Ensure server is running: `curl http://localhost:8000/openapi.json`
2. Check for CORS issues (FastAPI handles this by default)
3. Try manual schema paste instead of URL import
### General Issues
**Problem**: Downloads failing
**Solution**:
1. Check internet connection
2. Verify URL is accessible: `curl -I [URL]`
3. Some sites may block automated downloads
4. Check download directory permissions
**Problem**: Import errors in Python
**Solution**:
```bash
# Verify installation
python -c "from aw_agents.download import DownloadAgent; print('✓ Success')"
# Reinstall if needed
pip install -e .[all]
```
## Development
### Running Tests
```bash
pytest
```
### Code Quality
```bash
# Format code
black aw_agents tests
# Lint
ruff aw_agents tests
# Type check
mypy aw_agents
```
### Adding a New Agent
1. Create a new directory in `aw_agents/`:
```
aw_agents/myagent/
├── __init__.py
├── agent.py
└── core.py (if needed)
```
2. Implement `AgentBase` in `agent.py`
3. Add to `aw_agents/__init__.py`:
```python
from aw_agents.myagent import MyAgent
__all__.append('MyAgent')
```
4. Create tests in `tests/test_myagent.py`
5. Update documentation
## Roadmap
- [ ] Additional built-in agents (research, data prep, etc.)
- [ ] Support for more platforms (Slack, Discord, etc.)
- [ ] Agent composition and chaining
- [ ] Persistent state management
- [ ] Authentication and authorization
- [ ] Web UI for agent management
- [ ] CLI tools for deployment
## Contributing
Contributions welcome! Please:
1. Fork the repo
2. Create a feature branch
3. Add tests for new features
4. Ensure all tests pass
5. Submit a pull request
## License
MIT License - see LICENSE file for details
## Credits
Built with:
- [dol](https://github.com/i2mint/dol) - Storage abstractions
- [graze](https://github.com/thorwhalen/graze) - Download and caching
- [MCP](https://modelcontextprotocol.io/) - Model Context Protocol
- [FastAPI](https://fastapi.tiangolo.com/) - Modern web framework
Part of the [thorwhalen](https://github.com/thorwhalen) ecosystem.
Raw data
{
"_id": null,
"home_page": "https://github.com/thorwhalen/aw_agents",
"name": "aw-agents",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "ai, agents, chatbots, mcp, openapi, claude, chatgpt",
"author": "Thor Whalen",
"author_email": "Your Name <your.email@example.com>",
"download_url": "https://files.pythonhosted.org/packages/05/72/6792bca29c598111ffecce304d11ae046124f5fa989fdd42e9fff04ca759/aw_agents-0.1.0.tar.gz",
"platform": "any",
"description": "# aw-agents\n\n**AI Agents for Agentic Workflows** - Easily deploy AI agents to multiple chatbot platforms (Claude, ChatGPT, and more).\n\n## Overview\n\n`aw-agents` provides a unified framework for building AI agents and deploying them to different chatbot platforms with minimal boilerplate. Write your agent once, deploy everywhere.\n\n### Key Features\n\n- \ud83c\udfaf **Write Once, Deploy Everywhere**: Single agent implementation works with Claude, ChatGPT, and future platforms\n- \ud83d\udd0c **Pluggable Adapters**: MCP for Claude, OpenAPI for ChatGPT\n- \ud83d\udce6 **Batteries Included**: Built-in download agent with smart features\n- \ud83d\udee0\ufe0f **Easy to Extend**: Simple base class for creating new agents\n- \ud83c\udfa8 **Clean Architecture**: Separation of agent logic and platform adapters\n\n## Installation\n\n```bash\n# From source (recommended for development)\ngit clone https://github.com/thorwhalen/aw_agents.git\ncd aw_agents\npip install -e .\n\n# With Claude Desktop support (MCP)\npip install -e .[mcp]\n\n# With ChatGPT Custom GPT support (FastAPI)\npip install -e .[api]\n\n# With all features\npip install -e .[all]\n\n# For development\npip install -e .[dev]\n```\n\n### Verify Installation\n\n```bash\n# Test the installation\npython -c \"from aw_agents.download import DownloadAgent; agent = DownloadAgent(); print('\u2713 Installation successful!')\"\n```\n\n## Quick Start\n\n### Using the Download Agent\n\nThe package includes a smart download agent out of the box:\n\n```python\nfrom aw_agents.download import DownloadAgent\n\nagent = DownloadAgent()\n\n# Get available tools\ntools = agent.get_tools()\nprint([t['name'] for t in tools])\n# ['download_content', 'download_multiple', 'list_downloads']\n\n# Execute a tool\nresult = agent.execute_tool('download_content', {\n 'url': 'https://arxiv.org/pdf/2103.00020.pdf',\n 'context': 'Important ML Paper'\n})\n\nprint(result['data']['path']) # ~/Downloads/Important_ML_Paper.pdf\n```\n\n### Deploy to Claude Desktop (MCP)\n\n**Step 1: Create MCP Server Script**\n\n```python\nfrom aw_agents.download import DownloadAgent\nfrom aw_agents.adapters import MCPAdapter\n\nagent = DownloadAgent()\nadapter = MCPAdapter(agent, \"download-agent\")\n\n# This starts an MCP server for Claude Desktop\nif __name__ == \"__main__\":\n adapter.run_sync()\n```\n\nSave this as `mcp_download.py` or use the deployment script:\n\n```bash\npython scripts/deploy_mcp.py DownloadAgent --output mcp_download.py\n```\n\n**Step 2: Configure Claude Desktop**\n\nEdit your Claude Desktop config file:\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\nAdd this configuration:\n```json\n{\n \"mcpServers\": {\n \"download\": {\n \"command\": \"python\",\n \"args\": [\"/absolute/path/to/mcp_download.py\"]\n }\n }\n}\n```\n\n**Important**: Use the absolute path to your script, not `~/` or relative paths.\n\n**Step 3: Restart Claude Desktop**\n\nCompletely quit and restart Claude Desktop.\n\n**Step 4: Test It**\n\nAsk Claude:\n```\nDownload this paper for me: https://arxiv.org/pdf/2103.00020.pdf\nContext: \"Attention is All You Need\"\n```\n\n**Troubleshooting**:\n- Check logs: `~/Library/Logs/Claude/` (macOS)\n- Verify Python path in config\n- Ensure dependencies are installed in the correct Python environment\n\n### Deploy to ChatGPT Custom GPT (FastAPI)\n\n**Step 1: Create and Start API Server**\n\n```python\nfrom aw_agents.download import DownloadAgent\nfrom aw_agents.adapters import OpenAPIAdapter\n\nagent = DownloadAgent()\nadapter = OpenAPIAdapter(agent, title=\"Download Agent API\")\n\n# This starts a FastAPI server\nif __name__ == \"__main__\":\n adapter.run(port=8000)\n```\n\nSave this as `api_download.py` or use the deployment script:\n\n```bash\npython scripts/deploy_api.py DownloadAgent --output api_download.py\npython api_download.py # Start the server\n```\n\nThe server will be available at http://localhost:8000\n\n**Step 2: Create Custom GPT**\n\n1. Go to https://chat.openai.com/gpts/editor\n2. Click \"Create a GPT\"\n3. Name it (e.g., \"Download Assistant\")\n4. Add instructions:\n ```\n You help users download files from URLs. Use the download_content \n action when users provide URLs. Always ask for context to generate \n good filenames. You can download multiple files at once and list \n previously downloaded files.\n ```\n\n**Step 3: Add Actions**\n\n1. In the GPT editor, go to \"Configure\" \u2192 \"Actions\"\n2. Click \"Create new action\"\n3. Import schema from: `http://localhost:8000/openapi.json`\n4. Click \"Add Action\"\n\n**Step 4: Test Your GPT**\n\nAsk your Custom GPT:\n```\nDownload this dataset: https://github.com/user/repo/blob/main/data.csv\nContext: \"Sales Data Q4\"\n```\n\n**Important Notes**:\n- **Local Testing**: ChatGPT servers can't access `localhost` from OpenAI's infrastructure\n- **For Remote Access**: \n - Use ngrok: `ngrok http 8000` (provides a public URL)\n - Deploy to cloud service (AWS, GCP, Azure, Heroku)\n - Use local network IP if on the same network\n\n**Production Deployment**:\n1. Deploy to cloud service with HTTPS\n2. Add authentication (API keys, OAuth)\n3. Update Custom GPT actions with public URL\n\n## Architecture\n\n```\naw_agents/\n\u251c\u2500\u2500 base.py # AgentBase, ToolExecutionResult\n\u251c\u2500\u2500 adapters/\n\u2502 \u251c\u2500\u2500 mcp.py # MCPAdapter for Claude\n\u2502 \u2514\u2500\u2500 openapi.py # OpenAPIAdapter for ChatGPT\n\u2514\u2500\u2500 download/ # Download agent implementation\n \u251c\u2500\u2500 agent.py # DownloadAgent (AgentBase subclass)\n \u2514\u2500\u2500 download_core.py # Core download logic\n```\n\n### Creating Your Own Agent\n\n```python\nfrom aw_agents.base import AgentBase, ToolExecutionResult, create_json_schema\n\nclass MyAgent(AgentBase):\n \"\"\"My custom agent.\"\"\"\n \n def get_tools(self):\n return [\n {\n 'name': 'my_tool',\n 'description': 'Does something useful',\n 'parameters': create_json_schema(\n properties={\n 'input': {\n 'type': 'string',\n 'description': 'Input text'\n }\n },\n required=['input']\n )\n }\n ]\n \n def execute_tool(self, name, arguments):\n if name == 'my_tool':\n # Your logic here\n result = self._process(arguments['input'])\n \n return ToolExecutionResult.success_result(\n data={'output': result},\n message=\"Processed successfully\"\n ).to_dict()\n \n return ToolExecutionResult.error_result(\n message=f\"Unknown tool: {name}\"\n ).to_dict()\n \n def _process(self, input_text):\n # Your implementation\n return input_text.upper()\n```\n\nThen deploy it:\n\n```python\n# For Claude\nfrom aw_agents.adapters import MCPAdapter\nadapter = MCPAdapter(MyAgent(), \"my-agent\")\nadapter.run_sync()\n\n# For ChatGPT\nfrom aw_agents.adapters import OpenAPIAdapter\nadapter = OpenAPIAdapter(MyAgent())\nadapter.run(port=8001)\n```\n\n## Included Agents\n\n### Download Agent\n\nSmart content downloader with:\n- **Landing page detection**: Automatically finds actual download links\n- **Context-aware file naming**: Uses conversation context for meaningful filenames\n- **Special handling for**:\n - GitHub (converts blob URLs to raw)\n - HuggingFace (handles dataset downloads)\n - Kaggle datasets\n - Academic papers (arXiv, etc.)\n- **Support for**: PDFs, datasets, CSV, JSON, and more\n\n**Tools:**\n- `download_content` - Download a single URL with smart handling\n- `download_multiple` - Download multiple URLs at once\n- `list_downloads` - List downloaded files\n\n**Examples:**\n\n```python\nfrom aw_agents.download import DownloadAgent\n\nagent = DownloadAgent()\n\n# Download with context-aware naming\nresult = agent.execute_tool('download_content', {\n 'url': 'https://github.com/user/repo/blob/main/data.csv',\n 'context': 'Dataset for analysis'\n})\n# Automatically converts to raw.githubusercontent.com\n# Saves as: Dataset_for_analysis.csv\n\n# Download multiple files\nresult = agent.execute_tool('download_multiple', {\n 'urls': [\n 'https://arxiv.org/pdf/2103.00020.pdf',\n 'https://arxiv.org/pdf/1706.03762.pdf'\n ],\n 'contexts': [\n 'Attention Paper',\n 'Transformer Original'\n ]\n})\n\n# List downloaded PDFs\nresult = agent.execute_tool('list_downloads', {\n 'pattern': '*.pdf'\n})\n```\n\n**Smart Features:**\n\n1. **Landing Page Detection**:\n ```python\n # Input: Landing page URL\n agent.execute_tool('download_content', {\n 'url': 'https://papers.nips.cc/paper/2017/hash/xxx-Abstract.html'\n })\n # Agent detects HTML, finds PDF link, downloads PDF, warns about redirect\n ```\n\n2. **GitHub URL Handling**:\n ```python\n # Input: GitHub blob URL\n 'https://github.com/user/repo/blob/main/data.csv'\n # Converts to: \n 'https://raw.githubusercontent.com/user/repo/main/data.csv'\n ```\n\n3. **Context-Aware Naming**:\n ```python\n # Without context:\n # Filename: 2103.00020.pdf\n \n # With context:\n agent.execute_tool('download_content', {\n 'url': 'https://arxiv.org/pdf/2103.00020.pdf',\n 'context': 'Attention is All You Need - Transformer Paper'\n })\n # Filename: Attention_is_All_You_Need_Transformer_Paper.pdf\n ```\n\n## Integration Guides\n\n### Claude Desktop Integration\n\n1. Create MCP server script:\n ```bash\n python scripts/deploy_mcp.py DownloadAgent --output ~/mcp_download.py\n ```\n\n2. Edit Claude Desktop config:\n - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n - **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n - **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n3. Add to config:\n ```json\n {\n \"mcpServers\": {\n \"download\": {\n \"command\": \"python\",\n \"args\": [\"/absolute/path/to/mcp_download.py\"]\n }\n }\n }\n ```\n\n4. Restart Claude Desktop\n\n**Usage Examples in Claude:**\n\n```\nDownload this paper: https://arxiv.org/pdf/2103.00020.pdf\nContext: \"Attention is All You Need paper\"\n\nI need these papers:\n1. https://arxiv.org/pdf/2103.00020.pdf - \"Attention Paper\"\n2. https://arxiv.org/pdf/1706.03762.pdf - \"Transformer Original\"\n\nShow me what PDFs I've downloaded\n```\n\n### ChatGPT Custom GPT Integration\n\n1. Create API server script:\n ```bash\n python scripts/deploy_api.py DownloadAgent --output ~/api_download.py\n python ~/api_download.py\n ```\n\n2. Create Custom GPT at https://chat.openai.com/gpts/editor\n\n3. Add actions using schema from: `http://localhost:8000/openapi.json`\n\n4. For remote access, deploy to cloud or use ngrok:\n ```bash\n ngrok http 8000\n ```\n\n**Usage Examples in ChatGPT:**\n\n```\nDownload this dataset: https://github.com/user/repo/blob/main/data.csv\nContext: \"Sales Data Q4 2024\"\n\nCan you download these research papers for me?\n[List of URLs with contexts]\n```\n\n## Troubleshooting\n\n### Installation Issues\n\n**Problem**: Module not found errors\n\n**Solution**:\n```bash\n# Update pip and reinstall\npip install --upgrade pip\npip uninstall aw-agents\npip install -e .[all]\n```\n\n**Problem**: Missing dependencies\n\n**Solution**:\n```bash\n# Install specific feature sets\npip install -e .[mcp] # For Claude\npip install -e .[api] # For ChatGPT\npip install -e .[all] # Everything\n```\n\n### Claude Desktop Issues\n\n**Problem**: Claude doesn't see the download tools\n\n**Solution**:\n1. Verify config file location (see paths above)\n2. Use absolute path in config (not `~/` or `./`)\n3. Check logs: `~/Library/Logs/Claude/` (macOS)\n4. Restart Claude Desktop completely (Quit, not just close window)\n5. Verify Python environment: `which python`\n\n**Problem**: \"Module not found\" when Claude tries to use agent\n\n**Solution**:\n```bash\n# Install in the Python environment Claude uses\nwhich python # Check which Python Claude is using\n# Use that Python to install dependencies\n/path/to/python -m pip install mcp requests beautifulsoup4 graze\n```\n\n### ChatGPT Custom GPT Issues\n\n**Problem**: Actions can't connect to localhost\n\n**Solution**:\n- ChatGPT servers can't access `localhost` from OpenAI's infrastructure\n- Options:\n 1. **For testing**: Use ngrok to expose local server\n ```bash\n ngrok http 8000\n # Use the ngrok URL in your Custom GPT actions\n ```\n 2. **For production**: Deploy to cloud service (AWS, GCP, Azure, Heroku)\n 3. **Same network**: Use your local IP address\n\n**Problem**: Schema import fails\n\n**Solution**:\n1. Ensure server is running: `curl http://localhost:8000/openapi.json`\n2. Check for CORS issues (FastAPI handles this by default)\n3. Try manual schema paste instead of URL import\n\n### General Issues\n\n**Problem**: Downloads failing\n\n**Solution**:\n1. Check internet connection\n2. Verify URL is accessible: `curl -I [URL]`\n3. Some sites may block automated downloads\n4. Check download directory permissions\n\n**Problem**: Import errors in Python\n\n**Solution**:\n```bash\n# Verify installation\npython -c \"from aw_agents.download import DownloadAgent; print('\u2713 Success')\"\n\n# Reinstall if needed\npip install -e .[all]\n```\n\n## Development\n\n### Running Tests\n\n```bash\npytest\n```\n\n### Code Quality\n\n```bash\n# Format code\nblack aw_agents tests\n\n# Lint\nruff aw_agents tests\n\n# Type check\nmypy aw_agents\n```\n\n### Adding a New Agent\n\n1. Create a new directory in `aw_agents/`:\n ```\n aw_agents/myagent/\n \u251c\u2500\u2500 __init__.py\n \u251c\u2500\u2500 agent.py\n \u2514\u2500\u2500 core.py (if needed)\n ```\n\n2. Implement `AgentBase` in `agent.py`\n\n3. Add to `aw_agents/__init__.py`:\n ```python\n from aw_agents.myagent import MyAgent\n __all__.append('MyAgent')\n ```\n\n4. Create tests in `tests/test_myagent.py`\n\n5. Update documentation\n\n## Roadmap\n\n- [ ] Additional built-in agents (research, data prep, etc.)\n- [ ] Support for more platforms (Slack, Discord, etc.)\n- [ ] Agent composition and chaining\n- [ ] Persistent state management\n- [ ] Authentication and authorization\n- [ ] Web UI for agent management\n- [ ] CLI tools for deployment\n\n## Contributing\n\nContributions welcome! Please:\n\n1. Fork the repo\n2. Create a feature branch\n3. Add tests for new features\n4. Ensure all tests pass\n5. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Credits\n\nBuilt with:\n- [dol](https://github.com/i2mint/dol) - Storage abstractions\n- [graze](https://github.com/thorwhalen/graze) - Download and caching\n- [MCP](https://modelcontextprotocol.io/) - Model Context Protocol\n- [FastAPI](https://fastapi.tiangolo.com/) - Modern web framework\n\nPart of the [thorwhalen](https://github.com/thorwhalen) ecosystem.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "AI agents for agentic workflows, deployable to multiple chatbot platforms",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/yourusername/aw-agents#readme",
"Homepage": "https://github.com/yourusername/aw-agents",
"Issues": "https://github.com/yourusername/aw-agents/issues",
"Repository": "https://github.com/yourusername/aw-agents"
},
"split_keywords": [
"ai",
" agents",
" chatbots",
" mcp",
" openapi",
" claude",
" chatgpt"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "f434cd573cfd4fe36d1944a1c495bbfea99b54d16432272c021fb26ad34ff03a",
"md5": "d6af525db46b5f93ed8f0828c3a6f898",
"sha256": "69e1f79dc018229c494a222fa7da9e5d76920f744a3acaeeb3cdbbf475794ac9"
},
"downloads": -1,
"filename": "aw_agents-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d6af525db46b5f93ed8f0828c3a6f898",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 21527,
"upload_time": "2025-11-05T19:31:07",
"upload_time_iso_8601": "2025-11-05T19:31:07.001439Z",
"url": "https://files.pythonhosted.org/packages/f4/34/cd573cfd4fe36d1944a1c495bbfea99b54d16432272c021fb26ad34ff03a/aw_agents-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "05726792bca29c598111ffecce304d11ae046124f5fa989fdd42e9fff04ca759",
"md5": "be34c19b3eee43b6bff6637279a0efa4",
"sha256": "6e6a04720a0835b7e245a7ce39e67e7384ba1d400c27fce13e8c630cbcc8c148"
},
"downloads": -1,
"filename": "aw_agents-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "be34c19b3eee43b6bff6637279a0efa4",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 24415,
"upload_time": "2025-11-05T19:31:08",
"upload_time_iso_8601": "2025-11-05T19:31:08.478500Z",
"url": "https://files.pythonhosted.org/packages/05/72/6792bca29c598111ffecce304d11ae046124f5fa989fdd42e9fff04ca759/aw_agents-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-05 19:31:08",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "thorwhalen",
"github_project": "aw_agents",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "aw-agents"
}
JSON
