| Name | base-agents JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | None |
| Summary | A simple way to build AI agents with tools, MCP (Model Context Protocol) tools, and sub-agents. |
| upload_time | 2025-08-06 16:44:13 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.12 |
| license | MIT |
| keywords |
agents
ai
hierarchical
langchain
llm
mcp
tools
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Base Agents
A simple way to build AI agents with tools, MCP (Model Context Protocol) tools, and sub-agents
## Features
- **Multiple Tool Types**: Support for simple functions, MCP (Model Context Protocol) tools, and sub-agents
- **Hierarchical Agent Architecture**: Create agents that can use other agents as tools
- **Async & Sync Support**: Both asynchronous and synchronous execution modes
- **Easy Integration**: Simple API that works with any LangChain-compatible model
- **Flexible Tool System**: Mix and match different types of tools in a single agent
## Installation
```bash
pip install base-agents
```
## Quick Start
### Basic Usage
```python
from base_agents import create_agent_tool
import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from langchain_core.tools import tool
import numpy as np
load_dotenv()
model = ChatOpenAI(model="gpt-4o", api_key=os.getenv("OPENAI_API_KEY"))
@tool
def complex_matrix_multiplication(
matrix1: list[list[complex]], matrix2: list[list[complex]]
) -> list[list[complex]]:
"""
Multiply two complex-valued matrices.
Args:
matrix1: First complex matrix as a 2D list (e.g., [[1+2j, 3+4j], [5+6j, 7+8j]])
matrix2: Second complex matrix as a 2D list (same format as matrix1)
Returns:
The product of the two matrices as a 2D list of complex numbers
Raises:
ValueError: If matrices cannot be multiplied due to incompatible dimensions
"""
np_matrix1 = np.array(matrix1, dtype=complex)
np_matrix2 = np.array(matrix2, dtype=complex)
try:
result = np.matmul(np_matrix1, np_matrix2)
return result.tolist()
except ValueError as e:
raise ValueError(f"Matrix multiplication error: {str(e)}")
simple_tools = [complex_matrix_multiplication]
# mcp_tools = {
# "puppeteer": {
# "command": "npx",
# "args": ["-y", "@modelcontextprotocol/server-puppeteer"],
# "transport": "stdio",
# }
# }
# sub_agent_math = [
# create_agent_tool(
# model,
# simple_tools=simple_tools,
# system_prompt="You are a subagent that can perform large number calculations.",
# )
# ]
# Create Main Agent
agent = create_agent_tool(
model,
simple_tools=simple_tools,
# mcp_tools=mcp_tools,
# sub_agent_tools=sub_agent_math,
system_prompt="You are a helpful assistant that can use tools and sub-agents to search online.",
)
# Example usage
response = agent.invoke(
"Multiply the following two complex-valued matrices and return the result: Matrix A: [[1+2j, 3+4j], [5+6j, 7+8j]] Matrix B: [[2+1j, 0+3j], [1+2j, 4+0j]]"
)
print("Response:", response)
```
## API Reference
### `create_agent_tool()`
Creates a structured tool that wraps an agent with various capabilities.
**Parameters:**
**Args:**
- **model**: A LangChain-compatible chat model _(required)_
- **mcp_tools**: Dictionary defining MCP (Model Context Protocol) tools _(optional)_
- **simple_tools**: List of simple function tools _(optional)_
- **sub_agent_tools**: List of other agent tools _(optional)_
- **system_prompt**: System prompt for the agent _(required)_
**Raises:**
- **ValueError**: If all tools (`mcp_tools`, `simple_tools`, and `sub_agent_tools`) are `None`. At least one tool type must be provided.
**Returns:**
A `StructuredTool` that can be used with LangChain's agent frameworks.
### Tool Types
#### Simple Tools
To write simple tools, use the `@tool` decorator from `langchain_core.tools` on a function, specifying input types and a docstring. The function should perform a specific task and return a result.
```python
from langchain_core.tools import tool
@tool
def math_tool(x: float, y: float) -> float:
"""Add two numbers together"""
return x + y
simple_tools = [math_tool]
```
#### MCP Tools
MCP tools enable integration with external services:
```python
mcp_tools = {
"puppeteer": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-puppeteer"],
"env": {"PUPPETEER_LAUNCH_OPTIONS": '{ "headless": true }'},
"transport": "stdio",
},
}
```
#### Sub-agent Tools
Sub-agent tools are other agents created with `create_agent_tool()`:
```python
math_agent = create_agent_tool(model, simple_tools=math_tools)
main_agent = create_agent_tool(model, sub_agent_tools=[math_agent])
```
## Usage Patterns
### Synchronous Execution
```python
response = agent.invoke("Your question here")
```
### Asynchronous Execution
```python
response = await agent.ainvoke("Your question here")
```
### Concurrent Execution
```python
import asyncio
async def run_multiple_tasks():
tasks = [
agent.ainvoke("Question 1"),
agent.ainvoke("Question 2"),
agent.ainvoke("Question 3"),
]
responses = await asyncio.gather(*tasks)
return responses
```
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
This project is licensed under the MIT License - see the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "base-agents",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": "agents, ai, hierarchical, langchain, llm, mcp, tools",
"author": null,
"author_email": "Haotian Shan <haotianshan@example.com>",
"download_url": "https://files.pythonhosted.org/packages/7b/d0/d63c4abfbaeb1618b1f7bf5e4f9848ca17762e6fa88539cb5a3a9c985ca9/base_agents-0.1.1.tar.gz",
"platform": null,
"description": "# Base Agents\n\nA simple way to build AI agents with tools, MCP (Model Context Protocol) tools, and sub-agents\n\n## Features\n\n- **Multiple Tool Types**: Support for simple functions, MCP (Model Context Protocol) tools, and sub-agents\n- **Hierarchical Agent Architecture**: Create agents that can use other agents as tools\n- **Async & Sync Support**: Both asynchronous and synchronous execution modes\n- **Easy Integration**: Simple API that works with any LangChain-compatible model\n- **Flexible Tool System**: Mix and match different types of tools in a single agent\n\n## Installation\n\n```bash\npip install base-agents\n```\n\n## Quick Start\n\n### Basic Usage\n\n```python\nfrom base_agents import create_agent_tool\nimport os\nfrom dotenv import load_dotenv\nfrom langchain_openai import ChatOpenAI\nfrom langchain_core.tools import tool\nimport numpy as np\n\nload_dotenv()\n\nmodel = ChatOpenAI(model=\"gpt-4o\", api_key=os.getenv(\"OPENAI_API_KEY\"))\n\n\n@tool\ndef complex_matrix_multiplication(\n matrix1: list[list[complex]], matrix2: list[list[complex]]\n) -> list[list[complex]]:\n \"\"\"\n Multiply two complex-valued matrices.\n\n Args:\n matrix1: First complex matrix as a 2D list (e.g., [[1+2j, 3+4j], [5+6j, 7+8j]])\n matrix2: Second complex matrix as a 2D list (same format as matrix1)\n\n Returns:\n The product of the two matrices as a 2D list of complex numbers\n\n Raises:\n ValueError: If matrices cannot be multiplied due to incompatible dimensions\n \"\"\"\n np_matrix1 = np.array(matrix1, dtype=complex)\n np_matrix2 = np.array(matrix2, dtype=complex)\n\n try:\n result = np.matmul(np_matrix1, np_matrix2)\n return result.tolist()\n except ValueError as e:\n raise ValueError(f\"Matrix multiplication error: {str(e)}\")\n\n\nsimple_tools = [complex_matrix_multiplication]\n\n# mcp_tools = {\n# \"puppeteer\": {\n# \"command\": \"npx\",\n# \"args\": [\"-y\", \"@modelcontextprotocol/server-puppeteer\"],\n# \"transport\": \"stdio\",\n# }\n# }\n\n# sub_agent_math = [\n# create_agent_tool(\n# model,\n# simple_tools=simple_tools,\n# system_prompt=\"You are a subagent that can perform large number calculations.\",\n# )\n# ]\n\n# Create Main Agent\nagent = create_agent_tool(\n model,\n simple_tools=simple_tools,\n # mcp_tools=mcp_tools,\n # sub_agent_tools=sub_agent_math,\n system_prompt=\"You are a helpful assistant that can use tools and sub-agents to search online.\",\n)\n\n# Example usage\nresponse = agent.invoke(\n \"Multiply the following two complex-valued matrices and return the result: Matrix A: [[1+2j, 3+4j], [5+6j, 7+8j]] Matrix B: [[2+1j, 0+3j], [1+2j, 4+0j]]\"\n)\nprint(\"Response:\", response)\n```\n\n## API Reference\n\n### `create_agent_tool()`\n\nCreates a structured tool that wraps an agent with various capabilities.\n\n**Parameters:**\n\n**Args:**\n\n- **model**: A LangChain-compatible chat model _(required)_\n- **mcp_tools**: Dictionary defining MCP (Model Context Protocol) tools _(optional)_\n- **simple_tools**: List of simple function tools _(optional)_\n- **sub_agent_tools**: List of other agent tools _(optional)_\n- **system_prompt**: System prompt for the agent _(required)_\n\n**Raises:**\n\n- **ValueError**: If all tools (`mcp_tools`, `simple_tools`, and `sub_agent_tools`) are `None`. At least one tool type must be provided.\n\n**Returns:**\n\nA `StructuredTool` that can be used with LangChain's agent frameworks.\n\n### Tool Types\n\n#### Simple Tools\n\nTo write simple tools, use the `@tool` decorator from `langchain_core.tools` on a function, specifying input types and a docstring. The function should perform a specific task and return a result.\n\n```python\nfrom langchain_core.tools import tool\n\n@tool\ndef math_tool(x: float, y: float) -> float:\n \"\"\"Add two numbers together\"\"\"\n return x + y\n\n\nsimple_tools = [math_tool]\n```\n\n#### MCP Tools\n\nMCP tools enable integration with external services:\n\n```python\nmcp_tools = {\n \"puppeteer\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@modelcontextprotocol/server-puppeteer\"],\n \"env\": {\"PUPPETEER_LAUNCH_OPTIONS\": '{ \"headless\": true }'},\n \"transport\": \"stdio\",\n },\n}\n```\n\n#### Sub-agent Tools\n\nSub-agent tools are other agents created with `create_agent_tool()`:\n\n```python\nmath_agent = create_agent_tool(model, simple_tools=math_tools)\nmain_agent = create_agent_tool(model, sub_agent_tools=[math_agent])\n```\n\n## Usage Patterns\n\n### Synchronous Execution\n\n```python\nresponse = agent.invoke(\"Your question here\")\n```\n\n### Asynchronous Execution\n\n```python\nresponse = await agent.ainvoke(\"Your question here\")\n```\n\n### Concurrent Execution\n\n```python\nimport asyncio\n\nasync def run_multiple_tasks():\n tasks = [\n agent.ainvoke(\"Question 1\"),\n agent.ainvoke(\"Question 2\"),\n agent.ainvoke(\"Question 3\"),\n ]\n responses = await asyncio.gather(*tasks)\n return responses\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple way to build AI agents with tools, MCP (Model Context Protocol) tools, and sub-agents.",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/HaotianShan/BaseAgents",
"Issues": "https://github.com/HaotianShan/BaseAgents/issues"
},
"split_keywords": [
"agents",
" ai",
" hierarchical",
" langchain",
" llm",
" mcp",
" tools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "facd78f049656f5552654b3ae61097857ee5b7bffb729e0e33b4389a5c98dbdc",
"md5": "4fa40277c3c8b9729bf80fd9eda0b72f",
"sha256": "0d7416018e9ecdf877bbfc4042d3670e0a5c90e1071b552fe9d8ab53bbafdd01"
},
"downloads": -1,
"filename": "base_agents-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4fa40277c3c8b9729bf80fd9eda0b72f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 4820,
"upload_time": "2025-08-06T16:44:11",
"upload_time_iso_8601": "2025-08-06T16:44:11.571355Z",
"url": "https://files.pythonhosted.org/packages/fa/cd/78f049656f5552654b3ae61097857ee5b7bffb729e0e33b4389a5c98dbdc/base_agents-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7bd0d63c4abfbaeb1618b1f7bf5e4f9848ca17762e6fa88539cb5a3a9c985ca9",
"md5": "d3880bab60bd89dad6f17c82454f05da",
"sha256": "f5246b00fc53cd88becd907beaa4a007ccc13ebc4c0af7dc5861bacd7b020ddf"
},
"downloads": -1,
"filename": "base_agents-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "d3880bab60bd89dad6f17c82454f05da",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 94162,
"upload_time": "2025-08-06T16:44:13",
"upload_time_iso_8601": "2025-08-06T16:44:13.202698Z",
"url": "https://files.pythonhosted.org/packages/7b/d0/d63c4abfbaeb1618b1f7bf5e4f9848ca17762e6fa88539cb5a3a9c985ca9/base_agents-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-06 16:44:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "HaotianShan",
"github_project": "BaseAgents",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "base-agents"
}
