@gea-ai/app-sdk

中文文档
0.1.261111-alpha.1发布于 2026/11/12Apache-2.0TypeScriptES Module近 30 天下载 3936

用于与GEA整合的应用程序的公共 SDK.

此软件包已被标记为弃用

This package is deprecated and will no longer receive updates.

中文使用文档
文档目录7 节
  1. OAuth 客户端
  2. 用户授权
  3. 租户授权
  4. ORPC 客户端
  5. 代理聊天
  6. API 密钥代理聊天
  7. AI SDK浏览器集成

@gea-ai/app-sdk

用于使用 GEA OAuth 或组织 API 密钥的应用程序的服务器端助手.

每个软件包都有一个 client_id 还有一个客户秘密 安装它创建 拥有的组织 app_resource;其id是不可改变的安装ID.

保密客户 授权代码 刷新信使 和访问信使 在附录后端。 浏览器代码只应接收应用程序自己的会话.

OAuth 客户端

import { createOAuthClient } from "@gea-ai/app-sdk";

const gea = createOAuthClient({
  baseUrl: process.env.GEA_BASE_URL!,
  clientId: process.env.GEA_CLIENT_ID!,
  clientSecret: process.env.GEA_CLIENT_SECRET!,
});

SDK需要HTTPS,因为 OAuth 客户资格和无记名标志是 发送到此来源 。 Plain HTTP 只为本地开发主机接受 例如 musegea.localhost,它的租户子域, localhost和回转.

用户授权

当用户从 GEA 打开已安装的应用程序时, 启动 URL 包括公众 client_id, (中文(简体) ), installation_id,以及 organization_id。使用组织标识 作为不信任的选择器,创建随机 state 和应用程序中的 PKCE 验证器 后端,然后将浏览器重定向到 GEA :

const authorizationUrl = gea.getAuthorizationUrl({
  codeChallenge,
  organizationId,
  redirectUri: "https://app.example.com/oauth/callback",
  scope: ["openid", "profile", "offline_access", "resources:read"],
  state,
});

GEA 对照 OAuth 客户端验证选择器, 激活安装, 以及 注册用户的活跃成员。 选择者不准许访问 自己来 不支持在没有组织选择者的情况下直接授权 在此版本中.

验证后 state 在回调中,交换一次性代码:

const token = await gea.exchangeAuthorizationCode({
  code,
  codeVerifier,
  redirectUri: "https://app.example.com/oauth/callback",
});

答复包括核实 organization 财务报告和审定财务报表 installation 元数据。 这个 还包括当 offline_access 准予:

const renewed = await gea.refreshUserToken({
  refreshToken: token.refreshToken!,
});

刷新符号旋转 。 坚持每个成功者返回的替换 刷新并丢弃上一个值.

当应用程序会话或证书结束时撤销访问权限或刷新令牌 在其他方面不再需要:

await gea.revokeToken({
  token: token.accessToken,
  tokenTypeHint: "access_token",
});

租户授权

只为不作为用户的应用级API使用租户代币. 一个 组织本地应用程序省略了安装选择器,因为 GEA 推断它 拥有的组织:

const tenantToken = await gea.getTenantToken({
  scope: ["organization:read", "resources:read"],
});

一个“市场”应用程序提供不可改变的安装ID:

const tenantToken = await gea.getTenantToken({
  installationId: "019...",
  scope: ["organization:read", "resources:read"],
});

绝不接受一个组织发射弹作为授权边界。 租户 符号不包含用户主机,不能调用用户,成员,或 工作空间成员 APIs.

ORPC 客户端

创建 API 客户端, 使用用户或租户访问符 :

import { createClient } from "@gea-ai/app-sdk";

const api = createClient({
  accessToken: token.accessToken,
  baseUrl: process.env.GEA_BASE_URL!,
});

只有明确接受符号类型和范围的道路可供使用. GEA重新验证 OAuth 客户端,软件包,安装,组织, 属于用户代号的成员,并请求为每个请求提供范围.

resources.list() 返回活动组织拥有的资源 与所有工作空间或至少一个特定工作空间共享。 用户拥有和 不包括仅限用户的资源.

代理聊天

代理聊天 API 需要用户访问令牌 agents:read, (中文(简体) ), agent_chats:read,和(或) agent_chats:write。租户代币不能使用这些 范围,因为每个聊天都以授权用户的身份运行在一个明确的 工作空间.

从符号响应中创建工作空间客户端 和您的应用程序所选择或配置的工作空间弹片 :

import { createWorkspaceClient } from "@gea-ai/app-sdk";

const gea = createWorkspaceClient({
  accessToken: token.accessToken,
  baseUrl: process.env.GEA_BASE_URL!,
  organizationSlug: token.organization.slug,
  workspaceSlug: appWorkspaceSlug,
});

