零依赖PHP AI代理库NanoAgent：告别Python微服务

PHP开发者做AI Agent，为什么总要先搭一个Python微服务？

如果你曾尝试在PHP应用中接入LLM代理，很可能撞过同一堵墙：几乎所有成熟的Agent库都是Python写的。于是"最直接"的方案变成了在PHP应用旁边挂一个Python微服务——它调用你的Agent，Agent再调用你的API，结果你维护着两套运行时、两份部署，还凭空多了一跳网络通信。

开发者hammrouni对这种模式感到疲惫，于是构建了NanoAgent——一个原生运行在PHP中的Agent库。一次 composer require 即可安装，零运行时依赖，不需要Python、不需要框架、不需要DSL。

composer require hammrouni/nanoagent

Sidecar（边车）模式是这里提到的那种架构的通用名称：在原有应用进程之外，额外运行一个独立的辅助进程或服务，两者通过 HTTP、gRPC 或消息队列通信。这个概念源自微服务和 Kubernetes 生态（如 Envoy 作为服务网格的 sidecar），后来被广泛用于"主应用语言不擅长，就外挂一个擅长该任务的服务"的场景。

在 AI Agent 场景中，sidecar 的诱因是生态错配：LangChain、LlamaIndex、CrewAI 等成熟框架均为 Python 实现。把 Python Agent 作为 sidecar 挂在 PHP 应用旁边，虽然能让功能快速落地，但代价具体而真实——需要额外维护 Python 运行时与依赖锁、容器镜像变大、部署流水线翻倍，每次工具调用要多一次跨进程网络往返（延迟通常增加数十毫秒），跨语言调试也更困难。NanoAgent 的整个设计动机，正是消除这条 sidecar 链路。

NanoAgent的核心能力有哪些？

这个库的设计哲学可以用一句话概括：把已有的PHP代码直接变成Agent的工具。

• 一份配置，任意模型提供商。支持OpenAI、Groq、Anthropic、DeepSeek^广告、OpenRouter，也能接入任何兼容OpenAI协议的自托管端点（Ollama、llama.cpp server）。切换提供商只需改一行配置。
• 工具优先（Tool-first）。你可以把普通的PHP函数直接映射为工具，Agent能借此查询数据库、调用内部API、读取设备遥测数据——用的是你早就写好的那些代码。
• MCP支持。可以注册任意Model Context Protocol服务器（Streamable HTTP），其工具与本地工具行为完全一致，并通过allowlist控制哪些工具被注册。
• 持久化记忆。对话可以跨请求存活，通过可插拔驱动实现：JSON文件、SQLite、MySQL、PostgreSQL，或你自己实现的驱动。
• 极小的体积。一个包，没有隐藏魔法，官方声称可以在一小时内审计完整个代码库——这是刻意为之的小。

30秒上手示例

下面这段代码展示了NanoAgent最基本的用法：定义一个普通PHP函数作为工具，Agent会自行决定何时调用它。

<?php
use NanoAgent\Agent;

$agent = new Agent(llm: [
    'provider' => 'groq',
    'model'    => 'llama-3.3-70b-versatile',
    'api_key'  => getenv('GROQ_API_KEY'),
    // 'base_url' => 'http://localhost:8080/v1',  // …或本地模型服务器
]);

// 你的普通PHP函数，现在是一个工具：
$agent->tool('weather', fn (string $city) => "It is 22°C in {$city}.");

echo $agent->chat('How warm is it in Marrakech?');

就这么多。Agent自行决定调用 weather 工具，你的函数在进程内执行，结果返回后生成回复。没有sidecar，没有消息队列，没有第二种语言。

MCP（Model Context Protocol） 是 Anthropic 于 2024 年底提出并开源的协议，用于让 LLM 应用以统一方式连接外部工具与数据源。它把"工具提供方"（MCP Server）和"工具使用方"（MCP Client，即 Agent 宿主）解耦：Server 声明自己暴露哪些工具、资源和提示模板，Client 负责发现并调用它们。

