# Proto-Agent
An educational AI agent framework demonstrating capability-based security and modular toolkit architecture. Built for learning secure AI agent patterns with human oversight and permission controls.
## Features
- **Capability-based security** with granular permission controls
- **CLI tool** with human-in-the-loop approval for dangerous operations
- **Python framework** for building custom agents with programmatic control
- **Modular toolkits** for file operations, system monitoring, and version control
- **Educational focus** - clear, readable code demonstrating AI agent security patterns
## Quick Start
### Installation
```bash
pip install proto-agent
# or if you prefer the cli to be used from anywhere
uv tool install proto-agent # Recommended
# or using pipx
pipx install proto-agent
```
### Configuration
```bash
proto-agent --help # View CLI options, which include your config path for your OS
# Example config path for Linux: ~/.config/proto-agent/ will have .env file and config.toml
```
For Model configuration, please refer to the [Litellm documentation](https://docs.litellm.ai/docs/providers) for your exact name of the model you want to use.
### CLI Usage
```bash
# Safe read-only analysis
proto-agent "Analyze this codebase structure" ./my_project --read-only
# Interactive execution with approval prompts
proto-agent "Run the test suite" ./my_project
# Prompts: "Allow execution of function 'run_python_file'? (y/N):"
```
### Framework Usage
```python
from proto_agent import Agent, AgentConfig
from proto_agent.tool_kits import FileOperationToolkit
# Autonomous mode - no human approval needed
agent = Agent(AgentConfig(
api_key="your_api_key",
working_directory="./my_project",
tools=[FileOperationToolkit(
enable_read=True,
enable_write=False, # Disable risky operations
enable_execute=False
).tool]
))
response = agent.generate_content("Analyze this project's structure")
print(response.text)
```
## Key Concepts
- **CLI Mode**: Interactive approval prompts for dangerous operations
- **Framework Mode**: Full programmatic control over permissions
- **Capability Flags**: Enable/disable specific operations per toolkit
- **Human Oversight**: Configurable approval gates for security
## Available Toolkits
- **📁 FileOperationToolkit**: File reading, writing, and execution
- **💻 SystemInfoToolkit**: System monitoring and resource information
- **🔧 GitToolkit**: Version control operations with safety controls
## Documentation
- **[Complete Documentation](./docs/README-full.md)** - Full guide with examples and architecture
- **[Repository](https://github.com/WeismannS/Proto-agent)** - Source code and issues
- **[Inspiration](https://boot.dev)** - Boot.dev AI Agent Course
## Educational Goals
Proto-Agent prioritizes learning and security over performance:
- Demonstrates secure AI agent design patterns
- Shows human-in-the-loop safety controls
- Provides clear, modular architecture examples
- Emphasizes permission-based security models
Perfect for developers learning about AI agents, security patterns, or needing a foundation for experimentation.
## License
MIT License - see LICENSE file for details.
---
**⭐ Star the repo to support educational AI agent development!**
Raw data
{
"_id": null,
"home_page": null,
"name": "proto-agent",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, agent, modular, automation, library, framework, CLI",
"author": "WeismannS",
"author_email": "WeismannS <Sahazell@proton.me>",
"download_url": "https://files.pythonhosted.org/packages/6f/af/ec67b39225a10f0598ad77a1aab7f824535759054554502d6821a240de29/proto_agent-0.7.0.tar.gz",
"platform": null,
"description": "# Proto-Agent\n\nAn educational AI agent framework demonstrating capability-based security and modular toolkit architecture. Built for learning secure AI agent patterns with human oversight and permission controls.\n\n## Features\n\n- **Capability-based security** with granular permission controls\n- **CLI tool** with human-in-the-loop approval for dangerous operations\n- **Python framework** for building custom agents with programmatic control\n- **Modular toolkits** for file operations, system monitoring, and version control\n- **Educational focus** - clear, readable code demonstrating AI agent security patterns\n\n## Quick Start\n\n### Installation\n\n```bash\npip install proto-agent \n# or if you prefer the cli to be used from anywhere\nuv tool install proto-agent # Recommended\n# or using pipx\npipx install proto-agent\n```\n\n### Configuration\n\n```bash\nproto-agent --help # View CLI options, which include your config path for your OS \n# Example config path for Linux: ~/.config/proto-agent/ will have .env file and config.toml \n```\n\nFor Model configuration, please refer to the [Litellm documentation](https://docs.litellm.ai/docs/providers) for your exact name of the model you want to use.\n### CLI Usage\n\n```bash\n# Safe read-only analysis\nproto-agent \"Analyze this codebase structure\" ./my_project --read-only\n\n# Interactive execution with approval prompts\nproto-agent \"Run the test suite\" ./my_project\n# Prompts: \"Allow execution of function 'run_python_file'? (y/N):\"\n```\n\n### Framework Usage\n\n```python\nfrom proto_agent import Agent, AgentConfig\nfrom proto_agent.tool_kits import FileOperationToolkit\n\n# Autonomous mode - no human approval needed\nagent = Agent(AgentConfig(\n api_key=\"your_api_key\",\n working_directory=\"./my_project\",\n tools=[FileOperationToolkit(\n enable_read=True,\n enable_write=False, # Disable risky operations\n enable_execute=False\n ).tool]\n))\n\nresponse = agent.generate_content(\"Analyze this project's structure\")\nprint(response.text)\n```\n\n## Key Concepts\n\n- **CLI Mode**: Interactive approval prompts for dangerous operations\n- **Framework Mode**: Full programmatic control over permissions\n- **Capability Flags**: Enable/disable specific operations per toolkit\n- **Human Oversight**: Configurable approval gates for security\n\n## Available Toolkits\n\n- **\ud83d\udcc1 FileOperationToolkit**: File reading, writing, and execution\n- **\ud83d\udcbb SystemInfoToolkit**: System monitoring and resource information\n- **\ud83d\udd27 GitToolkit**: Version control operations with safety controls\n\n## Documentation\n\n- **[Complete Documentation](./docs/README-full.md)** - Full guide with examples and architecture\n- **[Repository](https://github.com/WeismannS/Proto-agent)** - Source code and issues\n- **[Inspiration](https://boot.dev)** - Boot.dev AI Agent Course\n\n## Educational Goals\n\nProto-Agent prioritizes learning and security over performance:\n\n- Demonstrates secure AI agent design patterns\n- Shows human-in-the-loop safety controls\n- Provides clear, modular architecture examples\n- Emphasizes permission-based security models\n\nPerfect for developers learning about AI agents, security patterns, or needing a foundation for experimentation.\n\n## License\n\nMIT License - see LICENSE file for details.\n\n---\n\n**\u2b50 Star the repo to support educational AI agent development!**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A modular AI agent framework that can also be your local CLI agent!",
"version": "0.7.0",
"project_urls": {
"Homepage": "https://github.com/WeismannS/proto-agent",
"Issues": "https://github.com/WeismannS/proto-agent/issues",
"Repository": "https://github.com/WeismannS/proto-agent"
},
"split_keywords": [
"ai",
" agent",
" modular",
" automation",
" library",
" framework",
" cli"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "56089890d411bafa205bdea655173d720682e45afcba144bac39fcd15de52d63",
"md5": "072848c82082eb0cf44ef6ec434462c2",
"sha256": "154da12e16ea09d6036a76066a839c9efaf9cab35893a01b9dbfd497c12e6330"
},
"downloads": -1,
"filename": "proto_agent-0.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "072848c82082eb0cf44ef6ec434462c2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 21996,
"upload_time": "2025-09-18T22:29:33",
"upload_time_iso_8601": "2025-09-18T22:29:33.791674Z",
"url": "https://files.pythonhosted.org/packages/56/08/9890d411bafa205bdea655173d720682e45afcba144bac39fcd15de52d63/proto_agent-0.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6fafec67b39225a10f0598ad77a1aab7f824535759054554502d6821a240de29",
"md5": "17aed8af09fa9be7529c99c7649668da",
"sha256": "f35316fef1ff91d7f4c0b6eb9e2841a403b19be408c183fd783da531ed6c18df"
},
"downloads": -1,
"filename": "proto_agent-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "17aed8af09fa9be7529c99c7649668da",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 16744,
"upload_time": "2025-09-18T22:29:35",
"upload_time_iso_8601": "2025-09-18T22:29:35.156431Z",
"url": "https://files.pythonhosted.org/packages/6f/af/ec67b39225a10f0598ad77a1aab7f824535759054554502d6821a240de29/proto_agent-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-18 22:29:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "WeismannS",
"github_project": "proto-agent",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "proto-agent"
}
JSON
