{"id":30762696,"url":"https://github.com/tobrun/gpt-agent","last_synced_at":"2026-07-13T20:32:20.781Z","repository":{"id":312759350,"uuid":"1048606760","full_name":"tobrun/gpt-agent","owner":"tobrun","description":"Python-based AI agent that connects to your locally-hosted GPT-OSS model via vLLM, with web search capabilities, using OpenAI Agents SDK.","archived":false,"fork":false,"pushed_at":"2025-09-01T19:42:55.000Z","size":68,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-19T20:38:55.775Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tobrun.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-01T18:06:12.000Z","updated_at":"2025-09-01T19:42:58.000Z","dependencies_parsed_at":null,"dependency_job_id":"40b4ff89-f875-409e-8591-d4acb1fb0cfc","html_url":"https://github.com/tobrun/gpt-agent","commit_stats":null,"previous_names":["tobrun/gpt-agent"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tobrun/gpt-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobrun%2Fgpt-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobrun%2Fgpt-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobrun%2Fgpt-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobrun%2Fgpt-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tobrun","download_url":"https://codeload.github.com/tobrun/gpt-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tobrun%2Fgpt-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35436279,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-13T02:00:06.543Z","response_time":119,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-04T15:10:11.731Z","updated_at":"2026-07-13T20:32:20.771Z","avatar_url":"https://github.com/tobrun.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GPT-OSS Agent v0.2.0\n\nA modern Python-based AI agent that connects to your locally-hosted GPT-OSS model via vLLM, with web search capabilities, using OpenAI Agents SDK.\n\n## ✨ What's New in v0.2.0\n\n- **🏗️ Modern Python Structure**: Proper package structure with `src/` layout\n- **⚙️ Type-Safe Configuration**: Pydantic-based configuration management  \n- **🔧 Improved Tooling**: Structured tool system with registry\n- **📊 Better Logging**: Enhanced logging and debug capabilities\n- **🧪 Testing Ready**: Foundation for comprehensive testing\n- **📦 Pip Installable**: Proper Python packaging with `pyproject.toml`\n\n## 🚀 Quick Start\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone \u003cyour-repo-url\u003e\ncd gpt-agent\n\n# Install in development mode (recommended)\npip install -e .\n\n# Or install dependencies only\npip install -r requirements.txt\n```\n\n### Configuration\n\n1. **Optional - Web Search**: Get an API key from [exa.ai](https://exa.ai)\n2. **Copy environment template**: `cp .env.example .env`\n3. **Edit configuration**: Set `EXA_API_KEY=your_key_here` in `.env`\n\n### Usage\n\n```bash\n# Test the connection\npython scripts/test_connection.py\n\n# Interactive chat\npython main.py\n\n# Single question\npython main.py --chat \"What's the weather like today?\"\n\n# Show system info\npython main.py --info\n\n# Test functionality\npython main.py --test\n\n# Use specific model\npython main.py --model gpt-oss-20b\n\n# Non-streaming mode\npython main.py --no-stream\n```\n\n### Interactive Commands\n\nOnce in chat mode:\n- `/help` - Show help\n- `/info` - Agent information  \n- `/tools` - Tools status\n- `/debug` - Debug session info\n- `/toggle-stream` - Toggle streaming\n- `/quit` - Exit\n\n## 📁 Project Structure\n\n```\ngpt-oss-agent/\n├── src/gpt_oss_agent/          # Main package\n│   ├── core/                   # Core agent functionality\n│   ├── clients/                # External service clients\n│   ├── tools/                  # Tool implementations\n│   ├── cli/                    # CLI interface\n│   ├── utils/                  # Utilities\n│   └── api/                    # Future API endpoints\n├── tests/                      # Test suite\n├── scripts/                    # Utility scripts\n├── docs/                       # Documentation\n├── examples/                   # Usage examples\n├── pyproject.toml             # Modern Python config\n└── README.md                  # This file\n```\n\n## 🛠️ Development\n\n### Using the New Structure\n\n```python\n# Import the agent\nfrom gpt_oss_agent import create_agent, get_settings\n\n# Create and use agent\nsettings = get_settings()\nagent = create_agent(settings=settings)\nresponse = agent.chat(\"Hello!\")\n```\n\n### Configuration Management\n\n```python\nfrom gpt_oss_agent.config import get_settings, Settings\n\n# Get current settings\nsettings = get_settings()\n\n# Create custom settings\ncustom_settings = Settings(\n    vllm__model=\"gpt-oss-20b\",\n    exa__api_key=\"your-key-here\"\n)\n```\n\n### Debug Logging\n\n```bash\n# View debug sessions\npython scripts/view_debug_logs.py --list\n\n# View session details\npython scripts/view_debug_logs.py --session 20250901_123456\n\n# View detailed message logs\npython scripts/view_debug_logs.py --session 20250901_123456 --detailed 1\n```\n\n## 🔧 Tools \u0026 Features\n\n- ✅ **Local GPT-OSS Integration** - Connects to vLLM server\n- ✅ **Web Search** - Real-time web search via Exa API  \n- ✅ **Streaming Responses** - Real-time response streaming\n- ✅ **Rich CLI** - Beautiful command-line interface\n- ✅ **Tool Registry** - Extensible tool system\n- ✅ **Debug Logging** - Comprehensive debugging\n- ✅ **Type Safety** - Full type hints and validation\n- ✅ **Modern Config** - Pydantic-based configuration\n\n## 📚 Documentation\n\n- [Installation Guide](docs/installation.md)\n- [Configuration Guide](docs/configuration.md)  \n- [Architecture Overview](docs/architecture.md)\n- [Troubleshooting](docs/troubleshooting.md)\n- [vLLM Setup](docs/VLLM_GPT_OSS.md)\n\n## 🧪 Testing\n\n```bash\n# Run tests (when implemented)\npytest\n\n# Test with coverage\npytest --cov=gpt_oss_agent\n\n# Type checking\nmypy src/\n\n# Code formatting\nblack src/ tests/\nruff check src/ tests/\n```\n\n## 🆘 Troubleshooting\n\n### Common Issues\n\n1. **Empty Responses**: Known vLLM `/v1/responses` endpoint issue\n   - Check [troubleshooting guide](docs/troubleshooting.md)\n   - Use debug logging: Set `DEBUG__ENABLED=true` in `.env`\n\n2. **Connection Errors**: vLLM server not accessible\n   - Verify server is running: `curl http://localhost:8000/v1/models`\n   - Check configuration: `python main.py --info`\n\n3. **No Web Search**: Exa API key not configured\n   - Get key from [exa.ai](https://exa.ai)\n   - Set in `.env`: `EXA_API_KEY=your_key`\n\n### Debug Logging\n\nDebug logs are saved to `logs/debug/` when enabled:\n\n```bash\n# Enable debug logging\necho \"DEBUG__ENABLED=true\" \u003e\u003e .env\n\n# View logs\npython scripts/view_debug_logs.py --list\n```\n\n## 🤝 Contributing\n\n1. **Fork the repository**\n2. **Create a feature branch**: `git checkout -b feature/amazing-feature`\n3. **Install dev dependencies**: `pip install -e .[dev]`\n4. **Make your changes**\n5. **Run tests**: `pytest`\n6. **Format code**: `black . \u0026\u0026 ruff check .`\n7. **Commit**: `git commit -m 'Add amazing feature'`\n8. **Push**: `git push origin feature/amazing-feature`\n9. **Open Pull Request**\n\n## 📄 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\n- [OpenAI Agents SDK](https://openai.github.io/openai-agents-python/)\n- [vLLM](https://github.com/vllm-project/vllm) \n- [Exa Search](https://exa.ai)\n- [Rich](https://rich.readthedocs.io/) for beautiful CLI","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftobrun%2Fgpt-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftobrun%2Fgpt-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftobrun%2Fgpt-agent/lists"}