@guuey/agent-client

中文文档
0.36.0发布于 2026/11/15MITTypeScriptES Module构建来源已验证近 30 天下载 7937

Client SDK for Guuey's agent runtime: the useAgentInvoke React hook + pure SSE helpers that speak the /agent/invoke streaming contract, plus the paginated thread-history read plane. Host adapters (storage / id / transport) are injected, so it runs on we

原始使用文档
文档目录5 节
  1. Three entry points
  2. React example
  3. Driving a turn without React
  4. React Native / Metro
  5. Support

@guuey/agent-client

The client SDK for a guuey agent's streaming contract:

  • POST /agent/invoke — a Server-Sent-Events stream (session / message / done / error frames) folded into a flat transcript.
  • GET /threads/:id/messages — the paginated history read plane, so a reload repaints the conversation before any new streaming starts.

The hook is platform-agnostic: thread-id storage, client-message-id generation, and the network transport (which also carries identity) are injected as adapters, so the same core runs on web (Next.js) and React Native.

npm install @guuey/agent-client

Three entry points

ImportContentsReact?
@guuey/agent-clientSSE helpers, invokeTurn, the thread-history reader, createWebAdapters, and all public types.No
@guuey/agent-client/reactThe useAgentInvoke hook (+ applyHistoryResult).Yes
@guuey/agent-client/transportOnly the invoke transport + guest-identity pieces — zero @guuey/mcp-apps-host in the import graph.No

The root subpath is React-free — importing it never pulls React in. React (react >=18) is an optional peer: only the ./react subpath needs it, so npm does not install it for you. If you import @guuey/agent-client/react, add react to your own dependencies.

React example

import { useAgentInvoke } from "@guuey/agent-client/react";
import { createWebAdapters } from "@guuey/agent-client";

export function Chat({ endpointUrl, appId }: { endpointUrl: string; appId: string }) {
  const adapters = createWebAdapters({ getAccessToken: async () => myToken });
  const { messages, send, status, activeTool, error } = useAgentInvoke({
    endpointUrl,
    appId,
    adapters,
  });

  return (
    <>
      {messages.map((m, i) => (
        <p key={i} data-role={m.role}>
          {m.text}
        </p>
      ))}
      {status === "connecting" && <p>Waking up…</p>}
      {status === "using-tool" && <p>Using {activeTool}…</p>}
      {error && <p role="alert">{error}</p>}
      <button disabled={status !== "ready"} onClick={() => send("hello")}>
        Send
      </button>
    </>
  );
}

status walks the turn lifecycle — ready → connecting → thinking / using-tool (with activeTool naming the tool) / responding → back to ready. Failures never occupy status; they land in error and the composer re-enables. The full vocabulary is documented at docs.guuey.com/sdk.

On React Native, supply your own adapters (AsyncStorage + an expo/fetch transport) in place of createWebAdapters — the hook's contract is identical.

Driving a turn without React

invokeTurn is the same wire walk as the hook, as a pure async generator — for a Node harness, a game loop, or any host with its own turn state machine. Its event stream is also the observation channel: tool results arrive as typed tool.done AgEvents, so telemetry is a filter, not a callback API.

import { invokeTurn, toInvokeUrl, fetchStreamTransport } from "@guuey/agent-client";

const req = {
  url: toInvokeUrl(endpointUrl),
  body: { input, clientMessageId: crypto.randomUUID() },
  signal: controller.signal,
};
// `getBearer` is resolved per attempt — a retry re-reads a fresh token.
const transport = (r) => fetchStreamTransport(r, null, null, { getBearer });

for await (const ev of invokeTurn(req, transport)) {
  if (ev.kind !== "message") continue;
  for (const agEvent of ev.agEvents) {
    if (agEvent.type === "tool.done") {
      telemetry.record(agEvent.toolCallId, agEvent.outcome ?? "ok");
    }
  }
  render(ev.assistantText); // full folded text — no delta bookkeeping
}

The transport retries cold-start 503s (the post-redeploy window) and capacity refusals (POD_SATURATED, WORKER_POD_RESOURCE_EXHAUSTED) by itself, never after the first streamed byte; tune or disable via its coldStartRetry option.

React Native / Metro

Every entry point resolves to the compiled ESM in dist/, for Metro as for Node and web bundlers. A stock Expo or React Native Metro config bundles it: no custom resolver and no transpilePackages-style configuration is needed.

Support

Questions and help: the guuey community on Discord — https://guuey.com/discord. Bugs and feature requests: https://github.com/withguuey/guuey-sdks/issues.

版本与发布记录

@guuey/agent-client 共发布 77 个版本,首次发布于 2026/07/20;过去 12 个月发布了 77 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.36.0latest2026/11/152 天前
0.35.02026/11/116 天前
0.34.02026/11/0610 天前
0.33.02026/11/0610 天前
0.32.02026/11/0610 天前
0.31.12026/09/291 个月前

其他发布通道:next → 0.16.15。

关于 @guuey/agent-client 的常见问题

@guuey/agent-client 是什么?

Client SDK for Guuey's agent runtime: the useAgentInvoke React hook + pure SSE helpers that speak the /agent/invoke streaming contract, plus the paginated thread-history read plane. Host adapters (storage / id / transport) are injected, so it runs on we

如何安装 @guuey/agent-client?

在项目目录运行 npm install @guuey/agent-client,或使用 pnpm add / yarn add / bun add。

@guuey/agent-client 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@guuey/agent-client 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@guuey/agent-client 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.12.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@guuey/agent-client 可以商用吗?

@guuey/agent-client 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@guuey/agent-client 的下载量有多少?

根据 npm 官方下载统计,@guuey/agent-client 在 2026/10/17 – 2026/11/15 这 30 天内被下载 7,937 次,日均约 265 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@guuey/agent-client 还在维护吗?

最新版本 0.36.0 发布于 2026/11/15(2 天前);至今共发布 77 个版本,其中过去 12 个月发布了 77 个;首次发布于 2026/07/20。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。