Skip to content

Agent Zero AI framework

feat: embedded MCP server for messaging with agent-zero

Rafael Uzarowski6beb4ec939a2
diff --git a/agent.py b/agent.py
index fad78a423..8096cc1ee 100644
--- a/agent.py
+++ b/agent.py
@@ -1,8 +1,9 @@
import asyncio
from collections import OrderedDict
from dataclasses import dataclass, field
-from datetime import datetime
+from datetime import datetime, timezone
from typing import Any, Awaitable, Coroutine, Optional, Dict, TypedDict
+from enum import Enum
import uuid
import models
@@ -20,6 +21,12 @@ from typing import Callable
from python.helpers.localization import Localization
+class AgentContextType(Enum):
+ USER = "user"
+ TASK = "task"
+ MCP = "mcp"
+
+
class AgentContext:
_contexts: dict[str, "AgentContext"] = {}
@@ -35,6 +42,8 @@ class AgentContext:
paused: bool = False,
streaming_agent: "Agent|None" = None,
created_at: datetime | None = None,
+ type: AgentContextType = AgentContextType.USER,
+ last_message: datetime | None = None,
):
# build context
self.id = id or str(uuid.uuid4())
@@ -45,9 +54,12 @@ class AgentContext:
self.paused = paused
self.streaming_agent = streaming_agent
self.task: DeferredTask | None = None
- self.created_at = created_at or datetime.now()
+ self.created_at = created_at or datetime.now(timezone.utc)
+ self.type = type
AgentContext._counter += 1
self.no = AgentContext._counter
+ # set to start of unix epoch
+ self.last_message = last_message or datetime.now(timezone.utc)
existing = self._contexts.get(self.id, None)
if existing:
@@ -84,6 +96,11 @@ class AgentContext:
"log_version": len(self.log.updates),
"log_length": len(self.log.logs),
"paused": self.paused,
+ "last_message": (
+ Localization.get().serialize_datetime(self.last_message)
+ if self.last_message else Localization.get().serialize_datetime(datetime.fromtimestamp(0))
+ ),
+ "type": self.type.value,
}
def get_created_at(self):
@@ -468,6 +485,7 @@ class Agent:
def hist_add_message(
self, ai: bool, content: history.MessageContent, tokens: int = 0
):
+ self.last_message = datetime.now(timezone.utc)
return self.history.add_message(ai=ai, content=content, tokens=tokens)
def hist_add_user_message(self, message: UserMessage, intervention: bool = False):
diff --git a/python/helpers/job_loop.py b/python/helpers/job_loop.py
index c4c2d2fbe..47ddae033 100644
--- a/python/helpers/job_loop.py
+++ b/python/helpers/job_loop.py
@@ -2,19 +2,41 @@ import asyncio
from python.helpers.task_scheduler import TaskScheduler
from python.helpers.print_style import PrintStyle
from python.helpers import errors
+from agent import AgentContext, AgentContextType
+from datetime import datetime, timezone, timedelta
+from python.helpers.persist_chat import remove_chat
async def run_loop():
while True:
+ # scheduler tick
try:
await scheduler_tick()
except Exception as e:
PrintStyle().error(errors.format_error(e))
- await asyncio.sleep(60) # TODO! - if we lower it under 1min, it can run a 5min job multiple times in it's target minute
+
+ # cleanup tmp chats
+ try:
+ await cleanup_tmp_chats()
+ except Exception as e:
+ PrintStyle().error(errors.format_error(e))
+
+ await asyncio.sleep(60) # TODO! - if we lower it under 1min, it can run a 5min job multiple times in it's target minute
async def scheduler_tick():
# Get the task scheduler instance and print detailed debug info
scheduler = TaskScheduler.get()
# Run the scheduler tick
- await scheduler.tick()
\ No newline at end of file
+ await scheduler.tick()
+
+
+async def cleanup_tmp_chats():
+ contexts = list(AgentContext._contexts.values())
+ for context in contexts:
+ if context.type == AgentContextType.MCP:
+ if context.last_message < datetime.now(timezone.utc) - timedelta(hours=1):
+ PrintStyle().debug(f"MCP chat {context.id} - {context.last_message} - cleaning up")
+ context.reset()
+ AgentContext.remove(context.id)
+ remove_chat(context.id)
diff --git a/python/helpers/mcp_server.py b/python/helpers/mcp_server.py
new file mode 100644
index 000000000..5356f79d9
--- /dev/null
+++ b/python/helpers/mcp_server.py
@@ -0,0 +1,213 @@
+from asyncio import current_task
+import os
+from typing import Annotated, Literal, Union
+from urllib.parse import urlparse
+from openai import BaseModel
+from pydantic import Field
+import uuid
+import asyncio
+from fastmcp import FastMCP
+
+from agent import AgentContext, AgentContextType, UserMessage
+from python.helpers.persist_chat import save_tmp_chat, remove_chat
+from initialize import initialize
+from python.helpers.print_style import PrintStyle
+from python.helpers.task_scheduler import DeferredTask
+
+_PRINTER = PrintStyle(italic=True, font_color="green", padding=False)
+
+
+mcp_server: FastMCP = FastMCP(
+ name="Agent Zero integrated MCP Server",
+ instructions="""
+ This server connects you to the Agent Zero instance running on the remote server.
+ It exposes tools to interact with the remote Agent Zero instance.
+ """,
+)
+
+
+class ToolResponse(BaseModel):
+ status: Literal["success"] = Field(description="The status of the response", default="success")
+ response: str = Field(description="The response from the remote Agent Zero Instance")
+ chat_id: str = Field(description="The id of the chat this message belongs to.")
+
+
+class ToolError(BaseModel):
+ status: Literal["error"] = Field(description="The status of the response", default="error")
+ error: str = Field(description="The error message from the remote Agent Zero Instance")
+ chat_id: str = Field(description="The id of the chat this message belongs to.")
+
+
+SEND_MESSAGE_DESCRIPTION = """
+Send a message to the remote Agent Zero Instance.
+This tool is used to send a message to the remote Agent Zero Instance connected remotely via MCP.
+"""
+
+
+@mcp_server.tool(
+ name="send_message",
+ description=SEND_MESSAGE_DESCRIPTION,
+ tags={"agent_zero", "chat", "remote", "communication", "dialogue", "sse", "send", "message", "start", "new", "continue"},
+ annotations={
+ "remote": True,
+ "readOnlyHint": False,
+ "destructiveHint": False,
+ "idempotentHint": False,
+ "openWorldHint": False,
+ "title": SEND_MESSAGE_DESCRIPTION,
+ },
+)
+async def send_message(
+ message: Annotated[str, Field(description="The message to send to the remote Agent Zero Instance", title="message")],
+ attachments: Annotated[list[str], Field(
+ description="Optional: A list of attachments (file paths or web urls) to send to the remote Agent Zero Instance with the message. Default: Empty list",
+ title="attachments",
+ )] | None = None,
+ chat_id: Annotated[str, Field(
+ description="Optional: ID of the chat. Used to continue a chat. This value is returned in response to sending previous message. Default: Empty string",
+ title="chat_id",
+ )] | None = None,
+ persistent_chat: Annotated[bool, Field(
+ description="Optional: Whether to use a persistent chat. If true, the chat will be saved and can be continued later. Default: False.",
+ title="persistent_chat",
+ )] | None = None,
+) -> Annotated[Union[ToolResponse, ToolError], Field(description="The response from the remote Agent Zero Instance", title="response")]:
+ context: AgentContext | None = None
+ if chat_id:
+ context = AgentContext.get(chat_id)
+ if not context:
+ return ToolError(error="Chat not found", chat_id=chat_id)
+ else:
+ # If the chat is found, we use the persistent chat flag to determine
+ # whether we should save the chat or delete it afterwards
+ # If we continue a conversation, it must be persistent
+ persistent_chat = True
+ else:
+ config = initialize()
+ context = AgentContext(config=config, type=AgentContextType.MCP)
+
+ if not message:
+ return ToolError(error="Message is required", chat_id=context.id if persistent_chat else "")
+
+ try:
+ response = await _run_chat(context, message, attachments)
+ if not persistent_chat:
+ context.reset()
+ AgentContext.remove(context.id)
+ remove_chat(context.id)
+ return ToolResponse(response=response, chat_id=context.id if persistent_chat else "")
+ except Exception as e:
+ return ToolError(error=str(e), chat_id=context.id if persistent_chat else "")
+
+
+FINISH_CHAT_DESCRIPTION = """
+Finish a chat with the remote Agent Zero Instance.
+This tool is used to finish a persistent chat (send_message with persistent_chat=True) with the remote Agent Zero Instance connected remotely via MCP.
+If you want to continue the chat, use the send_message tool instead.
+Always use this tool to finish persistent chat conversations with remote Agent Zero.
+"""
+
+
+@mcp_server.tool(
+ name="finish_chat",
+ description=FINISH_CHAT_DESCRIPTION,
+ tags={"agent_zero", "chat", "remote", "communication", "dialogue", "sse", "finish", "close", "end", "stop"},
+ annotations={
+ "remote": True,
+ "readOnlyHint": False,
+ "destructiveHint": True,
+ "idempotentHint": False,
+ "openWorldHint": False,
+ "title": FINISH_CHAT_DESCRIPTION,
+ },
+)
+async def finish_chat(
+ chat_id: Annotated[str, Field(
+ description="ID of the chat to be finished. This value is returned in response to sending previous message.",
+ title="chat_id",
+ )]
+) -> Annotated[Union[ToolResponse, ToolError], Field(description="The response from the remote Agent Zero Instance", title="response")]:
+ if not chat_id:
+ return ToolError(error="Chat ID is required", chat_id="")
+
+ context = AgentContext.get(chat_id)
+ if not context:
+ return ToolError(error="Chat not found", chat_id=chat_id)
+ else:
+ context.reset()
+ AgentContext.remove(context.id)
+ remove_chat(context.id)
+ return ToolResponse(response="Chat finished", chat_id=chat_id)
+
+
+async def _run_chat(context: AgentContext, message: str, attachments: list[str] | None = None):
+ async def _run_chat_wrapper(context: AgentContext, message: str, attachments: list[str] | None = None):
+ # the agent instance - init in try block
+ agent = None
+
+ try:
+ _PRINTER.print("MCP Chat message received")
+
+ agent = context.streaming_agent or context.agent0
+
+ # Pcurrent_taskhment filenames for logging
+ attachment_filenames = []
+ if attachments:
+ for attachment in attachments:
+ if os.path.exists(attachment):
+ attachment_filenames.append(attachment)
+ else:
+ try:
+ url = urlparse(attachment)
+ if url.scheme in ["http", "https", "ftp", "ftps", "sftp"]:
+ attachment_filenames.append(attachment)
+ else:
+ _PRINTER.print(f"Skipping attachment: [{attachment}]")
+ except Exception:
+ _PRINTER.print(f"Skipping attachment: [{attachment}]")
+
+ _PRINTER.print("User message:")
+ _PRINTER.print(f"> {message}")
+ if attachment_filenames:
+ _PRINTER.print("Attachments:")
+ for filename in attachment_filenames:
+ _PRINTER.print(f"- {filename}")
+
+ # Log the message with message_id and attachments
+ context.log.log(
+ type="user",
+ heading="User message",
+ content=message,
+ kvps={"attachments": attachment_filenames},
+ id=str(uuid.uuid4()),
+ )
+
+ agent.hist_add_user_message(
+ UserMessage(
+ message=message,
+ system_message=[],
+ attachments=attachment_filenames))
+
+ # Persist after setting up the context but before running the agent
+ save_tmp_chat(context)
+
+ result = await agent.monologue()
+
+ # Success
+ _PRINTER.print(f"MCP Chat message completed: {result}")
+ save_tmp_chat(context)
+
+ return result
+
+ except Exception as e:
+ # Error
+ _PRINTER.print(f"MCP Chat message failed: {e}")
+ if agent:
+ agent.handle_critical_exception(e)
+
+ raise RuntimeError(f"MCP Chat message failed: {e}") from e
+
+ deferred_task = DeferredTask(thread_name="mcp_chat_" + context.id)
+ deferred_task.start_task(_run_chat_wrapper, context, message, attachments)
+ asyncio.create_task(asyncio.sleep(0.1)) # Ensure background execution doesn't exit immediately on async await
+ return await deferred_task.result()
diff --git a/python/helpers/persist_chat.py b/python/helpers/persist_chat.py
index 3c3356a34..668bcc833 100644
--- a/python/helpers/persist_chat.py
+++ b/python/helpers/persist_chat.py
@@ -2,7 +2,7 @@ from collections import OrderedDict
from datetime import datetime
from typing import Any
import uuid
-from agent import Agent, AgentConfig, AgentContext
+from agent import Agent, AgentConfig, AgentContext, AgentContextType
from python.helpers import files, history
import json
from initialize import initialize
@@ -109,6 +109,11 @@ def _serialize_context(context: AgentContext):
context.created_at.isoformat() if context.created_at
else datetime.fromtimestamp(0).isoformat()
),
+ "type": context.type.value,
+ "last_message": (
+ context.last_message.isoformat() if context.last_message
+ else datetime.fromtimestamp(0).isoformat()
+ ),
"agents": agents,
"streaming_agent": (
context.streaming_agent.number if context.streaming_agent else 0
@@ -154,6 +159,12 @@ def _deserialize_context(data):
data.get("created_at", datetime.fromtimestamp(0).isoformat())
)
),
+ type=AgentContextType(data.get("type", AgentContextType.USER.value)),
+ last_message=(
+ datetime.fromisoformat(
+ data.get("last_message", datetime.fromtimestamp(0).isoformat())
+ )
+ ),
log=log,
paused=False,
# agent0=agent0,
diff --git a/requirements.txt b/requirements.txt
index a2cb4d1f1..06b24bff9 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -24,7 +24,7 @@ newspaper3k==0.2.8
paramiko==3.5.0
playwright==1.52.0
pypdf==4.3.1
-python-dotenv==1.0.1
+python-dotenv==1.1.0
pytz==2024.2
sentence-transformers==3.0.1
tiktoken==0.8.0
@@ -32,3 +32,6 @@ unstructured==0.15.13
unstructured-client==0.25.9
webcolors==24.6.0
crontab==1.0.1
+fastmcp==2.3.4
+mcp==1.9.0
+a2wsgi==1.10.8
diff --git a/run_ui.py b/run_ui.py
index 8d164d9a4..6f75d975f 100644
--- a/run_ui.py
+++ b/run_ui.py
@@ -20,19 +20,20 @@ from python.helpers.print_style import PrintStyle
from python.helpers.task_scheduler import TaskScheduler
from python.helpers.defer import DeferredTask
+
# Set the new timezone to 'UTC'
os.environ["TZ"] = "UTC"
# Apply the timezone change
time.tzset()
# initialize the internal Flask server
-app = Flask("app", static_folder=get_abs_path("./webui"), static_url_path="/")
-app.config["JSON_SORT_KEYS"] = False # Disable key sorting in jsonify
+webapp = Flask("app", static_folder=get_abs_path("./webui"), static_url_path="/")
+webapp.config["JSON_SORT_KEYS"] = False # Disable key sorting in jsonify
lock = threading.Lock()
-# Set up basic authentication
-basic_auth = BasicAuth(app)
+# Set up basic authentication for UI and API but not MCP
+basic_auth = BasicAuth(webapp)
def is_loopback_address(address):
@@ -123,7 +124,7 @@ def requires_auth(f):
# handle default address, load index
[email protected]("/", methods=["GET"])
[email protected]("/", methods=["GET"])
@requires_auth
async def serve_index():
gitinfo = None
@@ -147,6 +148,10 @@ def run():
# Suppress only request logs but keep the startup messages
from werkzeug.serving import WSGIRequestHandler
from werkzeug.serving import make_server
+ from werkzeug.middleware.dispatcher import DispatcherMiddleware
+ from a2wsgi import ASGIMiddleware, WSGIMiddleware
+ from fastmcp.server.http import create_sse_app
+ from python.helpers.mcp_server import mcp_server as mcp_server_instance
PrintStyle().print("Starting job loop...")
job_loop = DeferredTask().start_task(run_loop)
@@ -227,9 +232,28 @@ def run():
# initialize and register API handlers
handlers = load_classes_from_folder("python/api", "*.py", ApiHandler)
for handler in handlers:
- register_api_handler(app, handler)
+ register_api_handler(webapp, handler)
+
+ mcp_app = create_sse_app(
+ server=mcp_server_instance,
+ message_path=mcp_server_instance.settings.message_path,
+ sse_path=mcp_server_instance.settings.sse_path,
+ auth_server_provider=mcp_server_instance._auth_server_provider,
+ auth_settings=mcp_server_instance.settings.auth,
+ debug=mcp_server_instance.settings.debug,
+ routes=mcp_server_instance._additional_http_routes,
+ middleware=None
+ )
+
+ # add the webapp and mcp to the app
+ app = DispatcherMiddleware(webapp, {
+ "/mcp": ASGIMiddleware(app=mcp_app),
+ })
+ PrintStyle().debug("Registered middleware for MCP")
try:
+ PrintStyle().debug(f"Starting server at {host}:{port}...")
+
server = make_server(
host=host,
port=port,
@@ -259,10 +283,6 @@ def run():
process.set_server(server)
server.log_startup()
server.serve_forever()
- # Run Flask app
- # app.run(
- # request_handler=NoRequestLoggingWSGIRequestHandler, port=port, host=host
- # )
finally:
# Clean up tunnel if it was started
if tunnel: