agent-as-model

agent-as-model

真正的 MCP 服务，其中 Agent 就是模型，也是 API 密钥。

mcp-name: io.github.fernandogarzaaa/agent-as-model

安装

uvx agent-as-model

在 VS Code 中一键安装：

此深层链接在 vscode:mcp/install? 处理程序中携带服务的真实安装配置 （{"name":"agent-as-model","command":"uvx","args":["agent-as-model"]}）， 并采用 VS Code 官方 MCP 开发者指南中的格式。

宿主范围：仅支持采样的宿主

此服务通过 MCP 采样执行工作，因此一键安装和以下指南仅面向支持采样的宿主：VS Code、 Goose、fast-agent 和 opencode。在它们实现采样之前，Claude Code 和 Cursor 不在支持范围内。 下方仍保留了 Claude Code 的手动说明，供希望尝试的用户参考。

Goose

添加到 ~/.config/goose/config.yaml（或运行 goose configure，选择 Add Extension、Command-line Extension）：

extensions:
  agent-as-model:
    enabled: true
    type: stdio
    name: agent-as-model
    cmd: uvx
    args: ["agent-as-model"]
    timeout: 300

fast-agent

添加到 fastagent.config.yaml 中的 mcp.servers 下，然后将 agent-as-model 添加到 Agent 的 servers=[...] 列表中：

mcp:
  servers:
    agent-as-model:
      transport: "stdio"
      command: "uvx"
      args: ["agent-as-model"]

opencode

opencode mcp add agent-as-model -- uvx agent-as-model

或者添加到 opencode.json（项目根目录或 ~/.config/opencode/opencode.json）中：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agent-as-model": {
      "type": "local",
      "command": ["uvx", "agent-as-model"]
    }
  }
}

手动安装

Claude Code（保留为手动说明；在实现采样之前不提供一键安装）：

claude mcp add agent-as-model -- uvx agent-as-model

对于任何接受 MCP JSON 的客户端，粘贴以下内容：

{
  "mcpServers": {
    "agent-as-model": {
      "command": "uvx",
      "args": ["agent-as-model"]
    }
  }
}

需要 Python 3.10+，且宿主必须声明 MCP sampling 能力。无需 API 密钥，永远如此。

从本地检出目录运行：python -m agent_as_model。不安装，直接从仓库运行： uvx --from git+https://github.com/fernandogarzaaa/agent-as-model agent-as-model。

核心理念

AI 产品通常要求先提供模型 API 密钥，之后才能发挥作用。此服务反其道而行之。工具采用产品已有的请求格式，而智能则来自 MCP 连接另一端的 Agent。Agent 就是模型。Agent 就是密钥。

工具

chat_complete — 接收 OpenAI 聊天补全格式的请求，并返回补全文本。

{
  "messages": [
    {"role": "system", "content": "You are terse."},
    {"role": "user", "content": "Explain MCP sampling."}
  ],
  "model": "agent-default",
  "temperature": 0.7,
  "max_tokens": 500
}

messages_create — 接收 Anthropic 消息格式的请求，并返回补全文本。 system 接受字符串或文本块列表。消息内容接受字符串或文本块列表。

responses_create — 接收 OpenAI Responses API 格式的请求，并返回 Responses API 响应对象。input 可以是字符串（单条用户消息），也可以是输入项列表 {role, content}：role 可以是 user、assistant、system 或 developer；content 可以是字符串或文本部分列表 （{type: "input_text"|"text", input_text: "..."}）。系统和开发者输入项会与 instructions 一起合并到系统提示词中，且 instructions 优先。 不接受非文本部分。max_tokens 沿用其他工具中的名称（Responses API 称之为 max_output_tokens）。output_schema、 tools、tool_choice 和 persona 的行为与其他补全工具完全相同。

返回的对象为 {"id": "resp_<unique>", "object": "response", "model": <传入的模型别名>, "output": [...]}。宿主的纯文本回答会成为一个包含单个 output_text 块的 message 项。如果宿主通过调用工具作答，随附文本（非空时）会成为一个消息项，每次工具调用都会成为一个 function_call 项： {"type": "function_call", "id": "fc_<call id>", "call_id": "<宿主 工具调用 ID>", "name": "...", "arguments": "<JSON>"}；宿主的 工具调用 ID 会映射到 call_id，对象 ID 则由其派生。 generate — 输入原始提示词字符串，输出补全文本，使用相同的宿主模型，不进行聊天格式化。为不需要聊天结构的调用方提供精简路径：提示词会作为单条用户采样消息发送，不带系统提示词，也不进行角色转换。model、temperature 和 max_tokens 的行为与其他工具完全相同；没有 tools、output_schema 或 tool_choice 参数，因为这些是聊天工具的功能，而 generate 不增加任何开销。它也接受可选的 persona 契约，该契约仅用于请求／响应验证，不会增加采样开销。

