Photo Scout

Agentic Services

Agentic Services 是一个面向人类用户、自主 Agent 或两者的多服务平台。每项服务都专注于一项能力，并可通过适当的面向用户和／或面向机器的渠道独立销售。

服务分为以下三种产品类别之一：

• **仅面向人类：**专为人们通过 UI 使用而设计；无需提供 Agent 可调用的接口。
• **仅面向 Agent：**专为自主 Agent 通过机器接口发现、购买和调用而设计；信息性产品页面不属于供人类使用的 UI。
• **面向人类和 Agent：**为同一底层能力同时提供可用的人类 UI 和机器服务接口。

类别描述的是目标用户，而不是网站或 API 是否恰好存在。API、MCP 工具和 A2A 服务都是可能的机器传输方式；人类 UI 则是独立的产品界面。

产品契约

每项已发布服务都有稳定的身份、独立的报价和交付契约、付款途径，以及服务级别和政策信息。具体要求取决于服务类别：

• 仅面向人类的服务需要可用的 UI，以及面向人类的结账或权益获取流程。
• 仅面向 Agent 的服务需要机器可读的描述、输入／输出架构、可调用的传输方式，以及兼容机器的定价和付款方式。
• 面向人类和 Agent 的服务需要完整提供两种界面，并由相同的服务身份支撑；在适用情况下，还应确保结果和商业条款一致。
• 付费交付必须计量并记录。机器调用需要具备幂等性和可验证的收据；人类交易需要订单记录和适当的收据。
• 数据服务应根据其声明发布来源信息和时效信息。

对于提供 Agent 接口的服务，规范的公开清单位于：

https://<service-host>/.well-known/agent-service.json

同一份清单可由平台注册表编入索引，也可导出到兼容的发现网络。仅面向人类的服务不需要 Agent 清单。

仓库布局

docs/                         Product and system design
examples/                     Example service manifests
schemas/                      Versioned protocol schemas
services/                     Product-specific documentation
src/agentic_services/         Runnable gateway and Web Evidence API
tests/                        API contract and safety tests

初始协议定义于 schemas/service-manifest.schema.json。示例服务见 examples/weather-risk.service.json。

架构

该平台包含四个层：

• 服务层 — 由各个服务模块拥有、专注于特定领域的信息产品。
• 网关层 — 身份、报价、付款验证、速率限制和收据。
• 注册表层 — 能力搜索、运行状况、信誉和机器可读清单。
• 结算层 — 按次付费、积分和订阅的适配器。

执行流程请参阅 docs/architecture.md，构建顺序请参阅 docs/roadmap.md。

有关 Niche Discovery，请参阅持续收集与 Agent 分析设计。 其 Niche Manager Agent 通过可扩展的工具注册表、记忆、定期运行和事件驱动唤醒机制，负责自主研究和知识库维护。

设计原则

• 面向 Agent 的服务优先采用协议：Agent 无需阅读说明文字，只看架构即可完成集成。
• 服务范围要窄：每项服务只负责一个小领域，并返回有用的结果，而不只是原始数据。
• 核心与付款方式无关：商业条款保持稳定，同时付款渠道可替换。
• 交付可验证：付费交易有订单记录；机器执行有与请求、价格和结果关联的收据。
• 确保机器自主购买安全：通过确定性代码强制执行预算、到期时间、重放保护和幂等性。
• 联邦式发现：平台注册表很有用，但不是发现服务的唯一方式。

在本地运行 Web Evidence

首个可运行的服务是 Web Evidence，这是一个结构化的声明核验 API，由 OpenAI Responses API 和托管式网页搜索提供支持。

python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
cp .env.example .env.local
# Add OPENAI_API_KEY to .env.local
.venv/bin/agentic-services

API 的地址为 http://localhost:8000。主要端点如下：

• POST /web-evidence/v1/claims/verify/quick — 快速核验，费用为 $0.02。
• POST /web-evidence/v1/claims/verify — 标准核验，费用为 $0.05。
• POST /web-evidence/v1/claims/verify/deep — 深度核验，费用为 $0.12。
• POST /web-evidence/v1/claims/verify/research — 研究级核验，费用为 $0.25。

较早的 /v1/services/web-evidence/claims/verify... 和 /v1/claims/verify... 路径仍作为已弃用的兼容别名提供支持。

