# Lightweight Agent Framework
<p align="center">
<img src="https://raw.githubusercontent.com/andrewlwn77/robotape/refs/heads/main/docs/lightagent.jpg" alt="Lightweight Agent Framework Logo" width="400"/>
</p>
A minimalist, extensible framework for building autonomous agents with a focus on transparency and composability.
## Overview
Lightweight Agent Framework (LAF) provides a simple yet powerful foundation for building autonomous agents that can think, act, and observe within a structured environment. With LAF, you can:
- Create agents that follow a clear think-act-observe cycle
- Record and replay agent interactions using the tape system
- Build complex workflows by composing multiple agents
- Persist and analyze agent execution history
- Extend functionality through a modular tool system
- Integrate with external tools and services using the **Model Control Protocol (MCP)**
---
## System Architecture
The following diagram illustrates how the components of the Lightweight Agent Framework fit together:
```mermaid
graph TD
A[Agent] -->|Think| B[LLM]
A -->|Act| C[MCP Server]
A -->|Observe| D[Tape System]
B -->|Generate Thoughts| A
C -->|Execute Tools| A
D -->|Record Steps| A
D -->|Replay History| A
```
### Key Components:
- **Agent**: The core entity that performs the think-act-observe cycle.
- **LLM**: Large Language Model used by the agent to generate thoughts and reasoning.
- **MCP Server**: External server that provides tools and services for the agent to execute actions.
- **Tape System**: Records the agent's execution history for analysis, debugging, and replay.
---
## Key Features
- **Simple Core Concepts**: Based on three fundamental operations - think, act, and observe
- **Tape-Based History**: Record every step of your agent's execution for analysis and debugging
- **Modular Tools**: Easily extend agent capabilities through a flexible tool system
- **Built-in Storage**: Persist agent history with built-in SQLite support (expandable to other backends)
- **Async Support**: Built with asyncio for efficient concurrent operations
- **Testing Ready**: Comprehensive testing utilities and fixtures included
- **MCP Integration**: Seamlessly integrate with external tools and services using the Model Control Protocol
---
## Quick Installation
```bash
pip install robotape
```
For development installation:
```bash
pip install robotape[dev]
```
---
## Basic Usage
Here's a simple example of creating and running an agent:
```python
from robotape.agents import SimpleAgent
from robotape.tape import Tape, StepType
# Create an agent and a tape
agent = SimpleAgent("my_agent")
tape = Tape()
# Add an initial thought
tape.append(Step(
type=StepType.THOUGHT,
content="I should search for information",
metadata=StepMetadata(agent="my_agent", node="planning")
))
# Execute the agent
await agent.execute_step(tape.get_last_step())
```
---
## Using MCPLLMAgent
The `MCPLLMAgent` is a specialized agent that combines the capabilities of LLMs with the **Model Control Protocol (MCP)**. It allows agents to interact with external tools and services through an MCP server, enabling more complex workflows and integrations.
### Example: Using MCPLLMAgent
```python
from robotape.agents.mcpllm import MCPLLMAgent
from robotape.llm import LLMConfig
# Configure the LLM
llm_config = LLMConfig(
model="gpt-4",
api_key="your-api-key",
provider_name="openai"
)
# Configure the MCP server
mcp_config = {
"command": "python",
"args": ["path/to/mcp_server.py"],
"env": {"ENV_VAR": "value"}
}
# Create an MCPLLMAgent
agent = MCPLLMAgent("mcp_agent", llm_config, mcp_config)
# Connect to the MCP server
await agent.connect()
# Execute a full think-act-observe cycle
context = {"task": "Analyze test data"}
thought_result = await agent.think(context)
action_result = await agent.act(thought_result)
observe_result = await agent.observe(action_result)
```
---
## Advanced Features
- **Custom Agents**: Extend `BaseAgent` to create specialized agents
- **Tool Integration**: Add new capabilities through the tool system
- **Storage Backends**: Built-in SQLite support, extensible to other databases
- **Tape Management**: Clone, branch, and analyze execution history
- **Validation**: Built-in parameter validation and error handling
- **MCP Integration**: Connect to external tools and services using the Model Control Protocol
---
## Documentation
The framework provides comprehensive documentation covering all aspects:
1. **[Getting Started Guide](docs/getting_started.md)**: Quick start guide and core concepts
2. **[API Reference](docs/api_reference.md)**: Complete reference of all public APIs
3. **[Advanced Patterns](docs/advanced_patterns.md)**: Advanced usage patterns and best practices
4. **[Agent System](docs/agents.md)**: Guide to creating and managing agents
5. **[LLM Integration](docs/llm_integration.md)**: Integrating Large Language Models
6. **[MCP (Master Control Program)](docs/mcp.md)**: Understanding the MCP component
7. **[MCP Tools](docs/mcp_tools.md)**: Available MCP tools and utilities
8. **[Tape System](docs/tape_system.md)**: Recording and analyzing agent execution
9. **[Tools](docs/tools.md)**: Using and creating agent tools
---
## Development
Clone and set up the development environment:
```bash
git clone https://github.com/andrewlwn77/robotape.git
cd robotape
pip install -e ".[dev]"
```
Run tests:
```bash
pytest tests/ --cov=robotape
```
---
## Contributing
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
---
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/andrewlwn77/robotape",
"name": "robotape",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "agent, framework, autonomous, AI",
"author": "Andrew Lewin",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/4b/86/9d1a6c343074762f7afa39a3cc59e22cb5babec1728dee8cf724de71c31d/robotape-0.5.0.tar.gz",
"platform": null,
"description": "# Lightweight Agent Framework\n\n<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/andrewlwn77/robotape/refs/heads/main/docs/lightagent.jpg\" alt=\"Lightweight Agent Framework Logo\" width=\"400\"/>\n</p>\n\nA minimalist, extensible framework for building autonomous agents with a focus on transparency and composability.\n\n## Overview\n\nLightweight Agent Framework (LAF) provides a simple yet powerful foundation for building autonomous agents that can think, act, and observe within a structured environment. With LAF, you can:\n\n- Create agents that follow a clear think-act-observe cycle\n- Record and replay agent interactions using the tape system\n- Build complex workflows by composing multiple agents\n- Persist and analyze agent execution history\n- Extend functionality through a modular tool system\n- Integrate with external tools and services using the **Model Control Protocol (MCP)**\n\n---\n\n## System Architecture\n\nThe following diagram illustrates how the components of the Lightweight Agent Framework fit together:\n\n```mermaid\ngraph TD\n A[Agent] -->|Think| B[LLM]\n A -->|Act| C[MCP Server]\n A -->|Observe| D[Tape System]\n B -->|Generate Thoughts| A\n C -->|Execute Tools| A\n D -->|Record Steps| A\n D -->|Replay History| A\n```\n\n### Key Components:\n- **Agent**: The core entity that performs the think-act-observe cycle.\n- **LLM**: Large Language Model used by the agent to generate thoughts and reasoning.\n- **MCP Server**: External server that provides tools and services for the agent to execute actions.\n- **Tape System**: Records the agent's execution history for analysis, debugging, and replay.\n\n---\n\n## Key Features\n\n- **Simple Core Concepts**: Based on three fundamental operations - think, act, and observe\n- **Tape-Based History**: Record every step of your agent's execution for analysis and debugging\n- **Modular Tools**: Easily extend agent capabilities through a flexible tool system\n- **Built-in Storage**: Persist agent history with built-in SQLite support (expandable to other backends)\n- **Async Support**: Built with asyncio for efficient concurrent operations\n- **Testing Ready**: Comprehensive testing utilities and fixtures included\n- **MCP Integration**: Seamlessly integrate with external tools and services using the Model Control Protocol\n\n---\n\n## Quick Installation\n\n```bash\npip install robotape\n```\n\nFor development installation:\n\n```bash\npip install robotape[dev]\n```\n\n---\n\n## Basic Usage\n\nHere's a simple example of creating and running an agent:\n\n```python\nfrom robotape.agents import SimpleAgent\nfrom robotape.tape import Tape, StepType\n\n# Create an agent and a tape\nagent = SimpleAgent(\"my_agent\")\ntape = Tape()\n\n# Add an initial thought\ntape.append(Step(\n type=StepType.THOUGHT,\n content=\"I should search for information\",\n metadata=StepMetadata(agent=\"my_agent\", node=\"planning\")\n))\n\n# Execute the agent\nawait agent.execute_step(tape.get_last_step())\n```\n\n---\n\n## Using MCPLLMAgent\n\nThe `MCPLLMAgent` is a specialized agent that combines the capabilities of LLMs with the **Model Control Protocol (MCP)**. It allows agents to interact with external tools and services through an MCP server, enabling more complex workflows and integrations.\n\n### Example: Using MCPLLMAgent\n\n```python\nfrom robotape.agents.mcpllm import MCPLLMAgent\nfrom robotape.llm import LLMConfig\n\n# Configure the LLM\nllm_config = LLMConfig(\n model=\"gpt-4\",\n api_key=\"your-api-key\",\n provider_name=\"openai\"\n)\n\n# Configure the MCP server\nmcp_config = {\n \"command\": \"python\",\n \"args\": [\"path/to/mcp_server.py\"],\n \"env\": {\"ENV_VAR\": \"value\"}\n}\n\n# Create an MCPLLMAgent\nagent = MCPLLMAgent(\"mcp_agent\", llm_config, mcp_config)\n\n# Connect to the MCP server\nawait agent.connect()\n\n# Execute a full think-act-observe cycle\ncontext = {\"task\": \"Analyze test data\"}\nthought_result = await agent.think(context)\naction_result = await agent.act(thought_result)\nobserve_result = await agent.observe(action_result)\n```\n\n---\n\n## Advanced Features\n\n- **Custom Agents**: Extend `BaseAgent` to create specialized agents\n- **Tool Integration**: Add new capabilities through the tool system\n- **Storage Backends**: Built-in SQLite support, extensible to other databases\n- **Tape Management**: Clone, branch, and analyze execution history\n- **Validation**: Built-in parameter validation and error handling\n- **MCP Integration**: Connect to external tools and services using the Model Control Protocol\n\n---\n\n## Documentation\n\nThe framework provides comprehensive documentation covering all aspects:\n\n1. **[Getting Started Guide](docs/getting_started.md)**: Quick start guide and core concepts\n2. **[API Reference](docs/api_reference.md)**: Complete reference of all public APIs\n3. **[Advanced Patterns](docs/advanced_patterns.md)**: Advanced usage patterns and best practices\n4. **[Agent System](docs/agents.md)**: Guide to creating and managing agents\n5. **[LLM Integration](docs/llm_integration.md)**: Integrating Large Language Models\n6. **[MCP (Master Control Program)](docs/mcp.md)**: Understanding the MCP component\n7. **[MCP Tools](docs/mcp_tools.md)**: Available MCP tools and utilities\n8. **[Tape System](docs/tape_system.md)**: Recording and analyzing agent execution\n9. **[Tools](docs/tools.md)**: Using and creating agent tools\n\n---\n\n## Development\n\nClone and set up the development environment:\n\n```bash\ngit clone https://github.com/andrewlwn77/robotape.git\ncd robotape\npip install -e \".[dev]\"\n```\n\nRun tests:\n\n```bash\npytest tests/ --cov=robotape\n```\n\n---\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n---\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A lightweight agent framework",
"version": "0.5.0",
"project_urls": {
"Documentation": "https://github.com/andrewlwn77/robotape/tree/main/docs",
"Homepage": "https://github.com/andrewlwn77/robotape",
"Repository": "https://github.com/andrewlwn77/robotape"
},
"split_keywords": [
"agent",
" framework",
" autonomous",
" ai"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b7c624b403c07aae298cc1684041bdb34b33685f5717f2fd2aac0f7078ec102f",
"md5": "bd9b52dc746cd83119189d87490ee8fe",
"sha256": "0cad37a6b8c0af583fef33a3c727da6881c96a9a286240a37d0a6a70a4a6c7ca"
},
"downloads": -1,
"filename": "robotape-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bd9b52dc746cd83119189d87490ee8fe",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 27525,
"upload_time": "2025-01-08T05:10:01",
"upload_time_iso_8601": "2025-01-08T05:10:01.008666Z",
"url": "https://files.pythonhosted.org/packages/b7/c6/24b403c07aae298cc1684041bdb34b33685f5717f2fd2aac0f7078ec102f/robotape-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4b869d1a6c343074762f7afa39a3cc59e22cb5babec1728dee8cf724de71c31d",
"md5": "08be3e02750af5871739c85d32421be1",
"sha256": "eb7ae1d92e72a455f69e1284ae2fbbe078f1432e40d291a01f4134aa78af8d03"
},
"downloads": -1,
"filename": "robotape-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "08be3e02750af5871739c85d32421be1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 20509,
"upload_time": "2025-01-08T05:10:03",
"upload_time_iso_8601": "2025-01-08T05:10:03.517358Z",
"url": "https://files.pythonhosted.org/packages/4b/86/9d1a6c343074762f7afa39a3cc59e22cb5babec1728dee8cf724de71c31d/robotape-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-08 05:10:03",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "andrewlwn77",
"github_project": "robotape",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "pydantic",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "sqlmodel",
"specs": [
[
">=",
"0.0.8"
]
]
},
{
"name": "sqlalchemy",
"specs": [
[
">=",
"2.0.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "asyncio",
"specs": [
[
">=",
"3.4.3"
]
]
},
{
"name": "aiohttp",
"specs": [
[
">=",
"3.8.0"
]
]
},
{
"name": "typing-extensions",
"specs": [
[
">=",
"4.5.0"
]
]
},
{
"name": "uuid",
"specs": [
[
">=",
"1.30"
]
]
},
{
"name": "mirascope",
"specs": [
[
">=",
"1.14.0"
]
]
},
{
"name": "mirascope",
"specs": []
},
{
"name": "mirascope",
"specs": []
},
{
"name": "mcp",
"specs": [
[
">=",
"1.2.0"
]
]
},
{
"name": "openai",
"specs": [
[
">=",
"1.59.3"
]
]
},
{
"name": "anthropic",
"specs": [
[
">=",
"0.42.0"
]
]
},
{
"name": "huggingface-hub",
"specs": [
[
">=",
"0.27.0"
]
]
}
],
"lcname": "robotape"
}
JSON
