agentkit 0.0.2__tar.gz → 0.0.4__tar.gz

{agentkit-0.0.2 → agentkit-0.0.4}/PKG-INFO

@@ -1,25 +1,27 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: agentkit
-Version: 0.0.2
+Version: 0.0.4
 Summary: A simple framework for creating distributed llm agent swarms
 License: MIT
+License-File: LICENSE
 Keywords: artificial intelligence,agent frameworks,llm
 Author: Vikram Kumar
 Author-email: vik@japanvik.net
-Requires-Python: >=3.8
+Requires-Python: >=3.10
 Classifier: Development Status :: 4 - Beta
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: litellm
+Requires-Dist: mcp (>=1.14,<2.0)
 Requires-Dist: networkkit (>=0.0.2)
 Requires-Dist: python-dotenv
+Requires-Dist: rich
 Project-URL: Repository, https://github.com/japanvik/agentkit
 Description-Content-Type: text/markdown
 
@@ -37,7 +39,7 @@ Install `AgentKit` using pip:
 pip install agentkit
 ```
 
-Ensure you have Python 3.8 or higher installed to meet the compatibility requirements.
+Ensure you have Python 3.10 or higher installed to meet the compatibility requirements.
 
 ## Features
 
@@ -49,6 +51,26 @@ Ensure you have Python 3.8 or higher installed to meet the compatibility require
 
 - **Built-in Logging and Monitoring**: Integrated logging tracks message flows and system activity, providing valuable insights during development and troubleshooting phases.
 
+### Model Context Protocol (MCP) Integration
+
+- **Per-agent MCP tool catalogs**: Each agent can declare its own list of MCP servers. Tools discovered from those servers are automatically surfaced through the AgentKit functions registry, allowing LLM-driven planners to call them like any other function.
+- **Namespace isolation**: Tools are exposed using a `<server>::<tool>` naming convention so that specialized agents can connect to different MCP stacks without name collisions.
+- **Powered by the official SDK**: AgentKit now depends on the `mcp` package, ensuring first-class support for the Model Context Protocol standard and future enhancements.
+
+Sample snippet from an agent configuration:
+
+```json
+"mcp_servers": [
+  {
+    "name": "filesystem",
+    "transport": "stdio",
+    "command": "python",
+    "args": ["-m", "mcp_servers.fs"],
+    "namespace": "fs"
+  }
+]
+```
+
 ## Why AgentKit?
 
 AgentKit simplifies the creation and management of networked agent systems, making it an invaluable tool for a variety of innovative applications:
@@ -73,6 +95,70 @@ Aids in the simulation and modeling of complex systems to facilitate research an
 
 Refer to the `examples` directory to see a simple chat agent implementation. Comprehensive documentation will be provided soon!
 
+### Using the AgentRunner Utility
+
+For simplified agent creation and lifecycle management, AgentKit provides the `AgentRunner` utility:
+
+```python
+import asyncio
+from pathlib import Path
+from agentkit.utils import AgentRunner
+
+async def main():
+    runner = AgentRunner(
+        name="Julia",
+        description="A friendly AI assistant",
+        model="ollama/qwen3",
+        agent_home=str(Path("agentkit/examples/agent_homes/Julia").resolve())
+    )
+    
+    await runner.run()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+This utility handles:
+- Agent creation with sensible defaults
+- Message receiver setup and registration
+- Signal handling for graceful shutdown
+- Proper resource cleanup
+
+TODO: Add more examples of AgentRunner configuration options
+
+### Agent Home Convention
+
+AgentKit now uses a per-agent home directory for durable state, working files, and prompt instructions.
+
+Each configured agent must provide `agent_home`, and that directory must contain an `AGENTS.md` file. The content of `AGENTS.md` is loaded as the system prompt.
+
+Expected layout:
+
+```text
+<agent_home>/
+  AGENTS.md
+  state/
+  tasks/
+  workspace/
+  logs/
+```
+
+The runtime ensures these subdirectories exist when the agent is loaded.
+
+Example `sophia_task_agent.json`:
+
+```json
+{
+  "name": "Sophia",
+  "description": "A thoughtful task-aware assistant who can plan, delegate, and execute tools.",
+  "agent_home": "../agent_homes/Sophia",
+  "model": "ollama/qwen3-coder:480b-cloud",
+  "planner_model": "ollama/qwen3-coder:480b-cloud",
+  "user_prompt": "Conversation history:\n{context}\nSophia:",
+  "bus_ip": "127.0.0.1"
+}
+```
+
 ## Documentation
 
 Still in the works. Refer to the source docstrings for documentation for now.
@@ -97,7 +183,7 @@ To run a chat bot agent that utilizes the Data Bub for sending and receiving mes
    Ensure you have the latest version of the example files from the `examples` directory.
 
 2. **Configure the Agent**:
