Agent Zero AI framework
feat: External API Endpoints
Rafael Uzarowskie74dabb40ac9
diff --git a/python/api/api_files_get.py b/python/api/api_files_get.pynew file mode 100644index 000000000..e021af60f--- /dev/null+++ b/python/api/api_files_get.py@@ -0,0 +1,95 @@+import base64+import os+from python.helpers.api import ApiHandler, Request, Response+from python.helpers import files+from python.helpers.print_style import PrintStyle+import json+++class ApiFilesGet(ApiHandler):+ @classmethod+ def requires_auth(cls) -> bool:+ return False++ @classmethod+ def requires_csrf(cls) -> bool:+ return False++ @classmethod+ def requires_api_key(cls) -> bool:+ return True++ @classmethod+ def get_methods(cls) -> list[str]:+ return ["POST"]++ async def process(self, input: dict, request: Request) -> dict | Response:+ try:+ # Get paths from input+ paths = input.get("paths", [])++ if not paths:+ return Response(+ '{"error": "paths array is required"}',+ status=400,+ mimetype="application/json"+ )++ if not isinstance(paths, list):+ return Response(+ '{"error": "paths must be an array"}',+ status=400,+ mimetype="application/json"+ )++ result = {}++ for path in paths:+ try:+ # Convert internal paths to external paths+ if path.startswith("/a0/tmp/uploads/"):+ # Internal path - convert to external+ filename = path.replace("/a0/tmp/uploads/", "")+ external_path = files.get_abs_path("tmp/uploads", filename)+ filename = os.path.basename(external_path)+ elif path.startswith("/a0/"):+ # Other internal Agent Zero paths+ relative_path = path.replace("/a0/", "")+ external_path = files.get_abs_path(relative_path)+ filename = os.path.basename(external_path)+ else:+ # Assume it's already an external/absolute path+ external_path = path+ filename = os.path.basename(path)++ # Check if file exists+ if not os.path.exists(external_path):+ PrintStyle.warning(f"File not found: {path}")+ continue++ # Read and encode file+ with open(external_path, "rb") as f:+ file_content = f.read()+ base64_content = base64.b64encode(file_content).decode('utf-8')+ result[filename] = base64_content++ PrintStyle().print(f"Retrieved file: {filename} ({len(file_content)} bytes)")++ except Exception as e:+ PrintStyle.error(f"Failed to read file {path}: {str(e)}")+ continue++ # Log the retrieval+ PrintStyle(+ background_color="#2ECC71", font_color="white", bold=True, padding=True+ ).print(f"API Files retrieved: {len(result)} files")++ return result++ except Exception as e:+ PrintStyle.error(f"API files get error: {str(e)}")+ return Response(+ json.dumps({"error": f"Internal server error: {str(e)}"}),+ status=500,+ mimetype="application/json"+ )diff --git a/python/api/api_log_get.py b/python/api/api_log_get.pynew file mode 100644index 000000000..c09fdfdc0--- /dev/null+++ b/python/api/api_log_get.py@@ -0,0 +1,64 @@+from agent import AgentContext+from python.helpers.api import ApiHandler, Request, Response+++class ApiLogGet(ApiHandler):+ @classmethod+ def get_methods(cls) -> list[str]:+ return ["GET", "POST"]++ @classmethod+ def requires_auth(cls) -> bool:+ return False # No web auth required++ @classmethod+ def requires_csrf(cls) -> bool:+ return False # No CSRF required++ @classmethod+ def requires_api_key(cls) -> bool:+ return True # Require API key++ async def process(self, input: dict, request: Request) -> dict | Response:+ # Extract parameters (support both query params for GET and body for POST)+ if request.method == "GET":+ context_id = request.args.get("context_id", "")+ length = int(request.args.get("length", 100))+ else:+ context_id = input.get("context_id", "")+ length = input.get("length", 100)++ if not context_id:+ return Response('{"error": "context_id is required"}', status=400, mimetype="application/json")++ # Get context+ context = AgentContext.get(context_id)+ if not context:+ return Response('{"error": "Context not found"}', status=404, mimetype="application/json")++ try:+ # Get total number of log items+ total_items = len(context.log.logs)++ # Calculate start position (from newest, so we work backwards)+ start_pos = max(0, total_items - length)++ # Get log items from the calculated start position+ log_items = context.log.output(start=start_pos)++ # Return log data with metadata+ return {+ "context_id": context_id,+ "log": {+ "guid": context.log.guid,+ "total_items": total_items,+ "returned_items": len(log_items),+ "start_position": start_pos,+ "progress": context.log.progress,+ "progress_active": context.log.progress_active,+ "items": log_items+ }+ }++ except Exception as e:+ return Response(f'{{"error": "{str(e)}"}}', status=500, mimetype="application/json")diff --git a/python/api/api_message.py b/python/api/api_message.pynew file mode 100644index 000000000..4d3248c60--- /dev/null+++ b/python/api/api_message.py@@ -0,0 +1,140 @@+import base64+import os+from datetime import datetime, timedelta+from agent import AgentContext, UserMessage, AgentContextType+from python.helpers.api import ApiHandler, Request, Response+from python.helpers import files+from python.helpers.print_style import PrintStyle+from werkzeug.utils import secure_filename+from initialize import initialize_agent+import threading+++class ApiMessage(ApiHandler):+ # Track chat lifetimes for cleanup+ _chat_lifetimes = {}+ _cleanup_lock = threading.Lock()++ @classmethod+ def requires_auth(cls) -> bool:+ return False # No web auth required++ @classmethod+ def requires_csrf(cls) -> bool:+ return False # No CSRF required++ @classmethod+ def requires_api_key(cls) -> bool:+ return True # Require API key++ async def process(self, input: dict, request: Request) -> dict | Response:+ # Extract parameters+ context_id = input.get("context_id", "")+ message = input.get("message", "")+ attachments = input.get("attachments", [])+ lifetime_hours = input.get("lifetime_hours", 24) # Default 24 hours++ if not message:+ return Response('{"error": "Message is required"}', status=400, mimetype="application/json")++ # Handle attachments (base64 encoded)+ attachment_paths = []+ if attachments:+ upload_folder_int = "/a0/tmp/uploads"+ upload_folder_ext = files.get_abs_path("tmp/uploads")+ os.makedirs(upload_folder_ext, exist_ok=True)++ for attachment in attachments:+ if not isinstance(attachment, dict) or "filename" not in attachment or "base64" not in attachment:+ continue++ try:+ filename = secure_filename(attachment["filename"])+ if not filename:+ continue++ # Decode base64 content+ file_content = base64.b64decode(attachment["base64"])++ # Save to temp file+ save_path = os.path.join(upload_folder_ext, filename)+ with open(save_path, "wb") as f:+ f.write(file_content)++ attachment_paths.append(os.path.join(upload_folder_int, filename))+ except Exception as e:+ PrintStyle.error(f"Failed to process attachment {attachment.get('filename', 'unknown')}: {e}")+ continue++ # Get or create context+ if context_id:+ context = AgentContext.get(context_id)+ if not context:+ return Response('{"error": "Context not found"}', status=404, mimetype="application/json")+ else:+ config = initialize_agent()+ context = AgentContext(config=config, type=AgentContextType.USER)+ context_id = context.id++ # Update chat lifetime+ with self._cleanup_lock:+ self._chat_lifetimes[context_id] = datetime.now() + timedelta(hours=lifetime_hours)++ # Process message+ try:+ # Log the message+ attachment_filenames = [os.path.basename(path) for path in attachment_paths] if attachment_paths else []++ PrintStyle(+ background_color="#6C3483", font_color="white", bold=True, padding=True+ ).print("External API message:")+ PrintStyle(font_color="white", padding=False).print(f"> {message}")+ if attachment_filenames:+ PrintStyle(font_color="white", padding=False).print("Attachments:")+ for filename in attachment_filenames:+ PrintStyle(font_color="white", padding=False).print(f"- {filename}")++ # Add user message to chat history so it's visible in the UI+ context.log.log(+ type="user",+ heading="User message",+ content=message,+ kvps={"attachments": attachment_filenames},+ )++ # Send message to agent+ task = context.communicate(UserMessage(message, attachment_paths))+ result = await task.result()++ # Clean up expired chats+ self._cleanup_expired_chats()++ return {+ "context_id": context_id,+ "response": result+ }++ except Exception as e:+ PrintStyle.error(f"External API error: {e}")+ return Response(f'{{"error": "{str(e)}"}}', status=500, mimetype="application/json")++ @classmethod+ def _cleanup_expired_chats(cls):+ """Clean up expired chats"""+ with cls._cleanup_lock:+ now = datetime.now()+ expired_contexts = [+ context_id for context_id, expiry in cls._chat_lifetimes.items()+ if now > expiry+ ]++ for context_id in expired_contexts:+ try:+ context = AgentContext.get(context_id)+ if context:+ context.reset()+ AgentContext.remove(context_id)+ del cls._chat_lifetimes[context_id]+ PrintStyle().print(f"Cleaned up expired chat: {context_id}")+ except Exception as e:+ PrintStyle.error(f"Failed to cleanup chat {context_id}: {e}")diff --git a/python/api/api_reset_chat.py b/python/api/api_reset_chat.pynew file mode 100644index 000000000..b497adb1e--- /dev/null+++ b/python/api/api_reset_chat.py@@ -0,0 +1,69 @@+from agent import AgentContext+from python.helpers.api import ApiHandler, Request, Response+from python.helpers.print_style import PrintStyle+from python.helpers import persist_chat+import json+++class ApiResetChat(ApiHandler):+ @classmethod+ def requires_auth(cls) -> bool:+ return False++ @classmethod+ def requires_csrf(cls) -> bool:+ return False++ @classmethod+ def requires_api_key(cls) -> bool:+ return True++ @classmethod+ def get_methods(cls) -> list[str]:+ return ["POST"]++ async def process(self, input: dict, request: Request) -> dict | Response:+ try:+ # Get context_id from input+ context_id = input.get("context_id")++ if not context_id:+ return Response(+ '{"error": "context_id is required"}',+ status=400,+ mimetype="application/json"+ )++ # Check if context exists+ context = AgentContext.get(context_id)+ if not context:+ return Response(+ '{"error": "Chat context not found"}',+ status=404,+ mimetype="application/json"+ )++ # Reset the chat context (clears history but keeps context alive)+ context.reset()+ # Save the reset context to persist the changes+ persist_chat.save_tmp_chat(context)++ # Log the reset+ PrintStyle(+ background_color="#3498DB", font_color="white", bold=True, padding=True+ ).print(f"API Chat reset: {context_id}")++ # Return success response+ return {+ "success": True,+ "message": "Chat reset successfully",+ "context_id": context_id+ }++ except Exception as e:+ PrintStyle.error(f"API reset chat error: {str(e)}")+ return Response(+ json.dumps({"error": f"Internal server error: {str(e)}"}),+ status=500,+ mimetype="application/json"+ )diff --git a/python/api/api_terminate_chat.py b/python/api/api_terminate_chat.pynew file mode 100644index 000000000..3d6bcb4b4--- /dev/null+++ b/python/api/api_terminate_chat.py@@ -0,0 +1,68 @@+from agent import AgentContext+from python.helpers.api import ApiHandler, Request, Response+from python.helpers.persist_chat import remove_chat+from python.helpers.print_style import PrintStyle+import json+++class ApiTerminateChat(ApiHandler):+ @classmethod+ def requires_auth(cls) -> bool:+ return False++ @classmethod+ def requires_csrf(cls) -> bool:+ return False++ @classmethod+ def requires_api_key(cls) -> bool:+ return True++ @classmethod+ def get_methods(cls) -> list[str]:+ return ["POST"]++ async def process(self, input: dict, request: Request) -> dict | Response:+ try:+ # Get context_id from input+ context_id = input.get("context_id")++ if not context_id:+ return Response(+ '{"error": "context_id is required"}',+ status=400,+ mimetype="application/json"+ )++ # Check if context exists+ context = AgentContext.get(context_id)+ if not context:+ return Response(+ '{"error": "Chat context not found"}',+ status=404,+ mimetype="application/json"+ )++ # Delete the chat context+ AgentContext.remove(context.id)+ remove_chat(context.id)++ # Log the deletion+ PrintStyle(+ background_color="#E74C3C", font_color="white", bold=True, padding=True+ ).print(f"API Chat deleted: {context_id}")++ # Return success response+ return {+ "success": True,+ "message": "Chat deleted successfully",+ "context_id": context_id+ }++ except Exception as e:+ PrintStyle.error(f"API terminate chat error: {str(e)}")+ return Response(+ json.dumps({"error": f"Internal server error: {str(e)}"}),+ status=500,+ mimetype="application/json"+ )diff --git a/python/helpers/settings.py b/python/helpers/settings.pyindex 4ea9a23eb..d0f80e537 100644--- a/python/helpers/settings.py+++ b/python/helpers/settings.py@@ -67,7 +67,7 @@ class Settings(TypedDict):memory_memorize_enabled: boolmemory_memorize_consolidation: boolmemory_memorize_replace_threshold: float-+api_keys: dict[str, str]@@ -880,7 +880,7 @@ def convert_out(settings: Settings) -> SettingsOutput:# TTS fieldstts_fields: list[SettingsField] = []-+tts_fields.append({"id": "tts_kokoro",@@ -982,6 +982,28 @@ def convert_out(settings: Settings) -> SettingsOutput:"tab": "mcp",}+ # External API section+ external_api_fields: list[SettingsField] = []++ external_api_fields.append(+ {+ "id": "external_api_examples",+ "title": "API Examples",+ "description": "View examples for using Agent Zero's external API endpoints with API key authentication.",+ "type": "button",+ "value": "Show API Examples",+ }+ )++ external_api_section: SettingsSection = {+ "id": "external_api",+ "title": "External API",+ "description": "Agent Zero provides external API endpoints for integration with other applications. "+ "These endpoints use API key authentication and support text messages and file attachments.",+ "fields": external_api_fields,+ "tab": "external",+ }+# Backup & Restore sectionbackup_fields: list[SettingsField] = []@@ -1030,6 +1052,7 @@ def convert_out(settings: Settings) -> SettingsOutput:auth_section,mcp_client_section,mcp_server_section,+ external_api_section,backup_section,dev_section,]diff --git a/run_ui.py b/run_ui.pyindex 07ae1c82f..0b1b80c97 100644--- a/run_ui.py+++ b/run_ui.py@@ -1,18 +1,15 @@from datetime import timedeltaimport osimport secrets-import sysimport timeimport socketimport structfrom functools import wrapsimport threading-import signal-from typing import overridefrom flask import Flask, request, Response, sessionfrom flask_basicauth import BasicAuthimport initialize-from python.helpers import errors, files, git, mcp_server+from python.helpers import files, git, mcp_serverfrom python.helpers.files import get_abs_pathfrom python.helpers import runtime, dotenv, processfrom python.helpers.extract_tools import load_classes_from_folder@@ -81,14 +78,17 @@ def is_loopback_address(address):def requires_api_key(f):@wraps(f)async def decorated(*args, **kwargs):- valid_api_key = dotenv.get_dotenv_value("API_KEY")+ # Use the auth token from settings (same as MCP server)+ from python.helpers.settings import get_settings+ valid_api_key = get_settings()["mcp_server_token"]+if api_key := request.headers.get("X-API-KEY"):if api_key != valid_api_key:- return Response("API key required", 401)+ return Response("Invalid API key", 401)elif request.json and request.json.get("api_key"):api_key = request.json.get("api_key")if api_key != valid_api_key:- return Response("API key required", 401)+ return Response("Invalid API key", 401)else:return Response("API key required", 401)return await f(*args, **kwargs)@@ -171,7 +171,7 @@ def run():from werkzeug.serving import WSGIRequestHandlerfrom werkzeug.serving import make_serverfrom werkzeug.middleware.dispatcher import DispatcherMiddleware- from a2wsgi import ASGIMiddleware, WSGIMiddleware+ from a2wsgi import ASGIMiddlewarePrintStyle().print("Starting server...")diff --git a/webui/components/settings/external/api-examples.html b/webui/components/settings/external/api-examples.htmlnew file mode 100644index 000000000..08569a1e9--- /dev/null+++ b/webui/components/settings/external/api-examples.html@@ -0,0 +1,678 @@+<html>++<head>+ <title>Agent Zero External API Examples</title>+</head>++<body>+ <div x-data>+ <p>Agent Zero provides external API endpoints for integration with other applications.</p>+ <p>These endpoints use API key authentication and support text messages and file attachments.</p>++ <!-- API Token Information -->+ <div style="background-color: var(--color-bg-secondary); border: 1px solid var(--color-border); border-radius: 6px; padding: 12px; margin: 16px 0;">+ <h4 style="margin: 0 0 8px 0; color: var(--color-text-primary);">API Token Information</h4>+ <p style="margin: 0; color: var(--color-text-secondary); font-size: 14px;">+ The API token is automatically generated from your username and password.+ This same token is used for both MCP server connections and external API endpoints.+ The token changes when you update your credentials.+ </p>+ </div>++ <!-- Section 1: api_message Endpoint -->+ <div class="api-section">+ <h2>POST /api_message</h2>+ <p style="margin: 0 0 16px 0; color: var(--color-text-secondary); font-size: 14px;">+ Send messages to Agent Zero and receive responses. Supports text messages, file attachments, and conversation continuity.+ </p>++ <!-- API Reference -->+ <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">API Reference</h3>+ <div style="background-color: var(--color-bg-secondary); border: 1px solid var(--color-border); border-radius: 6px; padding: 12px; margin: 0 0 20px 0;">+ <p style="margin: 0 0 8px 0; color: var(--color-text-secondary); font-size: 14px;">+ <strong>Parameters:</strong><br>+ • <code>context_id</code> (string, optional): Existing chat context ID<br>+ • <code>message</code> (string, required): The message to send<br>+ • <code>attachments</code> (array, optional): Array of {filename, base64} objects<br>+ • <code>lifetime_hours</code> (number, optional): Chat lifetime in hours (default: 24)+ </p>+ <p style="margin: 0; color: var(--color-text-secondary); font-size: 14px;">+ <strong>Headers:</strong> <code>X-API-KEY</code> (required), <code>Content-Type: application/json</code>+ </p>+ </div>++ <!-- JavaScript Examples -->+ <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">JavaScript Examples</h3>++ <h4>Basic Usage Example</h4>+ <div id="api-basic-example"></div>++ <h4>Conversation Continuation Example</h4>+ <div id="api-continuation-example"></div>++ <h4>File Attachment Example</h4>+ <div id="api-attachment-example"></div>+ </div>++ <!-- Section 2: api_log_get Endpoint -->+ <div class="api-section">+ <h2>GET/POST /api_log_get</h2>+ <p style="margin: 0 0 16px 0; color: var(--color-text-secondary); font-size: 14px;">+ Retrieve log data by context ID, limited to a specified number of entries from the newest.+ </p>++ <!-- API Reference -->+ <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">API Reference</h3>+ <div style="background-color: var(--color-bg-secondary); border: 1px solid var(--color-border); border-radius: 6px; padding: 12px; margin: 0 0 20px 0;">+ <p style="margin: 0 0 8px 0; color: var(--color-text-secondary); font-size: 14px;">+ <strong>Parameters:</strong><br>+ • <code>context_id</code> (string, required): Context ID to get logs from<br>+ • <code>length</code> (integer, optional): Number of log items to return from newest (default: 100)+ </p>+ <p style="margin: 0; color: var(--color-text-secondary); font-size: 14px;">+ <strong>Headers:</strong> <code>X-API-KEY</code> (required), <code>Content-Type: application/json</code> (for POST)+ </p>+ </div>++ <!-- JavaScript Examples -->+ <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">JavaScript Examples</h3>++ <h4>GET Request Example</h4>+ <div id="api-log-get-example"></div>++ <h4>POST Request Example</h4>+ <div id="api-log-post-example"></div>+ </div>++ <!-- Section 3: api_terminate_chat Endpoint -->+ <div class="api-section">+ <h2>POST /api_terminate_chat</h2>+ <p style="margin: 0 0 16px 0; color: var(--color-text-secondary); font-size: 14px;">+ Terminate and remove a chat context to free up resources. Similar to the MCP finish_chat function.+ </p>++ <!-- API Reference -->+ <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">API Reference</h3>+ <div style="background-color: var(--color-bg-secondary); border: 1px solid var(--color-border); border-radius: 6px; padding: 12px; margin: 0 0 20px 0;">+ <p style="margin: 0 0 8px 0; color: var(--color-text-secondary); font-size: 14px;">+ <strong>Parameters:</strong><br>+ • <code>context_id</code> (string, required): Context ID of the chat to terminate+ </p>+ <p style="margin: 0; color: var(--color-text-secondary); font-size: 14px;">+ <strong>Headers:</strong> <code>X-API-KEY</code> (required), <code>Content-Type: application/json</code>+ </p>+ </div>++ <!-- JavaScript Examples -->+ <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">JavaScript Examples</h3>+ <h4>Basic Termination Examples</h4>+ <div id="api-terminate-example"></div>+ </div>++ <!-- Section 4: api_reset_chat Endpoint -->+ <div class="api-section">+ <h2>POST /api_reset_chat</h2>+ <p style="margin: 0 0 16px 0; color: var(--color-text-secondary); font-size: 14px;">+ Reset a chat context to clear conversation history while keeping the context_id alive for continued use.+ </p>++ <!-- API Reference -->+ <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">API Reference</h3>+ <div style="background-color: var(--color-bg-secondary); border: 1px solid var(--color-border); border-radius: 6px; padding: 12px; margin: 0 0 20px 0;">+ <p style="margin: 0 0 8px 0; color: var(--color-text-secondary); font-size: 14px;">+ <strong>Parameters:</strong><br>+ • <code>context_id</code> (string, required): Context ID of the chat to reset+ </p>+ <p style="margin: 0; color: var(--color-text-secondary); font-size: 14px;">+ <strong>Headers:</strong> <code>X-API-KEY</code> (required), <code>Content-Type: application/json</code>+ </p>+ </div>++ <!-- JavaScript Examples -->+ <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">JavaScript Examples</h3>+ <h4>Basic Reset Examples</h4>+ <div id="api-reset-example"></div>+ </div>++ <!-- Section 5: api_files_get Endpoint -->+ <div class="api-section">+ <h2>POST /api_files_get</h2>+ <p style="margin: 0 0 16px 0; color: var(--color-text-secondary); font-size: 14px;">+ Retrieve file contents by paths, returning files as base64 encoded data. Useful for retrieving uploaded attachments.+ </p>++ <!-- API Reference -->+ <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">API Reference</h3>+ <div style="background-color: var(--color-bg-secondary); border: 1px solid var(--color-border); border-radius: 6px; padding: 12px; margin: 0 0 20px 0;">+ <p style="margin: 0 0 8px 0; color: var(--color-text-secondary); font-size: 14px;">+ <strong>Parameters:</strong><br>+ • <code>paths</code> (array, required): Array of file paths to retrieve (e.g., ["/a0/tmp/uploads/file.txt"])+ </p>+ <p style="margin: 0; color: var(--color-text-secondary); font-size: 14px;">+ <strong>Headers:</strong> <code>X-API-KEY</code> (required), <code>Content-Type: application/json</code>+ </p>+ </div>++ <!-- JavaScript Examples -->+ <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">JavaScript Examples</h3>+ <h4>File Retrieval Examples</h4>+ <div id="api-files-get-example"></div>+ </div>++ <!-- Section 6: Additional Endpoints -->+ <!--+ Example template for new endpoint sections:++ <div class="api-section">+ <h2>POST /endpoint_name</h2>+ <p style="margin: 0 0 16px 0; color: var(--color-text-secondary); font-size: 14px;">+ Description of what this endpoint does...+ </p>++ <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">API Reference</h3>+ <div style="background-color: var(--color-bg-secondary); border: 1px solid var(--color-border); border-radius: 6px; padding: 12px; margin: 0 0 20px 0;">+ <p style="margin: 0 0 8px 0; color: var(--color-text-secondary); font-size: 14px;">+ <strong>Parameters:</strong><br>+ • <code>param_name</code> (type, required/optional): Description+ </p>+ <p style="margin: 0; color: var(--color-text-secondary); font-size: 14px;">+ <strong>Headers:</strong> <code>X-API-KEY</code> (required), <code>Content-Type: application/json</code>+ </p>+ </div>++ <h3 style="margin: 20px 0 12px 0; color: var(--color-text-primary);">JavaScript Examples</h3>+ <h4>Example Title</h4>+ <div id="example-id"></div>+ </div>+ -->++ <script>+ setTimeout(() => {+ const url = window.location.origin;+ const token = settingsModalProxy.settings.sections.filter(x => x.id == "mcp_server")[0].fields.filter(x => x.id == "mcp_server_token")[0].value;++ // Basic usage example+ const basicExample = `// Basic message example+async function sendMessage() {+ try {+ const response = await fetch('${url}/api_message', {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ 'X-API-KEY': '${token}'+ },+ body: JSON.stringify({+ message: "Hello, how can you help me?",+ lifetime_hours: 24+ })+ });++ const data = await response.json();++ if (response.ok) {+ console.log('✅ Success!');+ console.log('Response:', data.response);+ console.log('Context ID:', data.context_id);+ return data;+ } else {+ console.error('❌ Error:', data.error);+ return null;+ }+ } catch (error) {+ console.error('❌ Request failed:', error);+ return null;+ }+}++// Call the function+sendMessage().then(result => {+ if (result) {+ console.log('Message sent successfully!');+ }+});`;++ // Continuation example+ const continuationExample = `// Continue conversation example+async function continueConversation(contextId) {+ try {+ const response = await fetch('${url}/api_message', {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ 'X-API-KEY': '${token}'+ },+ body: JSON.stringify({+ context_id: contextId,+ message: "Can you tell me more about that?",+ lifetime_hours: 24+ })+ });++ const data = await response.json();++ if (response.ok) {+ console.log('✅ Continuation Success!');+ console.log('Response:', data.response);+ return data;+ } else {+ console.error('❌ Error:', data.error);+ return null;+ }+ } catch (error) {+ console.error('❌ Request failed:', error);+ return null;+ }+}++// Example: First send a message, then continue the conversation+async function fullConversationExample() {+ const firstResult = await sendMessage();+ if (firstResult && firstResult.context_id) {+ await continueConversation(firstResult.context_id);+ }+}++fullConversationExample();`;++ // Attachment example+ const attachmentExample = `// File attachment example+async function sendWithAttachment() {+ try {+ // Example with text content (convert to base64)+ const textContent = "Hello World from attachment!";+ const base64Content = btoa(textContent);++ const response = await fetch('${url}/api_message', {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ 'X-API-KEY': '${token}'+ },+ body: JSON.stringify({+ message: "Please analyze this file:",+ attachments: [+ {+ filename: "document.txt",+ base64: base64Content+ }+ ],+ lifetime_hours: 12+ })+ });++ const data = await response.json();++ if (response.ok) {+ console.log('✅ File sent successfully!');+ console.log('Response:', data.response);+ return data;+ } else {+ console.error('❌ Error:', data.error);+ return null;+ }+ } catch (error) {+ console.error('❌ Request failed:', error);+ return null;+ }+}++// Call the function+sendWithAttachment();`;++ // Log GET example+ const logGetExample = `// Get logs using GET request+async function getLogsGET(contextId, length = 50) {+ try {+ const params = new URLSearchParams({+ context_id: contextId,+ length: length.toString()+ });++ const response = await fetch('${url}/api_log_get?' + params, {+ method: 'GET',+ headers: {+ 'X-API-KEY': '${token}'+ }+ });++ const data = await response.json();++ if (response.ok) {+ console.log('✅ Logs retrieved successfully!');+ console.log('Total items:', data.log.total_items);+ console.log('Returned items:', data.log.returned_items);+ console.log('Log items:', data.log.items);+ return data;+ } else {+ console.error('❌ Error:', data.error);+ return null;+ }+ } catch (error) {+ console.error('❌ Request failed:', error);+ return null;+ }+}++// Example usage+getLogsGET('ctx_abc123', 20);`;++ // Log POST example+ const logPostExample = `// Get logs using POST request+async function getLogsPOST(contextId, length = 50) {+ try {+ const response = await fetch('${url}/api_log_get', {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ 'X-API-KEY': '${token}'+ },+ body: JSON.stringify({+ context_id: contextId,+ length: length+ })+ });++ const data = await response.json();++ if (response.ok) {+ console.log('✅ Logs retrieved successfully!');+ console.log('Context ID:', data.context_id);+ console.log('Log GUID:', data.log.guid);+ console.log('Total items:', data.log.total_items);+ console.log('Returned items:', data.log.returned_items);+ console.log('Start position:', data.log.start_position);+ console.log('Progress:', data.log.progress);+ console.log('Log items:', data.log.items);+ return data;+ } else {+ console.error('❌ Error:', data.error);+ return null;+ }+ } catch (error) {+ console.error('❌ Request failed:', error);+ return null;+ }+}++// Example usage - get latest 10 log entries+getLogsPOST('ctx_abc123', 10);`;++ // Terminate chat example+ const terminateExample = `// Basic terminate chat function+async function terminateChat(contextId) {+ try {+ const response = await fetch('${url}/api_terminate_chat', {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ 'X-API-KEY': '${token}'+ },+ body: JSON.stringify({+ context_id: contextId+ })+ });++ const data = await response.json();++ if (response.ok) {+ console.log('✅ Chat deleted successfully!');+ console.log('Message:', data.message);+ return data;+ } else {+ console.error('❌ Error:', data.error);+ return null;+ }+ } catch (error) {+ console.error('❌ Request failed:', error);+ return null;+ }+}++// Example 1: Terminate a specific chat+terminateChat('ctx_abc123');++// Example 2: Complete workflow - send message, then terminate+async function simpleWorkflow() {+ // Send a message+ const result = await sendMessage();++ if (result && result.context_id) {+ console.log('Chat created:', result.context_id);++ // Do some work with the chat...+ // await continueConversation(result.context_id);++ // Clean up when done+ await terminateChat(result.context_id);+ console.log('Chat cleaned up');+ }+}++// Run the workflow+simpleWorkflow();`;++ // Reset chat example+ const resetExample = `// Basic reset chat function+async function resetChat(contextId) {+ try {+ const response = await fetch('${url}/api_reset_chat', {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ 'X-API-KEY': '${token}'+ },+ body: JSON.stringify({+ context_id: contextId+ })+ });++ const data = await response.json();++ if (response.ok) {+ console.log('✅ Chat reset successfully!');+ console.log('Message:', data.message);+ console.log('Context ID:', data.context_id);+ return data;+ } else {+ console.error('❌ Error:', data.error);+ return null;+ }+ } catch (error) {+ console.error('❌ Request failed:', error);+ return null;+ }+}++// Example 1: Reset a specific chat+resetChat('ctx_abc123');++// Example 2: Reset and continue conversation+async function resetAndContinue() {+ const contextId = 'ctx_abc123';++ // Reset the chat to clear history+ const resetResult = await resetChat(contextId);++ if (resetResult) {+ console.log('Chat reset, starting fresh conversation...');++ // Continue with same context_id but fresh history+ const response = await fetch('${url}/api_message', {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ 'X-API-KEY': '${token}'+ },+ body: JSON.stringify({+ context_id: contextId, // Same context ID+ message: "Hello, this is a fresh start!",+ lifetime_hours: 24+ })+ });++ const data = await response.json();+ console.log('New conversation started:', data.response);+ }+}++// Run the example+resetAndContinue();`;++ // Files get example+ const filesGetExample = `// Basic file retrieval+async function getFiles(filePaths) {+ try {+ const response = await fetch('${url}/api_files_get', {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ 'X-API-KEY': '${token}'+ },+ body: JSON.stringify({+ paths: filePaths+ })+ });++ const data = await response.json();++ if (response.ok) {+ console.log('✅ Files retrieved successfully!');+ console.log('Retrieved files:', Object.keys(data));++ // Convert base64 back to text for display+ for (const [filename, base64Content] of Object.entries(data)) {+ try {+ const textContent = atob(base64Content);+ console.log(\`\${filename}: \${textContent.substring(0, 100)}...\`);+ } catch (e) {+ console.log(\`\${filename}: Binary file (\${base64Content.length} chars)\`);+ }+ }++ return data;+ } else {+ console.error('❌ Error:', data.error);+ return null;+ }+ } catch (error) {+ console.error('❌ Request failed:', error);+ return null;+ }+}++// Example 1: Get specific files+const filePaths = [+ "/a0/tmp/uploads/document.txt",+ "/a0/tmp/uploads/data.json"+];+getFiles(filePaths);++// Example 2: Complete attachment workflow+async function attachmentWorkflow() {+ // Step 1: Send message with attachments+ const messageResponse = await fetch('${url}/api_message', {+ method: 'POST',+ headers: {+ 'Content-Type': 'application/json',+ 'X-API-KEY': '${token}'+ },+ body: JSON.stringify({+ message: "Please analyze this file",+ attachments: [{+ filename: "test.txt",+ base64: btoa("Hello, this is test content!")+ }],+ lifetime_hours: 1+ })+ });++ if (messageResponse.ok) {+ console.log('Message sent with attachment');++ // Step 2: Retrieve the uploaded file+ const retrievedFiles = await getFiles(["/a0/tmp/uploads/test.txt"]);++ if (retrievedFiles && retrievedFiles["test.txt"]) {+ const originalContent = atob(retrievedFiles["test.txt"]);+ console.log('Retrieved content:', originalContent);+ }+ }+}++// Run the complete workflow+attachmentWorkflow();`;++ // Initialize ACE editors+ const editors = [+ { id: "api-basic-example", content: basicExample },+ { id: "api-continuation-example", content: continuationExample },+ { id: "api-attachment-example", content: attachmentExample },+ { id: "api-log-get-example", content: logGetExample },+ { id: "api-log-post-example", content: logPostExample },+ { id: "api-terminate-example", content: terminateExample },+ { id: "api-reset-example", content: resetExample },+ { id: "api-files-get-example", content: filesGetExample }+ ];++ editors.forEach(({ id, content }) => {+ const editor = ace.edit(id);+ const dark = localStorage.getItem("darkMode");+ if (dark != "false") {+ editor.setTheme("ace/theme/github_dark");+ } else {+ editor.setTheme("ace/theme/tomorrow");+ }+ editor.session.setMode("ace/mode/javascript");+ editor.setValue(content);+ editor.clearSelection();+ editor.setReadOnly(true);+ });+ }, 0);+ </script>+ </div>++ <style>+ #api-basic-example,+ #api-continuation-example,+ #api-attachment-example,+ #api-log-get-example,+ #api-log-post-example,+ #api-terminate-example,+ #api-reset-example,+ #api-files-get-example {+ width: 100%;+ height: 20em;+ margin: 8px 0 16px 0;+ border-radius: 4px;+ }++ /* Section styling */+ .api-section {+ border: 1px solid var(--color-border);+ border-radius: 8px;+ margin: 20px 0;+ padding: 16px;+ }++ .api-section h2 {+ margin: 0 0 16px 0;+ color: var(--color-text-primary);+ border-bottom: 1px solid var(--color-border);+ padding-bottom: 8px;+ }++ .api-section h3 {+ margin: 20px 0 12px 0;+ color: var(--color-text-primary);+ font-size: 1.2em;+ }++ .api-section h4 {+ margin: 16px 0 8px 0;+ color: var(--color-text-primary);+ }+ </style>++</body>++</html>diff --git a/webui/components/settings/mcp/server/example.html b/webui/components/settings/mcp/server/example.htmlindex 75bcd815c..b69c28ad1 100644--- a/webui/components/settings/mcp/server/example.html+++ b/webui/components/settings/mcp/server/example.html@@ -10,6 +10,15 @@<p>Agent Zero MCP Server is an SSE MCP running on the same URL and port as the Web UI + /mcp/sse path.</p><p>The same applies if you run A0 on a public URL using a tunnel.</p>+ <!-- API Token Information -->+ <div style="background-color: var(--color-bg-secondary); border: 1px solid var(--color-border); border-radius: 6px; padding: 12px; margin: 16px 0;">+ <h4 style="margin: 0 0 8px 0; color: var(--color-text-primary);">API Token Information</h4>+ <p style="margin: 0; color: var(--color-text-secondary); font-size: 14px;">+ The token used in the URL is automatically generated from your username and password.+ This same token is also used for external API endpoints. The token changes when you update your credentials.+ </p>+ </div>+<h3>Example MCP Server Configuration JSON</h3><div id="mcp-server-example"></div>@@ -52,4 +61,4 @@</body>-</html>\ No newline at end of file+</html>diff --git a/webui/js/settings.js b/webui/js/settings.jsindex f58cb1c97..aa36d7e91 100644--- a/webui/js/settings.js+++ b/webui/js/settings.js@@ -291,6 +291,8 @@ const settingsModalProxy = {openModal("settings/backup/backup.html");} else if (field.id === "backup_restore") {openModal("settings/backup/restore.html");+ } else if (field.id === "external_api_examples") {+ openModal("settings/external/api-examples.html");}}};diff --git a/webui/public/external_api.svg b/webui/public/external_api.svgnew file mode 100644index 000000000..5dc4f86b2--- /dev/null+++ b/webui/public/external_api.svg@@ -0,0 +1,28 @@+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20">+ <g fill="none" stroke="#000" stroke-width="0.8" stroke-miterlimit="10">+ <!-- Central hub node -->+ <circle cx="10" cy="10" r="2.5"/>++ <!-- External connection nodes -->+ <circle cx="3" cy="3" r="1.5"/>+ <circle cx="17" cy="3" r="1.5"/>+ <circle cx="3" cy="17" r="1.5"/>+ <circle cx="17" cy="17" r="1.5"/>++ <!-- Connection lines -->+ <line x1="5.1" y1="4.9" x2="7.9" y2="7.1"/>+ <line x1="14.9" y1="4.9" x2="12.1" y2="7.1"/>+ <line x1="5.1" y1="15.1" x2="7.9" y2="12.9"/>+ <line x1="14.9" y1="15.1" x2="12.1" y2="12.9"/>++ <!-- API endpoints indicators -->+ <rect x="1" y="7" width="1" height="6" rx="0.5"/>+ <rect x="18" y="7" width="1" height="6" rx="0.5"/>+ <rect x="7" y="1" width="6" height="1" rx="0.5"/>+ <rect x="7" y="18" width="6" height="1" rx="0.5"/>++ <!-- Data flow arrows -->+ <path d="M6 8.5 L7.5 9.5 L6 10.5" fill="none" stroke-width="0.6"/>+ <path d="M14 9.5 L12.5 8.5 L14 7.5" fill="none" stroke-width="0.6"/>+ </g>+</svg>