跳转到主要内容

​
使用 Node.js SDK 运行

当你想从 Node.js 或 TypeScript 中向智能体发送消息时,请使用官方的 @fetch-hive/sdk 包。该 SDK 封装了公开的 POST /v1/agent/invoke 端点,处理身份验证,以 AsyncIterable 的形式公开流式响应,并支持多模态输入。

​
安装

npm install @fetch-hive/sdk
# or
yarn add @fetch-hive/sdk
# or
pnpm add @fetch-hive/sdk
该 SDK 面向 Node.js 18+(使用全局 fetch),并附带 TypeScript 类型。

​
身份验证

将 FETCH_HIVE_API_KEY 环境变量设置为你的工作区 API 密钥: 
export FETCH_HIVE_API_KEY=fhk_...

import { FetchHive } from '@fetch-hive/sdk';

const client = new FetchHive();
或显式传入密钥: 
const client = new FetchHive({ apiKey: 'fhk_...' });
请参阅 API Keys 了解如何创建和轮换密钥。

​
基本示例

向智能体发送消息并读取最终响应: 
import { FetchHive } from '@fetch-hive/sdk';

const client = new FetchHive();

const reply = await client.invokeAgent({
  agent: 'AGENT_UUID',
  message: 'Summarize the latest AI infrastructure trends',
});

console.log(reply.response);
请参阅非流式响应结构。

​
方法参考

字段类型必填说明
agentstring是智能体 ID
messagestring是你想发送的消息
thread_idstring否标识持久会话线程的任意字符串
messagesArray<{ role, content, image_urls? }>否调用方管理的对话历史
image_urlsstring[]否用于多模态输入、附加到当前 message 的 HTTPS 图像 URL
userstring否在用户追踪中显示的不透明调用方标识符
metadataRecord<string, string | number | boolean | null>否由调用方定义的扁平元数据,用于审计和日志筛选。请参阅调用元数据
该 SDK 为 invokeAgent 注入 streaming: false。要进行流式调用,请使用 invokeAgentStream(见下文)。

​
处理响应

const reply = await client.invokeAgent({
  agent: 'AGENT_UUID',
  message: 'Hello',
});

console.log(reply.response);     // final text
console.log(reply.model);        // model identifier
console.log(reply.usage);        // token usage breakdown
console.log(reply.request_id);   // use this to look up the run in Logs
console.log(reply.tool_calls);   // tool invocations made during the run

​
流式

使用 invokeAgentStream 在事件到达时接收 Server-Sent Events。该方法返回一个 AsyncIterable: 
for await (const chunk of client.invokeAgentStream({
  agent: 'AGENT_UUID',
  message: 'Summarize the latest AI infrastructure trends',
  thread_id: 'user-456-support-session',
})) {
  if (chunk.type === 'response') {
    process.stdout.write(chunk.response ?? '');
  } else if (chunk.type === 'tool') {
    console.log(`\n[Calling tool: ${chunk.tool}]`);
  } else if (chunk.type === 'usage') {
    console.log('\n\nUsage:', chunk.usage);
  }
}
该流会产出在 Invoke Agent → Response 中记录的相同事件类型:summary(在自动摘要触发时)、reasoning、response、tool、最终的 usage 事件,或在提供商在流过程中失败时的 error 事件。

​
多轮对话

​
持久化线程

将任意字符串作为 thread_id 传入,Fetch Hive 会在首次调用时创建该线程,并在每次使用相同值的后续调用中恢复该线程: 
await client.invokeAgent({
  agent: 'AGENT_UUID',
  message: 'What are the main AI infrastructure trends right now?',
  thread_id: 'user-456-support-session',
});

await client.invokeAgent({
  agent: 'AGENT_UUID',
  message: 'Which of those trends have the most enterprise adoption?',
  thread_id: 'user-456-support-session',
});

​
无状态历史

自行管理状态,在 messages 中传入先前的回合。Fetch Hive 会将提供的历史用作上下文,但不会持久化: 
await client.invokeAgent({
  agent: 'AGENT_UUID',
  message: 'Which of those trends have the most enterprise adoption?',
  messages: [
    { role: 'user', content: 'What are the main AI infrastructure trends right now?' },
    { role: 'assistant', content: 'Teams are focusing on evals, tool routing, and observability.' },
  ],
});

​
多模态输入

使用 image_urls 在当前消息上附加图像: 
const result = await client.invokeAgent({
  agent: 'vision-agent',
  message: 'Describe this image',
  image_urls: ['https://example.com/photo.jpg'],
});
console.log(result.response);
URL 必须以 https:// 开头。

​
配置

选项默认值说明
apiKeyprocess.env.FETCH_HIVE_API_KEY控制台中的 Bearer 令牌
baseURLhttps://api.fetchhive.com/v1覆盖 API 基础 URL
const client = new FetchHive({
  apiKey: 'fhk_...',
  baseURL: 'https://api.fetchhive.com/v1',
});

​
错误

非 2xx 响应会抛出一个 Error,其消息包含状态码和响应体: 
try {
  const reply = await client.invokeAgent({
    agent: 'AGENT_UUID',
    message: 'Hello',
  });
} catch (err) {
  console.error('Fetch Hive error:', err);
}
请参阅错误和速率限制了解状态码含义。

​
链接

​
下一步