# Agents Manager
[](https://badge.fury.io/py/agents-manager)
[](https://opensource.org/licenses/MIT)
[](https://pypi.org/project/agents-manager/)
A lightweight Python package for managing multi-agent orchestration. Easily define agents with custom instructions, tools, and models, and orchestrate their interactions seamlessly. Perfect for building modular, collaborative AI systems.
## Features
- Define agents with specific roles and instructions
- Assign models to agents (e.g., OpenAI models)
- Equip agents with tools and containers for performing tasks
- Seamlessly orchestrate interactions between multiple agents
## Supported Models
- OpenAI
- Grok
- DeepSeek
- Anthropic
- Llama
- Genai
## Installation
Install the package via pip:
```sh
pip install agents-manager
```
## Quick Start
```python
from agents_manager.utils import handover
from agents_manager import Agent, AgentManager
from agents_manager.models import OpenAi, Anthropic, Genai
from dotenv import load_dotenv
load_dotenv()
# Define the OpenAi model
openaiModel = OpenAi(name="gpt-4o-mini")
#Define the Anthropic model
anthropicModel = Anthropic(
name="claude-3-5-sonnet-20241022",
max_tokens= 1024,
)
#Define the Genai model
genaiModel = Genai(name="gemini-2.0-flash-001")
def multiply(a: int, b: int) -> int:
"""
Multiply two numbers.
"""
return a * b
def transfer_to_agent_3_for_math_calculation() -> Agent:
"""
Transfer to agent 3 for math calculation.
"""
return agent3
# The 'handover' function allows for transferring tasks to specific agents by name instead of instance.
# When `share_context` is set to True, the receiving agent will receive the
# chat history of the agent that is invoking the handover.
handover_to_agent2 = handover(name="agent2", description="This is a calculator", share_context=False)
# Define agents
agent3 = Agent(
name="agent3",
instruction="You are a maths teacher, explain properly how you calculated the answer.",
model=genaiModel,
tools=[multiply]
)
agent2 = Agent(
name="agent2",
instruction="You are a maths calculator bro",
model=anthropicModel,
tools=[transfer_to_agent_3_for_math_calculation]
)
agent1 = Agent(
name="agent1",
instruction="You are a helpful assistant",
model=openaiModel,
tools=[handover_to_agent2]
)
# Initialize Agent Manager and run agent
agent_manager = AgentManager()
agent_manager.add_agent(agent1)
# Using transfer doesn't require pre-adding the agent, but with handover, the agent must be added to
# the agent_manager beforehand.
agent_manager.add_agent(agent2)
response = agent_manager.run_agent("agent1", "What is 2 multiplied by 3?")
print(response["content"])
```
You can run for stream response as well.
```python
response_stream = agent_manager.run_agent_stream("agent1", [
{"role": "user", "content": "What is 2 multiplied by 3?"},
])
for chunk in response_stream:
print(chunk["content"], end="")
```
You can also pass container as tool to the agent.
```python
from agents_manager import Agent, AgentManager, Container
...
agent4 = Agent(
name="agent4",
instruction="You are a helpful assistant",
model=model,
tools=[Container(
name="hello",
description="A simple hello world container",
image="hello-world:latest",
)]
)
```
You can also pass the result of the container to the next agent with result variable.
```python
from agents_manager import Agent, Container
...
agent5 = Agent(
name="agent1",
instruction="You are a helpful assistant",
model=model,
tools=[Container(
name="processing",
description="Container to do some processing...",
image="docker/xxxx:latest",
environment=[
{"name": "input1", "type": "integer"},
{"name": "input2", "type": "integer"}
],
authenticate={
"username": "xxxxx",
"password": "xxxxx",
"registry": "xxxxx"
},
return_to={
"agent": agent6,
"instruction": "The result is: {result}" # {result} will be replaced with the result of the container
},
)]
)
```
You can also pass output_format to agent to format the output.
```python
from pydantic import BaseModel
from agents_manager import Agent
class Answer(BaseModel):
value: str
agent1 = Agent(
name="agent1",
instruction="You are a helpful assistant",
model=model,
output_format=Answer
)
```
Note 1: The output_format should be a pydantic model.
Note 2: Anthropic model does not support output_format, you can use tool to format the output.
Note 3: `handover` with share_context does not work correctly for Genai
You can also run the agent with a dictionary as the input content.
```python
response = agent_manager.run_agent("agent1", {"role": "user", "content": "What is 2 multiplied by 3?"})
```
You can also run the agent with a list of history of messages as the input.
```python
response = agent_manager.run_agent("agent1", [
{"role": "user", "content": "What is 2 multiplied by 3?"},
])
```
## More models
```python
from agents_manager.models import Grok, DeepSeek, Llama
#Define the Grok model
modelGrok = Grok(name="grok-2-latest")
#Define the DeepSeek model
modelDeepSeek = DeepSeek(name="deepseek-chat")
#Define the Llama model
modelLlama = Llama(name="llama3.1-70b")
```
## Troubleshooting
1. While using Genai model with functions, if you get the following error:
```python
google.genai.errors.ClientError: 400 INVALID_ARGUMENT. {'error': {'code': 400, 'message': '* GenerateContentRequest.tools[0].function_declarations[0].parameters.properties: should be non-empty for OBJECT type\n', 'status': 'INVALID_ARGUMENT'}}
```
It is because google genai does not support functions without parameters. You can fix this by providing a dummy parameter. Please let me know if you have a better solution for this.
2. If you get the following error while running the container tool:
```python
Error: Error while fetching server API version: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))
```
It is because the docker daemon is not running. You can fix this by starting the docker daemon.
and export the following environment variable:
```bash
#linux
export DOCKER_HOST=unix:///var/run/docker.sock
#colima
export DOCKER_HOST=unix://$HOME/.colima/default/docker.sock
```
## How It Works
1. **Define Agents**: Each agent has a name, a specific role (instruction), and a model.
2. **Assign Tools**: Agents can be assigned tools (functions and containers) to perform tasks.
3. **Create an Agent Manager**: The `AgentManager` manages the orchestration of agents.
4. **Run an Agent**: Start an agent to process a request and interact with other agents as needed.
## Use Cases
- AI-powered automation systems
- Multi-agent chatbots
- Complex workflow orchestration
- Research on AI agent collaboration
## Contributing
Contributions are welcome! Feel free to submit issues and pull requests.
## License
MIT License
Raw data
{
"_id": null,
"home_page": null,
"name": "agents-manager",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "agents, multi-agent, orchestration, AI",
"author": null,
"author_email": "Naroju Sandesh <sandeshnaroju@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/76/e9/2b4f4631a8e93aac270995adbfb12a204197e35009fb11a0fe909fbd9a74/agents_manager-1.4.6.tar.gz",
"platform": null,
"description": "# Agents Manager\n\n[](https://badge.fury.io/py/agents-manager)\n[](https://opensource.org/licenses/MIT)\n\n[](https://pypi.org/project/agents-manager/)\n\nA lightweight Python package for managing multi-agent orchestration. Easily define agents with custom instructions, tools, and models, and orchestrate their interactions seamlessly. Perfect for building modular, collaborative AI systems.\n\n## Features\n\n- Define agents with specific roles and instructions\n- Assign models to agents (e.g., OpenAI models)\n- Equip agents with tools and containers for performing tasks\n- Seamlessly orchestrate interactions between multiple agents\n\n## Supported Models\n\n- OpenAI\n- Grok\n- DeepSeek\n- Anthropic\n- Llama\n- Genai\n\n## Installation\n\nInstall the package via pip:\n\n```sh\npip install agents-manager\n```\n\n## Quick Start\n\n```python\nfrom agents_manager.utils import handover\nfrom agents_manager import Agent, AgentManager\nfrom agents_manager.models import OpenAi, Anthropic, Genai\n\nfrom dotenv import load_dotenv\n\nload_dotenv()\n\n# Define the OpenAi model\nopenaiModel = OpenAi(name=\"gpt-4o-mini\")\n\n#Define the Anthropic model\nanthropicModel = Anthropic(\n name=\"claude-3-5-sonnet-20241022\",\n max_tokens= 1024,\n )\n\n#Define the Genai model\ngenaiModel = Genai(name=\"gemini-2.0-flash-001\")\n\ndef multiply(a: int, b: int) -> int:\n \"\"\"\n Multiply two numbers.\n \"\"\"\n return a * b\n\n\ndef transfer_to_agent_3_for_math_calculation() -> Agent:\n \"\"\"\n Transfer to agent 3 for math calculation.\n \"\"\"\n return agent3\n\n# The 'handover' function allows for transferring tasks to specific agents by name instead of instance.\n# When `share_context` is set to True, the receiving agent will receive the \n# chat history of the agent that is invoking the handover.\nhandover_to_agent2 = handover(name=\"agent2\", description=\"This is a calculator\", share_context=False)\n\n# Define agents\nagent3 = Agent(\n name=\"agent3\",\n instruction=\"You are a maths teacher, explain properly how you calculated the answer.\",\n model=genaiModel,\n tools=[multiply]\n)\n\nagent2 = Agent(\n name=\"agent2\",\n instruction=\"You are a maths calculator bro\",\n model=anthropicModel,\n tools=[transfer_to_agent_3_for_math_calculation]\n)\n\nagent1 = Agent(\n name=\"agent1\",\n instruction=\"You are a helpful assistant\",\n model=openaiModel,\n tools=[handover_to_agent2]\n)\n\n# Initialize Agent Manager and run agent\nagent_manager = AgentManager()\nagent_manager.add_agent(agent1)\n\n# Using transfer doesn't require pre-adding the agent, but with handover, the agent must be added to\n# the agent_manager beforehand.\nagent_manager.add_agent(agent2)\n\nresponse = agent_manager.run_agent(\"agent1\", \"What is 2 multiplied by 3?\")\nprint(response[\"content\"])\n```\n\nYou can run for stream response as well.\n```python\nresponse_stream = agent_manager.run_agent_stream(\"agent1\", [\n {\"role\": \"user\", \"content\": \"What is 2 multiplied by 3?\"},\n])\nfor chunk in response_stream:\n print(chunk[\"content\"], end=\"\")\n```\n\nYou can also pass container as tool to the agent.\n```python\nfrom agents_manager import Agent, AgentManager, Container\n\n...\n\nagent4 = Agent(\n name=\"agent4\",\n instruction=\"You are a helpful assistant\",\n model=model,\n tools=[Container(\n name=\"hello\",\n description=\"A simple hello world container\",\n image=\"hello-world:latest\",\n )]\n)\n```\n\nYou can also pass the result of the container to the next agent with result variable.\n```python\nfrom agents_manager import Agent, Container\n\n...\n\nagent5 = Agent(\n name=\"agent1\",\n instruction=\"You are a helpful assistant\",\n model=model,\n tools=[Container(\n name=\"processing\",\n description=\"Container to do some processing...\",\n image=\"docker/xxxx:latest\",\n environment=[\n {\"name\": \"input1\", \"type\": \"integer\"},\n {\"name\": \"input2\", \"type\": \"integer\"}\n ],\n authenticate={\n \"username\": \"xxxxx\",\n \"password\": \"xxxxx\",\n \"registry\": \"xxxxx\"\n },\n return_to={\n \"agent\": agent6,\n \"instruction\": \"The result is: {result}\" # {result} will be replaced with the result of the container\n },\n )]\n)\n```\n\nYou can also pass output_format to agent to format the output.\n\n```python\nfrom pydantic import BaseModel\n\nfrom agents_manager import Agent\n\n\nclass Answer(BaseModel):\n value: str\n\nagent1 = Agent(\n name=\"agent1\",\n instruction=\"You are a helpful assistant\",\n model=model,\n output_format=Answer\n)\n```\nNote 1: The output_format should be a pydantic model.\n\nNote 2: Anthropic model does not support output_format, you can use tool to format the output.\n\nNote 3: `handover` with share_context does not work correctly for Genai\n\nYou can also run the agent with a dictionary as the input content.\n```python\n\nresponse = agent_manager.run_agent(\"agent1\", {\"role\": \"user\", \"content\": \"What is 2 multiplied by 3?\"})\n\n```\n\nYou can also run the agent with a list of history of messages as the input.\n```python\nresponse = agent_manager.run_agent(\"agent1\", [\n {\"role\": \"user\", \"content\": \"What is 2 multiplied by 3?\"},\n])\n```\n\n\n\n## More models\n```python\nfrom agents_manager.models import Grok, DeepSeek, Llama\n\n#Define the Grok model\nmodelGrok = Grok(name=\"grok-2-latest\")\n\n\n#Define the DeepSeek model\nmodelDeepSeek = DeepSeek(name=\"deepseek-chat\")\n\n\n#Define the Llama model\nmodelLlama = Llama(name=\"llama3.1-70b\")\n\n```\n\n\n## Troubleshooting\n\n1. While using Genai model with functions, if you get the following error:\n\n```python\ngoogle.genai.errors.ClientError: 400 INVALID_ARGUMENT. {'error': {'code': 400, 'message': '* GenerateContentRequest.tools[0].function_declarations[0].parameters.properties: should be non-empty for OBJECT type\\n', 'status': 'INVALID_ARGUMENT'}}\n\n```\nIt is because google genai does not support functions without parameters. You can fix this by providing a dummy parameter. Please let me know if you have a better solution for this. \n\n2. If you get the following error while running the container tool:\n```python\nError: Error while fetching server API version: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))\n```\n\nIt is because the docker daemon is not running. You can fix this by starting the docker daemon.\nand export the following environment variable:\n\n```bash\n#linux\nexport DOCKER_HOST=unix:///var/run/docker.sock\n\n#colima\nexport DOCKER_HOST=unix://$HOME/.colima/default/docker.sock\n```\n\n\n## How It Works\n\n1. **Define Agents**: Each agent has a name, a specific role (instruction), and a model.\n2. **Assign Tools**: Agents can be assigned tools (functions and containers) to perform tasks.\n3. **Create an Agent Manager**: The `AgentManager` manages the orchestration of agents.\n4. **Run an Agent**: Start an agent to process a request and interact with other agents as needed.\n\n\n\n\n## Use Cases\n\n- AI-powered automation systems\n- Multi-agent chatbots\n- Complex workflow orchestration\n- Research on AI agent collaboration\n\n## Contributing\n\nContributions are welcome! Feel free to submit issues and pull requests.\n\n## License\n\nMIT License\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A lightweight Python package for managing multi-agent orchestration. Easily define agents with custom instructions, tools, containers, and models, and orchestrate their interactions seamlessly. Perfect for building modular, collaborative AI systems.",
"version": "1.4.6",
"project_urls": {
"Homepage": "https://github.com/sandeshnaroju/agents_manager",
"Repository": "https://github.com/sandeshnaroju/agents_manager"
},
"split_keywords": [
"agents",
" multi-agent",
" orchestration",
" ai"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a0edb5320b023b80ce009113982e0b699f12228d5ea714aeea0e33e86485a083",
"md5": "d4ac1aff39b35b78b840d20e45b82e99",
"sha256": "b763119575cca8275c64b3e349411e481ebd481ccaab1b972e6c04d0014e7deb"
},
"downloads": -1,
"filename": "agents_manager-1.4.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d4ac1aff39b35b78b840d20e45b82e99",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 23283,
"upload_time": "2025-07-31T06:31:04",
"upload_time_iso_8601": "2025-07-31T06:31:04.960054Z",
"url": "https://files.pythonhosted.org/packages/a0/ed/b5320b023b80ce009113982e0b699f12228d5ea714aeea0e33e86485a083/agents_manager-1.4.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "76e92b4f4631a8e93aac270995adbfb12a204197e35009fb11a0fe909fbd9a74",
"md5": "9b36b15ebd5d66b3eff4163e759ebe07",
"sha256": "62c312b6045a8048469bd56e2f918555c78ad5e2a8f061573f8c2d7763dd241b"
},
"downloads": -1,
"filename": "agents_manager-1.4.6.tar.gz",
"has_sig": false,
"md5_digest": "9b36b15ebd5d66b3eff4163e759ebe07",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 19673,
"upload_time": "2025-07-31T06:31:06",
"upload_time_iso_8601": "2025-07-31T06:31:06.545020Z",
"url": "https://files.pythonhosted.org/packages/76/e9/2b4f4631a8e93aac270995adbfb12a204197e35009fb11a0fe909fbd9a74/agents_manager-1.4.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-31 06:31:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sandeshnaroju",
"github_project": "agents_manager",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "annotated-types",
"specs": [
[
"==",
"0.7.0"
]
]
},
{
"name": "anthropic",
"specs": [
[
"==",
"0.47.1"
]
]
},
{
"name": "anyio",
"specs": [
[
"==",
"4.8.0"
]
]
},
{
"name": "backports.tarfile",
"specs": [
[
"==",
"1.2.0"
]
]
},
{
"name": "build",
"specs": [
[
"==",
"1.2.2.post1"
]
]
},
{
"name": "cachetools",
"specs": [
[
"==",
"5.5.2"
]
]
},
{
"name": "certifi",
"specs": [
[
"==",
"2025.1.31"
]
]
},
{
"name": "charset-normalizer",
"specs": [
[
"==",
"3.4.1"
]
]
},
{
"name": "distro",
"specs": [
[
"==",
"1.9.0"
]
]
},
{
"name": "docker",
"specs": [
[
"==",
"7.1.0"
]
]
},
{
"name": "docutils",
"specs": [
[
"==",
"0.21.2"
]
]
},
{
"name": "dotenv",
"specs": [
[
"==",
"0.9.9"
]
]
},
{
"name": "exceptiongroup",
"specs": [
[
"==",
"1.2.2"
]
]
},
{
"name": "google-auth",
"specs": [
[
"==",
"2.38.0"
]
]
},
{
"name": "google-genai",
"specs": [
[
"==",
"1.4.0"
]
]
},
{
"name": "h11",
"specs": [
[
"==",
"0.14.0"
]
]
},
{
"name": "httpcore",
"specs": [
[
"==",
"1.0.7"
]
]
},
{
"name": "httpx",
"specs": [
[
"==",
"0.28.1"
]
]
},
{
"name": "id",
"specs": [
[
"==",
"1.5.0"
]
]
},
{
"name": "idna",
"specs": [
[
"==",
"3.10"
]
]
},
{
"name": "importlib_metadata",
"specs": [
[
"==",
"8.6.1"
]
]
},
{
"name": "jaraco.classes",
"specs": [
[
"==",
"3.4.0"
]
]
},
{
"name": "jaraco.context",
"specs": [
[
"==",
"6.0.1"
]
]
},
{
"name": "jaraco.functools",
"specs": [
[
"==",
"4.1.0"
]
]
},
{
"name": "jiter",
"specs": [
[
"==",
"0.8.2"
]
]
},
{
"name": "keyring",
"specs": [
[
"==",
"25.6.0"
]
]
},
{
"name": "markdown-it-py",
"specs": [
[
"==",
"3.0.0"
]
]
},
{
"name": "mdurl",
"specs": [
[
"==",
"0.1.2"
]
]
},
{
"name": "more-itertools",
"specs": [
[
"==",
"10.6.0"
]
]
},
{
"name": "nh3",
"specs": [
[
"==",
"0.2.20"
]
]
},
{
"name": "openai",
"specs": [
[
"==",
"1.63.2"
]
]
},
{
"name": "packaging",
"specs": [
[
"==",
"24.2"
]
]
},
{
"name": "pyasn1",
"specs": [
[
"==",
"0.6.1"
]
]
},
{
"name": "pyasn1_modules",
"specs": [
[
"==",
"0.4.1"
]
]
},
{
"name": "pydantic",
"specs": [
[
"==",
"2.10.6"
]
]
},
{
"name": "pydantic_core",
"specs": [
[
"==",
"2.27.2"
]
]
},
{
"name": "Pygments",
"specs": [
[
"==",
"2.19.1"
]
]
},
{
"name": "pyproject_hooks",
"specs": [
[
"==",
"1.2.0"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"8.2.2"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
"==",
"1.0.1"
]
]
},
{
"name": "readme_renderer",
"specs": [
[
"==",
"44.0"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.32.3"
]
]
},
{
"name": "requests-toolbelt",
"specs": [
[
"==",
"1.0.0"
]
]
},
{
"name": "rfc3986",
"specs": [
[
"==",
"2.0.0"
]
]
},
{
"name": "rich",
"specs": [
[
"==",
"13.9.4"
]
]
},
{
"name": "rsa",
"specs": [
[
"==",
"4.9"
]
]
},
{
"name": "sniffio",
"specs": [
[
"==",
"1.3.1"
]
]
},
{
"name": "tomli",
"specs": [
[
"==",
"2.2.1"
]
]
},
{
"name": "tqdm",
"specs": [
[
"==",
"4.67.1"
]
]
},
{
"name": "twine",
"specs": [
[
"==",
"6.1.0"
]
]
},
{
"name": "typing_extensions",
"specs": [
[
"==",
"4.12.2"
]
]
},
{
"name": "urllib3",
"specs": [
[
"==",
"2.3.0"
]
]
},
{
"name": "websockets",
"specs": [
[
"==",
"14.2"
]
]
},
{
"name": "zipp",
"specs": [
[
"==",
"3.21.0"
]
]
}
],
"lcname": "agents-manager"
}