-   Examine and modify the configuration file (`simple_chat.json`) to fit your setup. By default, the agent is configured to interact with [Ollama](https://ollama.com/) running on localhost.
+   Examine and modify the configuration file (`simple_chat.json`) to fit your setup. By default, the agent is configured to interact with [Ollama](https://ollama.com/) running on localhost. Ensure each agent has an `agent_home` path and that `AGENTS.md` exists there.
 
    Update the configuration settings for the model and identity as necessary. For using other LLMs like OpenAI's models, refer to the [Litellm documentation](https://docs.litellm.ai/docs/) for details on specifying API keys and model settings.
 
@@ -118,7 +204,17 @@ To interact with the LLM-powered chat bot above, launch the agent with the human
    python ./config_agent.py --config ./config/human_agent.json --loglevel WARN
    ```
 
-   Once the command line prompt appears, begin typing your messages. The chat bot will respond according to the capabilities defined in its configuration.
+   Once the prompt appears, you can use a multi-agent chat-room style interface:
+
+   - Plain text sends to the current channel (broadcast as `ALL`)
+   - `/join <channel>` switches channels (default `#general`)
+   - `/dm <agent> <message>` sends a direct message
+   - `/reply <message>` replies to the most recent sender
+   - `/agents` lists discovered agents
+   - `/history [N]` shows recent timeline entries
+   - `/help` shows all commands
+
+   Japanese input/output is supported out of the box (UTF-8).
 
 ## Further Assistance
 

{agentkit-0.0.2 → agentkit-0.0.4}/README.md

@@ -12,7 +12,7 @@ Install `AgentKit` using pip:
 pip install agentkit
 ```
 
-Ensure you have Python 3.8 or higher installed to meet the compatibility requirements.
+Ensure you have Python 3.10 or higher installed to meet the compatibility requirements.
 
 ## Features
 
@@ -24,6 +24,26 @@ Ensure you have Python 3.8 or higher installed to meet the compatibility require
 
 - **Built-in Logging and Monitoring**: Integrated logging tracks message flows and system activity, providing valuable insights during development and troubleshooting phases.
 
+### Model Context Protocol (MCP) Integration
+
+- **Per-agent MCP tool catalogs**: Each agent can declare its own list of MCP servers. Tools discovered from those servers are automatically surfaced through the AgentKit functions registry, allowing LLM-driven planners to call them like any other function.
+- **Namespace isolation**: Tools are exposed using a `<server>::<tool>` naming convention so that specialized agents can connect to different MCP stacks without name collisions.
+- **Powered by the official SDK**: AgentKit now depends on the `mcp` package, ensuring first-class support for the Model Context Protocol standard and future enhancements.
+
+Sample snippet from an agent configuration:
+
+```json
+"mcp_servers": [
+  {
+    "name": "filesystem",
+    "transport": "stdio",
+    "command": "python",
+    "args": ["-m", "mcp_servers.fs"],
+    "namespace": "fs"
+  }
+]
+```
+
 ## Why AgentKit?
 
 AgentKit simplifies the creation and management of networked agent systems, making it an invaluable tool for a variety of innovative applications:
@@ -48,6 +68,70 @@ Aids in the simulation and modeling of complex systems to facilitate research an
 
 Refer to the `examples` directory to see a simple chat agent implementation. Comprehensive documentation will be provided soon!
 
+### Using the AgentRunner Utility
+
+For simplified agent creation and lifecycle management, AgentKit provides the `AgentRunner` utility:
+
+```python
+import asyncio
+from pathlib import Path
+from agentkit.utils import AgentRunner
+
+async def main():
+    runner = AgentRunner(
+        name="Julia",
+        description="A friendly AI assistant",
+        model="ollama/qwen3",
+        agent_home=str(Path("agentkit/examples/agent_homes/Julia").resolve())
+    )
+    
+    await runner.run()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+This utility handles:
+- Agent creation with sensible defaults
+- Message receiver setup and registration
+- Signal handling for graceful shutdown
+- Proper resource cleanup
+
+TODO: Add more examples of AgentRunner configuration options
+
+### Agent Home Convention
+
+AgentKit now uses a per-agent home directory for durable state, working files, and prompt instructions.
+
+Each configured agent must provide `agent_home`, and that directory must contain an `AGENTS.md` file. The content of `AGENTS.md` is loaded as the system prompt.
+
+Expected layout:
+
+```text
+<agent_home>/
+  AGENTS.md
+  state/
+  tasks/
+  workspace/
+  logs/
+```
+
+The runtime ensures these subdirectories exist when the agent is loaded.
+
+Example `sophia_task_agent.json`:
+
+```json
+{
+  "name": "Sophia",
+  "description": "A thoughtful task-aware assistant who can plan, delegate, and execute tools.",
+  "agent_home": "../agent_homes/Sophia",
+  "model": "ollama/qwen3-coder:480b-cloud",
+  "planner_model": "ollama/qwen3-coder:480b-cloud",
+  "user_prompt": "Conversation history:\n{context}\nSophia:",
+  "bus_ip": "127.0.0.1"
+}
+```
+
 ## Documentation
 
 Still in the works. Refer to the source docstrings for documentation for now.
@@ -72,7 +156,7 @@ To run a chat bot agent that utilizes the Data Bub for sending and receiving mes
    Ensure you have the latest version of the example files from the `examples` directory.
 
 2. **Configure the Agent**:
-   Examine and modify the configuration file (`simple_chat.json`) to fit your setup. By default, the agent is configured to interact with [Ollama](https://ollama.com/) running on localhost.
+   Examine and modify the configuration file (`simple_chat.json`) to fit your setup. By default, the agent is configured to interact with [Ollama](https://ollama.com/) running on localhost. Ensure each agent has an `agent_home` path and that `AGENTS.md` exists there.
 
    Update the configuration settings for the model and identity as necessary. For using other LLMs like OpenAI's models, refer to the [Litellm documentation](https://docs.litellm.ai/docs/) for details on specifying API keys and model settings.
 
@@ -93,7 +177,17 @@ To interact with the LLM-powered chat bot above, launch the agent with the human
    python ./config_agent.py --config ./config/human_agent.json --loglevel WARN
    ```
 
-   Once the command line prompt appears, begin typing your messages. The chat bot will respond according to the capabilities defined in its configuration.
+   Once the prompt appears, you can use a multi-agent chat-room style interface:
+
+   - Plain text sends to the current channel (broadcast as `ALL`)
+   - `/join <channel>` switches channels (default `#general`)
+   - `/dm <agent> <message>` sends a direct message
+   - `/reply <message>` replies to the most recent sender
+   - `/agents` lists discovered agents
+   - `/history [N]` shows recent timeline entries
+   - `/help` shows all commands
+
+   Japanese input/output is supported out of the box (UTF-8).
 
 ## Further Assistance
 

{agentkit-0.0.2 → agentkit-0.0.4}/agentkit/agents/agent_manager.py

@@ -10,6 +10,7 @@ from typing import Any, Dict, List, Optional
 from networkkit.network import ZMQMessageReceiver
 from agentkit.agents.simple_agent_factory import simple_agent_factory
 from networkkit.messages import Message
+from agentkit.utils.agent_home import apply_agent_home_convention
 
 class AgentManager:
     """
@@ -35,6 +36,7 @@ class AgentManager:
         try:
             with open(config_file, 'r') as f:
                 config = json.load(f)
+            config["_config_dir"] = str(config_file.parent.resolve())
             return config
         except json.JSONDecodeError as e:
             logging.error(f"Error parsing configuration file: {e}")
@@ -69,19 +71,44 @@ class AgentManager:
 
         for agent_conf in agents_config:
             try:
+                config_dir = Path(self.config.get("_config_dir", ".")).resolve()
+                resolved_conf = apply_agent_home_convention(
+                    agent_conf,
+                    config_dir=config_dir,
+                )
+                # Extract required parameters
+                name = resolved_conf["name"]
+                description = resolved_conf["description"]
+                model = resolved_conf["model"]
+                
+                # Extract optional parameters with defaults
+                agent_type = resolved_conf.get("agent_type", "SimpleAgent")
+                brain_type = resolved_conf.get("brain_type", "SimpleBrain")
+                memory_type = resolved_conf.get("memory_type", "SimpleMemory")
+                system_prompt = resolved_conf.get("system_prompt", "")
+                user_prompt = resolved_conf.get("user_prompt", "")
+                api_config = resolved_conf.get("api_config")
+                agent_home = resolved_conf.get("agent_home")
+                plugins_dir = self.config.get("plugins_dir", "plugins")
+                
+                # Create agent with extracted parameters
                 agent = simple_agent_factory(
-                    name=agent_conf["name"],
-                    description=agent_conf["description"],
-                    model=agent_conf["model"],
-                    system_prompt=agent_conf.get("system_prompt", ""),
-                    user_prompt=agent_conf.get("user_prompt", ""),
-                    agent_type=agent_conf.get("agent_type", "SimpleAgent"),
-                    brain_type=agent_conf.get("brain_type", "SimpleBrain"),
+                    name=name,
+                    description=description,
+                    model=model,
+                    system_prompt=system_prompt,
+                    user_prompt=user_prompt,
+                    agent_type=agent_type,
+                    brain_type=brain_type,
+                    memory_type=memory_type,
+                    plugins_dir=plugins_dir,
                     bus_ip=bus_ip,
-                    api_config=agent_conf.get("api_config")
+                    api_config=api_config,
+                    agent_home=agent_home,
+                    config_dir=str(config_dir),
                 )
                 self.agents.append(agent)
-                logging.info(f"Loaded agent: {agent_conf['name']}")
+                logging.info(f"Loaded agent: {name}")
             except KeyError as e:
                 logging.error(f"Missing required agent configuration parameter: {e}")
             except Exception as e: