首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >用 Python 从零实现一个可插拔 AI Agent 运行时

用 Python 从零实现一个可插拔 AI Agent 运行时

原创
作者头像
用户12583550
发布于 2026-11-18 18:26:00
发布于 2026-11-18 18:26:00
70
举报
代码语言:javascript
复制
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 删除。

问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档