Skip to main content
Use the official fetch_hive gem when you want to send a message to an agent from Ruby. The SDK wraps the public POST /v1/agent/invoke endpoint, handles authentication, supports streaming via a block, and accepts multimodal inputs.

​
Installation

Add to your Gemfile: 
gem "fetch_hive"
Then run: 
bundle install
Or install directly: 
gem install fetch_hive
The gem uses faraday under the hood and supports Ruby 3.0+.

​
Authentication

Set the FETCH_HIVE_API_KEY environment variable to your workspace API key (the client reads it automatically): 
export FETCH_HIVE_API_KEY=fhk_...

require "fetch_hive"

client = FetchHive::Client.new
Or pass the key explicitly: 
client = FetchHive::Client.new(api_key: "fhk_...")
See API Keys for how to create and rotate keys.

​
Basic example

Send a message to an agent and read the final response: 
require "fetch_hive"

client = FetchHive::Client.new

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

puts reply["response"]
See the non-streaming response shape.

​
Method reference

KeywordTypeRequiredDescription
agentStringYesThe agent ID
messageStringYesThe message you want to send
thread_idStringNoAn arbitrary string identifying a persistent conversation thread
messagesArray<Hash>NoCaller-managed conversation history. Each item: { role: "user" | "assistant" | "system", content: String }.
image_urlsArray<String>NoHTTPS image URLs attached to the current message for multimodal inputs
userStringNoOpaque caller identifier surfaced in User Tracking
metadataHashNoFlat caller-defined metadata for audit and log filtering. See Invoke metadata
The SDK injects streaming: false for invoke_agent. To stream, use invoke_agent_stream (below).

​
Handling the response

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

​
Streaming

Use invoke_agent_stream to receive Server-Sent Events as they arrive. The method yields each parsed event hash to the block: 
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
The stream yields the same event types documented in Invoke Agent → Response: summary (when auto-summarization fires), reasoning, response, tool, a final usage event, or an error event if the provider fails mid-stream. If you omit the block, the method returns an Enumerator you can pass around: 
enum = client.invoke_agent_stream(agent: "AGENT_UUID", message: "Hello")
enum.each { |chunk| handle(chunk) }

​
Multi-turn conversations

​
Persistent threads

Pass any string as thread_id and Fetch Hive will create the thread on the first call and resume it on subsequent calls with the same value: 
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"
)

​
Stateless history

Manage state yourself by passing the previous turns in messages. Fetch Hive uses the supplied history for context but does not persist it: 
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." }
  ]
)

​
Multimodal inputs

Attach images to the current message with image_urls: 
result = client.invoke_agent(
  agent: "vision-agent",
  message: "Describe this image",
  image_urls: ["https://example.com/photo.jpg"]
)
puts result["response"]
URLs must start with https://.

​
Configuration

OptionDefaultDescription
api_keyENV["FETCH_HIVE_API_KEY"]Bearer token from the dashboard
base_urlhttps://api.fetchhive.com/v1Override the API base URL
timeout120Request timeout in seconds
client = FetchHive::Client.new(
  api_key: "fhk_...",
  base_url: "https://api.fetchhive.com/v1",
  timeout: 120
)

​
Errors

Non-2xx responses raise a RuntimeError with the status code and body. Rescue them if you need to handle failures: 
begin
  reply = client.invoke_agent(agent: "AGENT_UUID", message: "Hello")
rescue => e
  warn "Fetch Hive error: #{e.message}"
end
See Errors and Rate Limits for status code meanings.

​
Next steps