> ## Documentation Index
> Fetch the complete documentation index at: https://glasser.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 为产品中的 Agent 接入数据

通过 MCP、CLI 或自定义工具连接。Agent 选择数据， Glasser 负责获取。

## 选择集成方式

> [tab] MCP
>
> 适用于支持远程 MCP 的 Agent 框架。
>
> Your product
>
> Agent
> →
> MCP client
>
> →
> **Glasser**MCP tools
>
> **1. 配置连接**
>
> 使用 **Streamable HTTP**，将以下服务器添加到 MCP 客户端：
>
> ```text wrap theme={null}
> https://api.glasser.ai/mcp
> ```
>
> \*\*使用产品账号：\*\*创建 [API Key](https://app.glasser.ai/keys?locale=zh-CN)，并发送 `Authorization: Bearer <your Key>`。
>
> \*\*使用用户账号：\*\*使用相同请求头连接用户的 API Key，或通过支持 OAuth 的客户端进行 [MCP 浏览器登录](https://glasser.ai/docs/zh/mcp-server/other.md)。
>
> **2. 将工具提供给 Agent**
>
> 通过 `tools/list` 发现 Glasser 工具并注册到 Agent。详见[工具参考](https://glasser.ai/docs/zh/mcp-server.md#tools)。
>
> **3. 检查连接**
>
> 不带参数调用 `balance`。收到余额响应即表示连接正常，即使余额为零。此检查免费。

> [tab] CLI
>
> 适用于能够执行 shell 命令的 Agent。
>
> Your runtime
>
> Agent
> →
> **Glasser CLI**via shell
>
> →
> **Glasser**HTTP API
>
> **1. 安装 CLI**
>
> 在 Agent 运行环境中安装，需要 Node.js 22 或更高版本。
>
> ```bash wrap theme={null}
> npm install -g @glasser-ai/cli
> ```
>
> **2. 连接账号**
>
> 通过运行环境的密钥存储设置 `GLASSER_API_KEY`。
>
> \*\*使用产品账号：\*\*使用工作空间的 [API Key](https://app.glasser.ai/keys?locale=zh-CN)。\
> &#x20;\*\*使用用户账号：\*\*在该用户的隔离运行环境中加载其 API Key。
>
> **3. 检查连接**
>
> 为 Agent 提供 shell 工具，然后执行以下免费检查：
>
> ```bash wrap theme={null}
> glasser balance --json
> ```
>
> 使用 `--json` 获取机器可读结果。
>
> **参考：**[CLI 配置](https://glasser.ai/docs/zh/cli.md) · [搜索](https://glasser.ai/docs/zh/cli/search.md) · [检查](https://glasser.ai/docs/zh/cli/inspect.md) · [运行](https://glasser.ai/docs/zh/cli/run.md)

> [tab] 自定义工具 · API
>
> 适用于已有工具或数据提供商的产品。
>
> Your backend
>
> Agent
> →
> Your tools
>
> →
> **Glasser**HTTP API
>
> →
> **Providers**Your existing APIs
>
> **1. 连接后端**
>
> **服务地址：**`https://api.glasser.ai`\
> &#x20;**请求头：**`Authorization: Bearer <your Key>`
>
> \*\*使用产品账号：\*\*使用工作空间的 [API Key](https://app.glasser.ai/keys?locale=zh-CN)。\
> &#x20;\*\*使用用户账号：\*\*为每次请求选择该用户的 API Key。
>
> **2. 定义 Agent 工具**
>
> 将 [Glasser API 请求](https://glasser.ai/docs/zh/api-reference/overview.md#search-inspect-run) 封装为 `get_instagram_posts(username)` 等工具，并注册到 Agent。后端负责选择数据提供商并控制输出格式。
>
> **3. 检查连接**
>
> 发送经过认证的 [GET /v1/balance](https://glasser.ai/docs/zh/api-reference/balance/get.md) 请求。此检查免费。
>
> **参考：**[API 认证](https://glasser.ai/docs/zh/api-reference/overview.md#authenticate) · [API 流程](https://glasser.ai/docs/zh/api-reference/overview.md#search-inspect-run)

Run 使用所连接工作空间的余额。API Key 和访问令牌不得出现在模型消息或前端代码中。

## 为 Agent 提供工作流程

**搜索**接口 → **检查**输入和价格 → **运行**获取数据。

查询词、匹配接口和输入见 [Instagram 示例](https://glasser.ai/docs/zh/integrations/overview.md#example-check-an-instagram-creator)。搜索和检查均免费；后端应在发起 Run 前执行付费规则。

## 实现细节

> [accordion] Skill 与 Agent 指令
>
> 说明何时使用 Glasser，以及应调用哪些工具。基于 CLI 的 Agent 可从 [Glasser Skill](https://glasser.ai/SKILL.md) 开始。自定义工具则使用自己的工具名称和数据提供商偏好。
>
> 搜索时必须通过 `use_case` 提供用户需求，CLI 中使用 `--use-case`。将返回的 `task_id` 传给同一任务后续的搜索、检查和 Run， CLI 中使用 `--task`。
>
> 本地 CLI 开发且用户在场时，可通过 [glasser login](https://glasser.ai/docs/zh/cli/login.md) 在浏览器登录后保存 API Key。

> [accordion] 重试与未完成的 Run
>
> 为每次预期执行生成幂等键，并随请求保存。重试同一请求时复用该键：
>
> * MCP：工具参数 `idempotency_key`。
> * CLI：`--idempotency-key`，`run --json` 时必填。
> * HTTP API：请求头 `Idempotency-Key`。
>
> 对于 `QUEUED` 或 `RUNNING`，读取已有 Run 直至进入终态： MCP 使用 `runs_get`，CLI 使用 `glasser runs get -r <runId> --wait`，或调用 [HTTP 获取 Run](https://glasser.ai/docs/zh/api-reference/runs/get.md)。获取结果后继续 Agent 流程。
>
> 使用 `output` 前，同时检查 Run 的 `status` 和 `provider_response`。 `COMPLETED` 可能包含数据提供商错误；失败的 Run 仍可能产生费用。

> [accordion] 权限、付费与用量记录
>
> * 用户连接各自账号时，分别保存凭据，并从已登录用户的连接中选择，不要从模型参数中获取。
> * 使用 API Key 的 Policy 限制可用接口。在后端执行每用户付费上限；共用 API Key 会消耗同一个工作空间的余额。
> * 在产品任务记录中保留 Run ID 和 `charge_usd`。
> * 可由后端附加客户元数据用于追踪，不可用于权限控制。MCP 使用请求的 `_meta["glasser.ai/metadata"]`；元数据不是模型工具参数。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.