list_models — 返回此服务提供的唯一模型：agent-default，它是宿主 Agent 自身模型的别名。

结构化输出 — 三个聊天形式的补全工具都接受可选的 output_schema（根类型为 object 的 JSON Schema 对象）。提供该参数时，采样请求会携带且仅携带一个工具，其输入架构为该架构，并将其标记为必选工具选项：宿主必须通过调用该工具作答，因此其工具使用输入就是结构化补全内容。服务会根据架构验证该输入，并将其作为 JSON 文本返回。宿主的回答若不符合架构，会明确报错；错误输出绝不会被悄悄返回。架构本身会预先验证，因此架构格式错误属于调用方的问题，不会在流程中途造成意外。

工具调用透传 — 三个聊天形式的补全工具还接受 tools（工具定义列表：{name, description, input_schema}，其中 input_schema 是根类型为 object 的 JSON Schema 对象）和 tool_choice（auto／required／none，默认值为 auto）。这些定义会预先验证（名称非空且唯一，架构有效并且为对象类型），并在两代协议的采样请求中转发给宿主模型。转发受宿主的 sampling.tools 能力约束：未声明该能力的宿主会收到不含工具的请求，服务端会记录警告日志说明降级，并且调用返回纯文本。宿主通过调用工具作答时，工具会以以下稳定格式返回 JSON 文本（键按字典序排列）： {"text": "...", "tool_calls": [{"id": "...", "input": {...}, "name": "..."}]}。 宿主返回纯文本时，仍会像以前一样返回文本。同时传入 tools 和 output_schema 会报错：output_schema 已通过一个必选工具实现，因此二者不能组合。

Persona — 四个补全工具（chat_complete、messages_create、responses_create 和 generate）都接受可选的 persona（{name, input_schema, output_schema}）。服务是无状态的：没有 persona 注册表，由宿主在每次调用时提供 persona，并且两代协议都执行相同的验证。发送任何内容之前，会先验证 persona 本身（必须提供非空的 name；若提供 input_schema 和 output_schema，则它们必须是根类型为 object 的有效 JSON Schema 对象），并在提供 input_schema 时根据它验证工具的请求参数。经过验证的请求对象是应用默认值后的工具参数集，但不包括 persona 本身：chat_complete 的 messages、model、temperature、max_tokens、output_schema、tools、tool_choice，以及 messages_create 额外包含的 system；generate 的 prompt、model、temperature、max_tokens。宿主作答后，补全文本必须能解析为 JSON，并在提供 output_schema 时通过其验证；无效输出会明确报错，并指出 persona 名称。与 output_schema 不同，persona 的 output_schema 不会改变采样请求（不会注入必选工具）：宿主以纯文本作答，再由服务解析。同时传入 output_schema 和 persona.output_schema 会报错：二者是结构化输出契约的两个相互矛盾的来源。 延续对话 — 服务端不保留会话状态，因此多轮延续由宿主负责。四种补全工具都接受可选的 previous_response_id，每个补全响应都会携带一个游标，供你传回以继续对话。游标格式为 cur_ + 对规范 JSON {"model","tool","transcript"} 计算的 sha256（键排序，分隔符紧凑）；其中 transcript 是截至助手轮次的对话内容：这是一种可检测篡改的承诺，具有确定性，因此你可以自行重新计算。传入 "" 可开始一条对话链。要继续对话，请将累积的历史记录（包括之前的助手轮次，且内容必须与收到时完全一致）和上一轮的游标一并传回：服务端会根据你的历史记录重新计算游标；如果不匹配，就会明确报错并指出预期值与收到的值。responses_create 响应 ID（resp_...）会锚定一条新对话链，而不会报错，因为不透明 ID 不承诺任何内容。提供 previous_response_id 时，文本工具会返回 {"completion": "<text>", "response_id": "cur_<...>"}，而不是纯文本；responses_create 则会将游标放在 id 字段中。不提供 previous_response_id，一切行为都与之前完全相同。要从较早的轮次分支，请将历史记录截断到该轮次，并传入该轮次的游标。对于 generate（没有结构化历史记录通道），传入 cur_ 游标会明确报错，而不会悄悄跳过验证；传入 ""，即可为当前提示词和补全内容生成游标。