const agents = await gea.agents.list();
const run = await gea.agentChats.start({
  agentId: agents[0]!.id,
  message: "Summarize the latest project context.",
});

const { chatId } = run;
const stream = await gea.agentChats.openStream({ chatId });
// Consume stream.body as an AI SDK UI message stream.

await gea.agentChats.sendMessage({
  chatId,
  message: "Turn that into three action items.",
});

const page = await gea.agentChats.messages.list({ chatId, limit: 50 });

当SDK第一代理暂停工具批准时,请读取待处理的助手 发送信息并提交决定,而不重复工具输入:

await gea.agentChats.respondToToolApprovals({
  chatId,
  messageId: pendingMessage.id,
  responses: [{ id: pendingApproval.id, approved: true }],
});

同样的"聊天"方法也与"后人"合作. 运行时间选择为自有 被选中的代理服务器侧元数据; 工具批准响应是 仅接受SDK第一代理工作聊天.

Agent APIs拒绝只组织RPC路线. 工作空间的子弹必须 显示在请求路由中; GEA 从未为一个 第三方应用.

GEA生成持续聊天和消息ID. 读取 chatId 产生结果 agentChats.start() 并用于后流,消息,和历史召来. start() 财务报告和审定财务报表 sendMessage() 目前不提供一能重试 语义, 因此在模糊后不要自动重试两个操作 网络故障. 在相应的范围下,应用程序可以读取或继续 所选组织中授权用户拥有的任何根聊天,以及 工作空间;聊天不必来自该应用程序。 创建聊天 通过此 API 记录源安装 chat.metadata 页:1 仅是出处,不是授权边界.

openStream() 交换用户代号服务器侧以换取短寿命, 聊天串流能力,然后以 那个能力 该能力仍然与该确切的OAuth赠款有关: 重新检查补助金、其阅读范围和用户当前工作空间的访问 当溪口被打开的时候, 取消补助金或取消工作空间访问使 已经发布的能力无法使用。 保留用户符和流 响应; 只转发您自己的前端需要的数据。 吉亚 简短地等待一个新的聊天程序来注册其流 。 如果反应是 503 与 Retry-After电话 openStream() 同样的 chatIdA级 204 响应是指在串流消费者前完成的运行; 呼叫 agentChats.messages.list() 同样的 chatId 读取最后信件.

流电能力只包含不透明的授电、安装和聊天 参考文献。 GEA 解决用户、组织、安装和工作空间 当流打开时服务器侧. 信件页面保存代理发送元数据 但编辑GEA用户的内部身份和名称. 使用 OAuth 对称 sub 财务报告和审定财务报表 当您的应用程序需要用户身份时,明确授权的配置文件请求.

API 密钥代理聊天

使用 createApiKeyWorkspaceClient 对于API键唯一的代理表面。 一个用户 键省略 externalUserId 他只派遣他的证明

import { createApiKeyWorkspaceClient } from "@gea-ai/app-sdk";

const gea = createApiKeyWorkspaceClient({
  apiKey: process.env.GEA_API_KEY!,
  baseUrl: process.env.GEA_BASE_URL!,
  organizationSlug: "acme",
  workspaceSlug: "research",
});

const chatId = crypto.randomUUID();
const stream = await gea.agentChats.run({
  agentId: "agent-019...",
  chatId,
  message: "Summarize this workspace.",
});

if (!stream.ok || !stream.body) {
  throw new Error(`Agent Chat failed: ${stream.status}`);
}

团队密钥必须为一个目录身份创建客户端. 设定 externalUserId 到精确的大小写敏感目录 principalId 编号 : externalId; SDK 发送为 x-user-id 每项RPC请求:

const gea = createApiKeyWorkspaceClient({
  apiKey: process.env.GEA_TEAM_API_KEY!,
  baseUrl: process.env.GEA_BASE_URL!,
  externalUserId: customerDirectoryPrincipalId,
  organizationSlug: "acme",
  workspaceSlug: "research",
});

部署必须能够 features.teamApiKeyIdentityDelegation组合键 仅限于此代理API及其三个代理范围 一般范围 ORPC 路由只接受个人密钥.

客户暴露 agents.list(), (中文(简体) ), agentChats.run(), (中文(简体) ), agentChats.openStream(), (中文(简体) ), agentChats.messages.list(),以及 agentChats.files.resolve()。 。 。 . run() 发送一个 POST /api/chat 请求和 直接返回它的 AI SDK UI 消息流. 在服务器上存储两种API密钥. 不转发团队密钥或让一个 浏览器选择 x-user-id 独立于经认证的客户用户.

