@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 内
其答案文本,例如  或者说
[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 的操作,并进行更详细的错误处理,请跟踪 公开 代理反应 教学.