工作原理

1. 产品（或 Agent）使用普通聊天消息调用 chat_complete。
2. 服务端将消息转换为补全载荷，并请求宿主完成补全。对于 2026 年以前的连接，这会直接发起 sampling/createMessage 请求。对于 2026-07-28 及之后的连接，服务端会返回携带完整载荷的多轮往返 InputRequiredResult，而不是调用 sampling API；补全内容会在重试轮次中返回。两种时期共用同一个工具主体。
3. 宿主 Agent 使用自己的模型生成补全内容，服务端再返回文本。model 参数只会作为模型提示传给宿主；agent-default 表示“使用你自己的模型”。

需要坦诚说明的事项

• Sampling 已在上游弃用（SEP-2577，规范版本 2026-07-28，最早于 2027-07-28 移除）。官方迁移路径是使用提供商 API 密钥。本项目存在的原因是，Agent 作为模型的架构才是关键，而不是密钥。这里采用的跨时期形式是获准的做法，可让它在两个规范时期都继续工作。
• 宿主拥有控制权。Sampling 在宿主的同意和策略下运行。对于 2026-07-28 之前的连接，如果宿主不具备 sampling 能力，就会返回明确的 MISSING_REQUIRED_CLIENT_CAPABILITY 错误，而不会悄悄失败。2026-07-28 及之后的 MRTR 路径完全不需要 sampling 能力。
• 每次工具调用都会触发一次宿主模型调用。这是一个思考型端点，而非快速端点。
• 工具调用只会透传，绝不会执行。服务端会将工具定义转发给宿主模型，并以 JSON 形式返回宿主的工具调用；它不会运行这些调用。任一方向的图像和音频仍会被明确拒绝并返回错误，不会悄悄丢弃。

路线图

• 为不支持 sampling 的宿主提供提供商密钥回退方案（可选择启用，每次调用的选择权仍属于用户）。
• 通过 toolChoice-required 技巧实现结构化输出（已发布：两种补全工具均支持 output_schema，并在服务端使用 jsonschema 包进行验证）。
• 工具使用透传（已发布：两种补全工具均支持 tools/tool_choice，由宿主的 sampling.tools 能力进行限制，并提供明确的纯文本降级方式及文档化的 JSON 结果格式）。
• 增加更多产品形态作为工具（无法通过 sampling 有意义地处理嵌入向量请求；按设计不在范围内）。

开发

python3 -m pytest tests/ -q
python3 -m ruff format . && python3 -m ruff check .

125 项测试全部通过：消息翻译单元测试，以及针对脚本化主机运行完整 MCP 循环（从工具调用到采样完成）的端到端测试，覆盖现代多轮往返时代和旧版直接采样时代，还包括结构化输出路径（采样参数中的单个必需工具和 MRTR 负载、验证成功以及明确报错的验证失败）、工具使用透传路径（在两个时代都转发 tools 和 tool_choice、能力缺失时降级为纯文本并明确记录警告、文档说明的 JSON 结果形状，以及 tools 与 output_schema 冲突）、generate 工具（在两个时代都使用单条用户消息、不带系统提示词且不带工具、参数透传、工具列表和说明）、persona 路径（在全部三个完成工具上公布 persona、请求侧验证成功及发送前拒绝、响应侧验证成功及明确报错的失败、格式错误的 persona 拒绝、output_schema 与 persona.output_schema 冲突、两个时代行为一致），以及由主机管理的会话游标协议（固定的规范游标计算；链的启动；两个时代的已验证多轮继续正常路径及跨时代游标一致性；历史被篡改时明确报错，指出预期值与收到值，涵盖被编辑的用户轮次、被编辑的助手轮次以及模型变更；格式错误的游标格式；不透明的 resp_ ID 锚定新链；省略 previous_response_id 时保持旧版返回形状不变；游标路径上将 responses_create ID 作为游标；generate 精简路径的验证限制；通过截断进行分支；以及在返回任何 InputRequiredResult 之前验证 MRTR 第一轮）。