API 密钥代理访问使用独立的 agents.read, (中文(简体) ), agent_chats.read, (中文(简体) ), 财务报告和审定财务报表 agent_chats.write 范围; OAuth 的结号限制范围仍然保留 不变. run() 需求 agent_chats.write· ; openStream() 并坚持 信件读取要求 agent_chats.read。两个直接的 HTTP 请求发送 相同的API 密钥, 对于一个团队密钥, 相同的固定 x-user-id全球环境评估决定 身份并重新检查密钥、 用户、 聊天所有权和工作空间访问 每一个请求.

不自动重试 run() 经过一个模糊的结果。 A 类 503 流线 答复可通过拨打重新测试 openStream() 与现有 chatId· ; 之后 204,读取最后的恒定消息 agentChats.messages.list()。 。 。 .

要附加文件, 请打电话 files.upload({ file, filename })它发送一个 多块 POST /api/files 并附有同一份全权证书 agent_chats.write,然后返回原始数据 Response页:1 201 机构包含 文件 id。通过这些标识作为 fileIds 改为 run() 加上字符串 message数字 :

const uploaded = await gea.files.upload({
  file: pdfBlob,
  filename: "report.pdf",
});
if (uploaded.status !== 201) {
  throw new Error(`Upload failed: ${uploaded.status}`);
}
const { id } = await uploaded.json();

const stream = await gea.agentChats.run({
  agentId: "agent-019...",
  chatId,
  fileIds: [id],
  message: "Analyze this report.",
});

每个文件最多20个MIB,最多接受10个运行 fileIds。一个文件可以 仅供上传该文本的用户在同一工作空间使用一次; a 无法使用 id 使 run() 返回时 404 没有开始运行.

一个代理人指的是它用下方的Markdown路径生成的文件 /workspace 内 其答案文本,例如 ![Revenue chart](/workspace/charts/revenue.png) 或者说 [Q3 report](/workspace/reports/q3.pdf); 流和持续消息 保持文本不变。 要显示这样的文件, 请将路径交换为 临时 URL 与 agentChats.files.resolve({ chatId, path })它使用 工作空间RPC和全权证书与 messages.list 和要求 agent_chats.read数字 :

const file = await gea.agentChats.files.resolve({
  chatId,
  path: "/workspace/charts/revenue.png",
});
// { path, contentType, sizeBytes, url }

url 临时 : 每次给出答案后再次解析路径 永远不要储存它。 PNG、JPEG、WebP和GIF文件返回可嵌入的URL; PDF, HTML, SVG 和所有其他类型都返回附件下载 URL. 这个 文件在请求时被读取, 因此一个覆盖的文件显示其当前 内容,而删除的文件、目录、符号链接或聊天用户 不拥有返回 NOT_FOUND。非条形路径(除了一条 绝对 /workspace/... 没有文件路径 ., (中文(简体) ), .. 或空块)是 以 BAD_REQUEST,并且存储或签名失败表面为 INTERNAL_SERVER_ERROR 而不是作为一个缺失的文件。 API 密钥保留在 服务器,只将临时URL传递给浏览器.

AI SDK浏览器集成

教书是 代理反应 在 GEA 开发者文档中。 这里包含同样的SDK核心模式 读者.

GEA 返回一个 AI SDK 用户界面消息流, (中文(简体) ), 但GEA用户访问符和短寿命流能力必须保留 在应用程序服务器上。 在自己的应用程序中显示一个认证的路由,打开 GEA流并转发其正文和协议头到浏览器:

// app/api/gea-agent-chat/route.ts
import { createWorkspaceClient } from "@gea-ai/app-sdk";

const streamHeaders = [
  "cache-control",
  "content-type",
  "retry-after",
  "x-vercel-ai-ui-message-stream",
] as const;

async function getGeaForCurrentUser() {
  // Load and refresh the current user's OAuth token in your app backend.
  const connection = await loadUserGeaConnection();

  return createWorkspaceClient({
    getAccessToken: connection.getAccessToken,
    baseUrl: "https://musegea.com",
    organizationSlug: connection.organizationSlug,
    workspaceSlug: connection.workspaceSlug,
  });
}

export async function POST(request: Request) {
  const { agentId, message } = await request.json();
  const gea = await getGeaForCurrentUser();

  // Do not automatically retry this write after an ambiguous network failure.
  const run = await gea.agentChats.start({ agentId, message });
  return Response.json({ chatId: run.chatId });
}

export async function GET(request: Request) {
  const search = new URL(request.url).searchParams;
  const chatId = search.get("chatId");
  const view = search.get("view");
  if (!chatId || (view !== "messages" && view !== "stream")) {
    return new Response("chatId and view are required", { status: 400 });
  }

  const gea = await getGeaForCurrentUser();
  if (view === "messages") {
    return Response.json(
      await gea.agentChats.messages.list({ chatId, limit: 50 }),
    );
  }

  const upstream = await gea.agentChats.openStream({ chatId });
  const headers = new Headers();

  for (const name of streamHeaders) {
    const value = upstream.headers.get(name);
    if (value) headers.set(name, value);
  }

  return new Response(upstream.body, {
    headers,
    status: upstream.status,
    statusText: upstream.statusText,
  });
}

