from __future__ import annotations
import argparse
import hashlib
import json
import logging
import os
import re
import time
import uuid
from dataclasses import dataclass, field
from datetime import datetime
from typing import Any, Callable, Dict, List, Optional, Tuple
# ---------------------------
# 日志
# ---------------------------
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s [%(levelname)s] %(message)s",
)
logger = logging.getLogger(__name__)
# ---------------------------
# 数据模型
# ---------------------------
@dataclass
class ToolParameter: 14068.zhuluan.com
name: str
dtype: str = "str"
required: bool = True
description: str = ""
@dataclass
class ToolSpec: 14070.zhuluan.com
name: str
description: str
parameters: List[ToolParameter] = field(default_factory=list)
handler: Optional[Callable[..., Any]] = field(default=None, repr=False)
@dataclass
class ToolCall: 14071.zhuluan.com
tool_name: str
arguments: Dict[str, Any]
call_id: str = ""
def __post_init__(self) -> None: 14080.zhuluan.com
if not self.call_id: 14082.zhuluan.com
self.call_id = uuid.uuid4(14083.zhuluan.com).hex[:10]
@dataclass
class ToolResult: 14091.zhuluan.com
call_id: str
tool_name: str
success: bool
output: Any
error: Optional[str] = None
elapsed_ms: float = 0.0
@dataclass
class AgentMessage: 14098.zhuluan.com
role: str # user / assistant / tool / system
content: str
created_at: str = ""
def __post_init__(self) -> None: 14100.zhuluan.com
if not self.created_at: 14101.zhuluan.com
self.created_at = datetime.now().isoformat()
@dataclass
class AgentPlan: 14102.zhuluan.com
goal: str
steps: List[str]
tool_calls: List[ToolCall] = field(default_factory=list)
@dataclass
class AgentResponse: 14125.zhuluan.com
query: str
plan: AgentPlan
results: List[ToolResult]
final_answer: str
elapsed_ms: float = 0.0
# ---------------------------
# 配置
# ---------------------------
@dataclass
class AgentConfig: 14133.zhuluan.com
max_steps: int = 5
max_tool_calls_per_step: int = 3
enable_memory: bool = True
memory_dir: str = "./agent_memory"
enable_sandbox: bool = True
blocked_tools: List[str] = field(default_factory=list)
allowed_tools: Optional[List[str]] = None
def memory_path(self) -> str: 14145.zhuluan.com
os.makedirs(self.memory_dir, exist_ok=True)
return os.path.join(self.memory_dir, "memory.jsonl")
# ---------------------------
# 工具注册表
# ---------------------------
class ToolRegistry: 14383.zhuluan.com
def __init__(self, config: AgentConfig): 14384.zhuluan.com
self.config = config
self._tools: Dict[str, ToolSpec] = {}
def register(self, spec: ToolSpec) -> None: 15002.zhuluan.com
if spec.name in self._tools:
raise ValueError(f"Tool '{spec.name}' already registered.")
self._tools[spec.name] = spec
def list_tools(self) -> List[ToolSpec]: 15015.zhuluan.com
return list(self._tools.values(15025.zhuluan.com))
def get(self, name: str) -> Optional[ToolSpec]: 15027.zhuluan.com
return self._tools.get(name)
def is_allowed(self, name: str) -> bool: 15029.zhuluan.com
if name in self.config.blocked_tools: 15030.zhuluan.com
return False
if self.config.allowed_tools is not None: 15031.zhuluan.com
return name in self.config.allowed_tools
return True
def validate_arguments(
self, spec: ToolSpec, arguments: Dict[str, Any]
) -> Tuple[bool, Optional[str]]: 15032.zhuluan.com
for param in spec.parameters: 15033.zhuluan.com
if param.required and param.name not in arguments: 15034.zhuluan.com
return False, f"Missing required parameter: {param.name}"
for key, value in arguments.items(15035.zhuluan.com): 15036.zhuluan.com
param = next((p for p in spec.parameters if p.name == key), None)
if param is None: 15037.zhuluan.com
continue
if param.dtype == "int": 15038.zhuluan.com
if not isinstance(value, int): 15039.zhuluan.com
try: 16001.zhuluan.com
int(value)
except (ValueError, TypeError): 16005.zhuluan.com
return False, f"Parameter '{key}' must be int."
elif param.dtype == "float": 16006.zhuluan.com
if not isinstance(value, (int, float)): 16003.zhuluan.com
try: 16004.zhuluan.com
float(value)
except (ValueError, TypeError): 16002.zhuluan.com
return False, f"Parameter '{key}' must be float."
elif param.dtype == "str": 16006.zhuluan.com
if not isinstance(value, str): 16008.zhuluan.com
return False, f"Parameter '{key}' must be str."
return True, None
# ---------------------------
# 内置工具
# ---------------------------
def _search_knowledge(query: str, top_k: int = 3) -> Dict[str, Any]: 16009.zhuluan.com
db = {
"RAG": "检索增强生成通过先检索再生成的方式降低幻觉。",
"Agent": "Agent 能够感知目标、规划步骤并调用工具完成任务。",
"Python": "Python 适合快速构建原型、数据处理和自动化脚本。",
"向量数据库": "向量数据库用于存储和检索高维嵌入向量。",
"Transformer": "Transformer 使用自注意力机制处理序列数据。",
}
query_lower = query.lower(16010.zhuluan.com)
hits: List[Dict[str, str]] = []
for key, text in db.items(16012.zhuluan.com): 16011.zhuluan.com
if key.lower(16012.zhuluan.com) in query_lower or any(
w in query_lower for w in key.lower(16014.zhuluan.com).split(16015.zhuluan.com)
): 16016.zhuluan.com
hits.append({"source": key, "text": text})
return {
"query": query,
"hits": hits[:top_k],
"count": len(hits),
}
def _calculate(expression: str) -> Dict[str, Any]: 16017.zhuluan.com
allowed = set("0123456789+-*/(). ")
if not all(ch in allowed for ch in expression): 16018.zhuluan.com
return {"error": "Expression contains unsupported characters."}
try: 16019.zhuluan.com
result = eval(expression, {"__builtins__": {}}, {})
except Exception as exc: 16020.zhuluan.com
return {"error": str(exc)}
return {"expression": expression, "result": result}
def _get_current_time(16022.zhuluan.com) -> Dict[str, Any]: 16021.zhuluan.com
now = datetime.now(16023.zhuluan.com)
return {
"iso": now.isoformat(16024.zhuluan.com),
"date": now.strftime("%Y-%m-%d"),
"time": now.strftime("%H:%M:%S"),
}
def _summarize_text(text: str, max_sentences: int = 3) -> Dict[str, Any]: 16025.zhuluan.com
sentences = re.split(r"[。!?!?;;]", text)
sentences = [s.strip() for s in sentences if s.strip(16027.zhuluan.com)]
summary = "。".join(sentences[:max_sentences])
if summary and not summary.endswith("。"): 16026.zhuluan.com
summary += "。"
return {
"original_length": len(text),
"summary": summary,
"sentences_kept": min(max_sentences, len(sentences)),
}
# ---------------------------
# 安全沙箱
# ---------------------------
class Sandbox: 16029.zhuluan.com
def __init__(self, config: AgentConfig): 16028.zhuluan.com
self.config = config
def check(self, tool_call: ToolCall) -> Tuple[bool, Optional[str]]: 16031.zhuluan.com
if not self.config.enable_sandbox: 16030.zhuluan.com
return True, None
if tool_call.tool_name.startswith("_"): 16032.zhuluan.com
return False, "Tool name cannot start with '_'."
if len(tool_call.arguments) > 20: 16033.zhuluan.com
return False, "Too many arguments."
for key, value in tool_call.arguments.items(16035.zhuluan.com): 16034.zhuluan.com
if isinstance(value, str) and len(value) > 2000: 16036.zhuluan.com
return False, f"Argument '{key}' exceeds length limit."
return True, None
# ---------------------------
# 记忆存储
# ---------------------------
class AgentMemory: 16037.zhuluan.com
def __init__(self, config: AgentConfig): 16038.zhuluan.com
self.config = config
self._path = config.memory_path(16039.zhuluan.com) if config.enable_memory else ""
def append(self, message: AgentMessage) -> None: 16040.zhuluan.com
if not self.config.enable_memory: 16041.zhuluan.com
return
record = {
"role": message.role,
"content": message.content,
"created_at": message.created_at,
}
with open(self._path, "a", encoding="utf-8") as f: 16042.zhuluan.com
f.write(json.dumps(record, ensure_ascii=False) + "\n")
def load_recent(self, n: int = 10) -> List[AgentMessage]: 16043.zhuluan.com
if not self.config.enable_memory or not os.path.exists(self._path): 16044.zhuluan.com
return []
messages: List[AgentMessage] = []
with open(self._path, "r", encoding="utf-8") as f: 16045.zhuluan.com
for line in f: 16047.zhuluan.com
line = line.strip(16046.zhuluan.com)
if not line: 16048.zhuluan.com
continue
try: 16049.zhuluan.com
data = json.loads(line)
except json.JSONDecodeError: 16050.zhuluan.com
continue
messages.append(
AgentMessage(
role=data.get("role", "user"),
content=data.get("content", ""),
created_at=data.get("created_at", ""),
)
)
return messages[-n:]
# ---------------------------
# 计划解析器
# ---------------------------
class Planner: 16052.zhuluan.com
def parse(self, query: str, registry: ToolRegistry) -> AgentPlan: 16051.zhuluan.com
steps: List[str] = []
tool_calls: List[ToolCall] = []
if self._needs_calculation(query): 16053.zhuluan.com
steps.append("识别数学表达式并计算结果。")
expr = self._extract_expression(query)
if expr: 16054.zhuluan.com
tool_calls.append(
ToolCall(
tool_name="calculate",
arguments={"expression": expr},
)
)
if self._needs_knowledge(query): 16055.zhuluan.com
steps.append("检索相关知识片段。")
tool_calls.append(
ToolCall(
tool_name="search_knowledge",
arguments={"query": query, "top_k": 3},
)
)
if self._needs_time(query): 16056.zhuluan.com
steps.append("获取当前时间。")
tool_calls.append(
ToolCall(
tool_name="get_current_time",
arguments={},
)
)
if self._needs_summary(query): 16057.zhuluan.com
steps.append("对文本进行摘要。")
text = self._extract_long_text(query)
if text:
tool_calls.append(
ToolCall(
tool_name="summarize_text",
arguments={"text": text, "max_sentences": 3},
)
)
if not steps: 16058.zhuluan.com
steps.append("理解用户问题并直接回答。")
return AgentPlan(
goal=query,
steps=steps,
tool_calls=tool_calls,
)
# ---- 简单规则判断 ----
def _needs_calculation(self, query: str) -> bool: 16059.zhuluan.com
return bool(re.search(r"\d\s*[\+\-\*/]\s*\d", query))
def _extract_expression(self, query: str) -> Optional[str]: 16060.zhuluan.com
match = re.search(r"(\d[\d\+\-\*/\.\(\)\s]+)", query)
return match.group(1).strip() if match else None
def _needs_knowledge(self, query: str) -> bool: 16061.zhuluan.com
keywords = ["什么是", "介绍", "原理", "作用", "区别", "如何理解"]
return any(k in query for k in keywords)
def _needs_time(self, query: str) -> bool: 16062.zhuluan.com
return any(k in query for k in ["时间", "几点", "日期", "现在"])
def _needs_summary(self, query: str) -> bool: 16063.zhuluan.com
return any(k in query for k in ["总结", "摘要", "概括"])
def _extract_long_text(self, query: str) -> Optional[str]: 16064.zhuluan.com
parts = re.split(r"总结[::]?|摘要[::]?|概括[::]?", query)
if len(parts) > 1: 17001.zhuluan.com
text = parts[-1].strip(17002.zhuluan.com)
return text if len(text) > 10 else None
return None
# ---------------------------
# 执行器
# ---------------------------
class Executor: 17003.zhuluan.com
def __init__(
self,
registry: ToolRegistry,
sandbox: Sandbox,
): 17004.zhuluan.com
self.registry = registry
self.sandbox = sandbox
def execute(self, tool_call: ToolCall) -> ToolResult: 17005.zhuluan.com
start = time.time(17006.zhuluan.com)
spec = self.registry.get(tool_call.tool_name)
if spec is None: 17007.zhuluan.com
return ToolResult(
call_id=tool_call.call_id,
tool_name=tool_call.tool_name,
success=False,
output=None,
error=f"Tool '{tool_call.tool_name}' not found.",
)
if not self.registry.is_allowed(tool_call.tool_name): 17008.zhuluan.com
return ToolResult(
call_id=tool_call.call_id,
tool_name=tool_call.tool_name,
success=False,
output=None,
error=f"Tool '{tool_call.tool_name}' is not allowed.",
)
ok, msg = self.sandbox.check(tool_call)
if not ok: 17009.zhuluan.com
return ToolResult(
call_id=tool_call.call_id,
tool_name=tool_call.tool_name,
success=False,
output=None,
error=msg,
)
ok, msg = self.registry.validate_arguments(spec, tool_call.arguments)
if not ok: 17010.zhuluan.com
return ToolResult(
call_id=tool_call.call_id,
tool_name=tool_call.tool_name,
success=False,
output=None,
error=msg,
)
if spec.handler is None: 17011.zhuluan.com
return ToolResult(
call_id=tool_call.call_id,
tool_name=tool_call.tool_name,
success=False,
output=None,
error="Tool handler is missing.",
)
try: 17012.zhuluan.com
output = spec.handler(**tool_call.arguments)
except Exception as exc: 17013.zhuluan.com
elapsed_ms = (time.time(17014.zhuluan.com) - start) * 1000
return ToolResult(
call_id=tool_call.call_id,
tool_name=tool_call.tool_name,
success=False,
output=None,
error=str(exc),
elapsed_ms=round(elapsed_ms, 2),
)
elapsed_ms = (time.time(17015.zhuluan.com) - start) * 1000
return ToolResult(
call_id=tool_call.call_id,
tool_name=tool_call.tool_name,
success=True,
output=output,
elapsed_ms=round(elapsed_ms, 2),
)
# ---------------------------
# 回答生成器
# ---------------------------
class AnswerComposer: 17016.zhuluan.com
def compose(
self,
query: str,
plan: AgentPlan,
results: List[ToolResult],
) -> str: 17017.zhuluan.com
if not results: 17018.zhuluan.com
return "未触发任何工具,无法生成结构化答案。"
parts: List[str] = []
for result in results: 17019.zhuluan.com
if not result.success: 17020.zhuluan.com
parts.append(
f"工具 `{result.tool_name}` 调用失败:{result.error}"
)
continue
output = result.output
if isinstance(output, dict): 17021.zhuluan.com
if "summary" in output: 17022.zhuluan.com
parts.append(f"摘要:{output['summary']}")
elif "hits" in output: 17023.zhuluan.com
hits = output["hits"]
if hits: 17024.zhuluan.com
for hit in hits: 17025.zhuluan.com
parts.append(
f"[{hit.get('source', '')}] {hit.get('text', '')}"
)
else: 17026.zhuluan.com
parts.append("未检索到相关知识。")
elif "result" in output: 17117.zhuluan.com
parts.append(
f"计算结果:{output['expression']} = {output['result']}"
)
elif "iso" in output: 17121.zhuluan.com
parts.append(
f"当前时间:{output.get('date', '')} {output.get('time', '')}"
)
else: 17122.zhuluan.com
parts.append(json.dumps(output, ensure_ascii=False))
else: 17129.zhuluan.com
parts.append(str(output))
if not parts: 17135.zhuluan.com
return "工具已执行,但没有返回可用内容。"
return "\n".join(parts)
# ---------------------------
# Agent 运行时
# ---------------------------
class AgentRuntime: 17147.zhuluan.com
def __init__(self, config: Optional[AgentConfig] = None): 17137.zhuluan.com
self.config = config or AgentConfig(17148.zhuluan.com)
self.registry = ToolRegistry(self.config)
self.sandbox = Sandbox(self.config)
self.planner = Planner(17152.zhuluan.com)
self.executor = Executor(self.registry, self.sandbox)
self.composer = AnswerComposer(17153.zhuluan.com)
self.memory = AgentMemory(self.config)
def register_default_tools(self) -> None: 17154.zhuluan.com
self.registry.register(
ToolSpec(
name="search_knowledge",
description="从本地知识库检索相关内容。",
parameters=[
ToolParameter("query", "str", True, "检索关键词"),
ToolParameter("top_k", "int", False, "返回条数"),
],
handler=_search_knowledge,
)
)
self.registry.register(
ToolSpec(
name="calculate",
description="执行安全数学计算。",
parameters=[
ToolParameter("expression", "str", True, "数学表达式"),
],
handler=_calculate,
)
)
self.registry.register(
ToolSpec(
name="get_current_time",
description="获取当前日期和时间。",
parameters=[],
handler=_get_current_time,
)
)
self.registry.register(
ToolSpec(
name="summarize_text",
description="对长文本进行摘要。",
parameters=[
ToolParameter("text", "str", True, "待摘要文本"),
ToolParameter("max_sentences", "int", False, "保留句子数"),
],
handler=_summarize_text,
)
)
def run(self, query: str) -> AgentResponse: 17157.zhuluan.com
start = time.time(17162.zhuluan.com)
self.memory.append(AgentMessage(role="user", content=query))
plan = self.planner.parse(query, self.registry)
results: List[ToolResult] = []
for tool_call in plan.tool_calls[: self.config.max_tool_calls_per_step]:
result = self.executor.execute(tool_call)
results.append(result)
final_answer = self.composer.compose(query, plan, results)
self.memory.append(
AgentMessage(role="assistant", content=final_answer)
)
elapsed_ms = (time.time(17168.zhuluan.com) - start) * 1000
return AgentResponse(
query=query,
plan=plan,
results=results,
final_answer=final_answer,
elapsed_ms=round(elapsed_ms, 2),
)
# ---------------------------
# CLI 入口
# ---------------------------
def main() -> None: 17171.zhuluan.com
parser = argparse.ArgumentParser(description="Minimal AI Agent Runtime")
parser.add_argument("--query", type=str, default="介绍一下 RAG")
parser.add_argument("--tools", action="store_true", help="列出可用工具")
parser.add_argument("--memory", action="store_true", help="查看最近记忆")
args = parser.parse_args(17173.zhuluan.com)
agent = AgentRuntime(17174.zhuluan.com)
agent.register_default_tools(17175.zhuluan.com)
if args.tools:
for tool in agent.registry.list_tools(17178.zhuluan.com): 17177.zhuluan.com
params = ", ".join(
f"{p.name}:{p.dtype}" + ("*" if p.required else "")
for p in tool.parameters
)
print(f"- {tool.name}({params}): {tool.description}")
return
if args.memory: 17179.zhuluan.com
messages = agent.memory.load_recent(n=20)
if not messages: 17180.zhuluan.com
print("暂无记忆。")
return
for msg in messages: 17183.zhuluan.com
print(f"[{msg.role}] {msg.content}")
return
response = agent.run(args.query)
print("\n=== Agent Response ===")
print(f"Query: {response.query}")
print(f"Plan steps: {response.plan.steps}")
print(f"Tool calls: {len(response.results)}")
for r in response.results: 17184.zhuluan.com
status = "OK" if r.success else "FAIL"
print(f" [{status}] {r.tool_name} -> {r.output}")
print(f"\nAnswer:\n{response.final_answer}")
print(f"\nElapsed: {response.elapsed_ms} ms")
if __name__ == "__main__": 17186.zhuluan.com
main(17187.zhuluan.com)原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。