MCP 常见的传输方式包括 stdio（本地子进程）和 Streamable HTTP（远程服务）。NanoAgent 支持的是后者，意味着你可以把任意符合 MCP 规范的远程服务直接接入，而不必为每个集成手写适配层。allowlist 机制则是一道安全阀：远程 Server 可能暴露几十个工具，只注册你审核过的那几个，可以避免 Agent 误调用危险操作。

为什么是PHP？一个被忽视的现实

作者的论证值得认真对待：大量生产环境中的AI需求并不是从零开始的新项目。它们是Laravel服务在对接遗留数据库、内部HTTP API和积累了十年的业务逻辑。在这些场景里真正有用的Agent，不是一个光鲜的框架，而是一个无聊的、本地的库，运行在你已经在跑的那个进程内部。

NanoAgent刻意选择了"无聊"。用作者的话说——"无聊就是特性"。

这种判断有它的合理性。PHP至今仍是Web后端的主力语言之一，WordPress、Laravel、Symfony生态中沉淀了海量业务代码。要求这些团队为了接入一个LLM Agent而引入Python技术栈，确实是一个不小的工程决策，而非简单的技术选型。

Tool Calling（工具调用） 是这类 Agent 库运作的底层机制。主流 LLM API 允许在请求中附带一份工具清单（名称、参数 JSON Schema、用途描述），模型不会真的执行函数，而是返回一个结构化的调用意图，比如 {"name": "weather", "arguments": {"city": "Marrakech"}}。宿主程序解析这个意图、在本地执行对应函数，再把结果作为一条消息回传给模型，模型据此生成最终自然语言回复——这个循环可能重复多轮。

正因如此，Agent 框架本质上只是一个"请求—解析—执行—回传"的循环加上工具注册表。它不需要特殊的运行时能力，PHP 完全可以承担。理解这一点，就能明白为什么 NanoAgent 敢把库做得很小：真正复杂的是模型本身，宿主侧的逻辑其实相当直白。

设计取舍：不做什么，比做什么更重要

NanoAgent明确划定了自己的边界：

• 不自动生成提示词。Prompt的构造权交给开发者。
• 不提供"魔法"抽象。没有隐藏的调用链，没有层层封装的AgentExecutor。
• 不引入14个依赖。整个库的依赖树为空。

如果你想要的是一个功能完备的框架，社区里有不少优秀选择。但如果你想要的是一个能从头读到尾、可以指向托管API也可以指向自己硬件上的模型、一个下午就能上线的库——这就是NanoAgent的定位。

这种取舍在工程上意味着什么？它意味着你放弃了开箱即用的多Agent编排、复杂的记忆策略、内置的RAG管道。换来的是一份你可以完全掌控的代码，以及不需要在架构中多维护一套运行时的简洁性。

RAG（检索增强生成） 指的是先从知识库中检索相关片段，再把片段拼进提示词交给模型生成答案的做法，通常需要向量化模型、向量数据库和分块策略三件套。多 Agent 编排则是指让多个各司其职的 Agent（规划者、执行者、审查者等）通过消息传递协作完成任务，LangGraph、AutoGen 等框架主要解决这类问题。

这两项能力在 NanoAgent 中被有意排除，不是能力缺陷，而是范围声明。如果你的场景是"查工单、调内部 API、读设备数据后回答"，单 Agent 加若干本地工具已经足够；只有当任务需要跨越多步规划、自我反思或并行子任务时，才值得引入编排层。明确这条分界线，能避免团队为一个简单需求背上复杂框架的维护负担。

如何获取与参与

• 代码仓库：https://github.com/hammrouni/nanoagentphp （含完整文档和可运行示例）
• 文档站点：https://hammrouni.github.io/nanoagentphp/
• Composer安装：composer require hammrouni/nanoagent

项目采用MIT许可证，欢迎提交Issue和PR。作者还提到，他的个人主页链接了一套关于"用PHP构建Agent"的12篇系列文章，本文只是精简版。

对于正在维护PHP技术栈、又希望在不引入第二运行时的情况下为应用添加Agent能力的团队来说，NanoAgent提供了一个值得评估的选项。它未必适合所有场景——尤其是需要复杂多Agent协作的项目——但它的"零依赖、进程内运行、可完全审计"这三点，在特定的工程约束下是实实在在的优势。