浏览器可以使用 ai 解码中继响应的软件包。 这个 运算子类曝光AI SDK的普通响应-流解析器; 浏览器 无需了解电线协议本身:

"use client";

import { DefaultChatTransport, readUIMessageStream, type UIMessage } from "ai";
import { useState } from "react";

class GeaStreamTransport extends DefaultChatTransport<UIMessage> {
  decode(stream: ReadableStream<Uint8Array>) {
    return this.processResponseStream(stream);
  }
}

const transport = new GeaStreamTransport();

function textFromMessage(message: UIMessage) {
  return message.parts
    .filter((part) => part.type === "text")
    .map((part) => part.text)
    .join("");
}

async function openStream(chatId: string) {
  for (let attempt = 0; attempt < 3; attempt += 1) {
    const response = await fetch(
      `/api/gea-agent-chat?view=stream&chatId=${encodeURIComponent(chatId)}`,
    );
    if (response.status !== 503) return response;

    const retryAfter = Number(response.headers.get("retry-after"));
    await response.arrayBuffer();
    await new Promise((resolve) =>
      window.setTimeout(
        resolve,
        Number.isFinite(retryAfter) && retryAfter > 0
          ? Math.min(retryAfter * 1000, 5000)
          : 500,
      ),
    );
  }

  throw new Error("The Agent stream was not ready after three attempts.");
}

export function AgentResult() {
  const [text, setText] = useState("");
  const [persistedMessages, setPersistedMessages] = useState<unknown>(null);

  async function run() {
    const startResponse = await fetch("/api/gea-agent-chat", {
      method: "POST",
      headers: { "content-type": "application/json" },
      body: JSON.stringify({
        agentId: "agent-019...",
        message: "Summarize this workspace.",
      }),
    });
    if (!startResponse.ok) throw new Error("Could not start Agent chat");
    const started = (await startResponse.json()) as { chatId: string };

    const response = await openStream(started.chatId);

    // 204 means the run completed before the stream attached. In that case,
    // skip the loop and read the persisted result below.
    if (response.status !== 204) {
      if (!response.ok || !response.body) throw new Error("Stream failed");

      const chunks = transport.decode(response.body);
      for await (const message of readUIMessageStream<UIMessage>({
        stream: chunks,
        terminateOnError: true,
      })) {
        setText(textFromMessage(message));
      }
    }

    const messagesResponse = await fetch(
      `/api/gea-agent-chat?view=messages&chatId=${encodeURIComponent(started.chatId)}`,
    );
    if (!messagesResponse.ok) throw new Error("Could not load final messages");
    setPersistedMessages(await messagesResponse.json());
  }

  return (
    <section>
      <button onClick={run} type="button">
        Run Agent
      </button>
      <pre>{text}</pre>
      <pre>{JSON.stringify(persistedMessages, null, 2)}</pre>
    </section>
  );
}

流出后持续读取是真相的来源 完成得太快,无法附加流或当浏览器重新连接时。 对a 完成 Next.j 的操作,并进行更详细的错误处理,请跟踪 公开 代理反应 教学.

版本与发布记录

@gea-ai/app-sdk 共发布 108 个版本,首次发布于 2026/07/21;过去 12 个月发布了 108 个版本。

版本发布日期距今
0.1.261111-alpha.1latest2026/11/123 天前
0.1.261111-alpha.02026/11/124 天前
0.1.261106-alpha.02026/11/069 天前
0.1.261102-alpha.22026/11/0213 天前
0.1.261102-alpha.12026/11/0213 天前
0.1.261102-alpha.02026/11/0213 天前

关于 @gea-ai/app-sdk 的常见问题

@gea-ai/app-sdk 是什么?

用于与GEA整合的应用程序的公共 SDK.注意:该包已被作者标记为弃用——This package is deprecated and will no longer receive updates.

如何安装 @gea-ai/app-sdk?

在项目目录运行 npm install @gea-ai/app-sdk,或使用 pnpm add / yarn add / bun add。

@gea-ai/app-sdk 支持 TypeScript 吗?

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

@gea-ai/app-sdk 支持 ESM 还是 CommonJS?

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

@gea-ai/app-sdk 可以商用吗?

@gea-ai/app-sdk 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@gea-ai/app-sdk 的下载量有多少?

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

@gea-ai/app-sdk 还在维护吗?

最新版本 0.1.261111-alpha.1 发布于 2026/11/12(3 天前);至今共发布 108 个版本,其中过去 12 个月发布了 108 个;首次发布于 2026/07/21。作者已将其标记为弃用,新项目建议寻找替代方案。