跳转到主要内容

​
使用 Ruby SDK 运行

当你想从 Ruby 中向智能体发送消息时,请使用官方的 fetch_hive gem。该 SDK 封装了公开的 POST /v1/agent/invoke 端点,处理身份验证,通过块支持流式响应,并接受多模态输入。

​
安装

在 Gemfile 中添加: 
gem "fetch_hive"
然后运行: 
bundle install
或直接安装: 
gem install fetch_hive
该 gem 在底层使用 faraday,支持 Ruby 3.0+。

​
身份验证

将 FETCH_HIVE_API_KEY 环境变量设置为你的工作区 API 密钥(客户端会自动读取): 
export FETCH_HIVE_API_KEY=fhk_...

require "fetch_hive"

client = FetchHive::Client.new
或显式传入密钥: 
client = FetchHive::Client.new(api_key: "fhk_...")
请参阅 API Keys 了解如何创建和轮换密钥。

​
基本示例

向智能体发送消息并读取最终响应: 
require "fetch_hive"

client = FetchHive::Client.new

reply = client.invoke_agent(
  agent: "AGENT_UUID",
  message: "Summarize the latest AI infrastructure trends"
)

puts reply["response"]
请参阅非流式响应结构。

​
方法参考

关键字类型必填说明
agentString是智能体 ID
messageString是你想发送的消息
thread_idString否标识持久会话线程的任意字符串
messagesArray<Hash>否调用方管理的对话历史。每一项格式为:{ role: "user" | "assistant" | "system", content: String }。
image_urlsArray<String>否用于多模态输入、附加到当前 message 的 HTTPS 图像 URL
userString否在用户追踪中显示的不透明调用方标识符
metadataHash否由调用方定义的扁平元数据,用于审计和日志筛选。请参阅调用元数据
该 SDK 为 invoke_agent 注入 streaming: false。要进行流式调用,请使用 invoke_agent_stream(见下文)。

​
处理响应

reply = client.invoke_agent(agent: "AGENT_UUID", message: "Hello")

puts reply["response"]      # final text
puts reply["model"]         # model identifier
puts reply["usage"]         # token usage breakdown
puts reply["request_id"]    # use this to look up the run in Logs
puts reply["tool_calls"]    # tool invocations made during the run

​
流式

使用 invoke_agent_stream 在事件到达时接收 Server-Sent Events。该方法会将每个解析后的事件 hash 提供给块: 
client.invoke_agent_stream(
  agent: "AGENT_UUID",
  message: "Summarize the latest AI infrastructure trends",
  thread_id: "user-456-support-session"
) do |chunk|
  case chunk["type"]
  when "response"
    print chunk["response"]
    $stdout.flush
  when "tool"
    puts "\nCalling tool: #{chunk['tool']}"
  when "usage"
    puts "\n\nUsage: #{chunk['usage']}"
  end
end
该流会产出在 Invoke Agent → Response 中记录的相同事件类型:summary(在自动摘要触发时)、reasoning、response、tool、最终的 usage 事件,或在提供商在流过程中失败时的 error 事件。 如果省略块,该方法会返回一个可传递的 Enumerator: 
enum = client.invoke_agent_stream(agent: "AGENT_UUID", message: "Hello")
enum.each { |chunk| handle(chunk) }

​
多轮对话

​
持久化线程

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

client.invoke_agent(
  agent: "AGENT_UUID",
  message: "Which of those trends have the most enterprise adoption?",
  thread_id: "user-456-support-session"
)

​
无状态历史

自行管理状态,在 messages 中传入先前的回合。Fetch Hive 会将提供的历史用作上下文,但不会持久化: 
client.invoke_agent(
  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 在当前消息上附加图像: 
result = client.invoke_agent(
  agent: "vision-agent",
  message: "Describe this image",
  image_urls: ["https://example.com/photo.jpg"]
)
puts result["response"]
URL 必须以 https:// 开头。

​
配置

选项默认值说明
api_keyENV["FETCH_HIVE_API_KEY"]控制台中的 Bearer 令牌
base_urlhttps://api.fetchhive.com/v1覆盖 API 基础 URL
timeout120请求超时(秒)
client = FetchHive::Client.new(
  api_key: "fhk_...",
  base_url: "https://api.fetchhive.com/v1",
  timeout: 120
)

​
错误

非 2xx 响应会引发带状态码和响应体的 RuntimeError。如果你需要处理失败,请使用 rescue 捕获: 
begin
  reply = client.invoke_agent(agent: "AGENT_UUID", message: "Hello")
rescue => e
  warn "Fetch Hive error: #{e.message}"
end
请参阅错误和速率限制了解状态码含义。

​
链接

​
下一步