• GET /v1/claims/verifications/{verification_id} — 获取不可变结果。
• GET /v1/url-snapshots/{snapshot_id} — 获取快照状态和内容哈希。
• GET /v1/url-snapshots/{snapshot_id}/content — 获取精确捕获的响应字节。
• GET /.well-known/agent-service.json — 发现服务及其架构。
• GET /.well-known/x402 — 发现可通过 x402 付费的资源 URL。
• POST /mcp — MCP Streamable HTTP 服务，提供一个免费的发现工具和四个通过 x402 付费的核验工具。
• GET /.well-known/mcp/server.json — MCP Registry 元数据。
• POST /a2a — A2A 1.0 JSON-RPC SendMessage，按标准档位收费。
• GET /.well-known/agent-card.json — A2A Agent Card。
• GET /openapi.json — 查看完整的 HTTP 契约。
• GET /v1/services — 列出平台目录中的所有服务。
• GET /llms.txt — 阅读简明的 Agent 集成说明。
• GET / — 包含结构化数据的人类可读首页；robots.txt 和 sitemap.xml 支持网页索引。
• POST /v1/quotes — 创建有效期为 15 分钟的机器可读档位报价。
• GET /v1/orders/{order_id} — 获取一笔已付款订单及其带有一次性订单令牌的签名收据。
• GET /v1/customer/orders — 使用 X-Agentic-Customer-Key 列出已注册客户的订单。
• POST /v1/receipts/{order_id}/verify — 验证已签发收据上的服务端签名。
• GET /admin — 私密商务仪表板，用于查看收入、OpenAI 成本、毛利润和单笔订单。
• GET /v1/admin/services — 列出商务仪表板可用的服务。
• GET /v1/admin/summary、GET /v1/admin/orders — 使用 X-Admin-Key 进行身份验证的仪表板 API；两者均支持平台范围报告和 serviceId 筛选。
• POST /v1/admin/customers — 签发客户 API 密钥；明文仅返回一次，存储的只有其 SHA-256 哈希。

请求示例：

curl http://localhost:8000/v1/claims/verify \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-claim-1' \
  -d '{
    "claim": "OpenAI publishes an official Responses API reference.",
    "sourcePolicy": "official_only",
    "allowedDomains": ["openai.com"],
    "minimumSources": 1
  }'

有关请求语义、证据保证和计划推出的付费服务端点，请参阅 docs/web-evidence-api.md。

如需在 api.aisoup.net 部署生产环境的 Docker Compose，请按照 deploy/google-cloud-vm.md 操作。公共网关接受以 Base USDC 支付的 x402 和 MPP 付款，价格为所列档位的价格。网关还接受通过 MPP Stripe 支付的银行卡/USD 付款，每次调用最低 $0.50。Python 服务仍通过内部 Bearer 凭据保持私有。

实时发现

California C-10 Contractor Check 已面向人类用户通过 Stripe Checkout（每份报告 $19）上线，也已面向 Agent 通过其付费 HTTP API 和 MCP 端点（每次检查 $1，以 Base USDC 结算）上线。其 Smithery 条目、官方 MCP Registry 记录以及共享 x402Scan 页面上的路由均可公开查看。发布约定和可重复的验证门槛详见 docs/agent-service-release.md。其他外部目录条目和已结算付款尚未验证。

Web Evidence 已通过以下公开发现入口发布：

• Smithery：作为托管的 MCP 条目，列出 impanyu/web-evidence。
• Official MCP Registry：列为 io.github.impanyu/web-evidence。
• OpenX402 Bazaar：作为付费 MCP 资源 mcp://api.aisoup.net/verify_claim_quick。
• x402Scan：包含全部四个付费 HTTP 档位和两个公开快照路由。
• MPPScan：包含付费验证路由，以及可安全抓取的公开证据／商务路由。
• Global A2A Registry 和开源 A2A Registry API：通过公开的 A2A 1.0 Agent Card 发布。

该代码库还包含用于发布到 MCP Registry 的 server.json，以及用于未来提交至 Glama 的 glama.json。落地页提供 Schema.org 服务元数据、robots.txt、sitemap.xml、OpenAPI、llms.txt，以及供独立爬虫使用的 well-known 清单。只有在能够独立检索到目录的公开条目后，才将其视为已上线。

api.aisoup.net URL 前缀属性已在 Google Search Console 中验证，且其站点地图已提交。生产环境还提供由私钥支持的 IndexNow 所有权文件，以便将更新后的发现 URL 发送给参与的搜索引擎。搜索引擎收录仍需异步完成，只有结果可公开搜索后才视为完成。

状态

此代码仓库包含 v0 协议、一套可运行的分级 Web 证据服务、完整的提供方来源追溯、带原始和标准化 SHA-256 哈希值的 URL 快照、SQLite 持久化、机器可读的发现机制，以及一个 x402/MPP 双协议支付网关。每次付费 HTTP、MCP 或 A2A 执行都会创建一笔订单、一份签名收据和一条详细的收入／成本账目。管理仪表板会按订单报告 OpenAI Token 和 Web 搜索成本、毛利润及利润率。USDC 生产环境结算以及公共 MCP、A2A、x402 和 MPP 目录发现机制均已通过验证。MPP Stripe 已通过隔离的双账户沙盒支付测试；真实的线上模式银行卡扣款仍是验收要求。下一个里程碑是增加证据运营能力并持续监控目录健康状况。

Niche Manager 运行时和部署：运营。

Photo Scout 的 Agent API 已公开，地址为 https://api.aisoup.net/photo-scout/mcp。 免费工具 list_photo_scout_prices 会说明定价和覆盖范围；付费工具 discover_photo_spots 使用 x402 MCP，费用为 2 美元（Base USDC）。HTTP 端点 仍支持 MPP，面向用户的网站则继续提供免费预览。其官方 MCP Registry 记录 已通过公开验证。Photo Scout 也已列入 x402Scan 和 MPPScan，价格为每次搜索 2 美元。Smithery GitHub 授权已完成；发布仍待所有者验证电子邮件。尚未独立验证已结算的付款。请参阅发布元数据 和 API 文档。