Run with Ruby SDK

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

Keyword	Type	Required	Description
`agent`	`String`	Yes	The agent ID
`message`	`String`	Yes	The message you want to send
`thread_id`	`String`	No	An arbitrary string identifying a persistent conversation thread
`messages`	`Array<Hash>`	No	Caller-managed conversation history. Each item: `{ role: "user" \| "assistant" \| "system", content: String }`.
`user`	`String`	No	Opaque caller identifier surfaced in User Tracking
`metadata`	`Hash`	No	Flat caller-defined metadata for audit and log filtering. See Invoke metadata
`tool_approval`	`"policy" \| "auto_approve"`	No	Omit it, or send `"policy"`, to follow saved rules. `"auto_approve"` applies to this call only when the API key is allowed to auto-approve actions.

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 attachments:

result = client.invoke_agent(
  agent: "vision-agent",
  message: "Describe this image",
  attachments: ["https://example.com/photo.jpg"]
)
puts result["response"]

URLs must start with https://.

Configuration

Option	Default	Description
`api_key`	`ENV["FETCH_HIVE_API_KEY"]`	Bearer token from the dashboard
`base_url`	`https://api.fetchhive.com/v1`	Override the API base URL
`timeout`	`120`	Request 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

Run with API - The same flow with cURL
Run with Python SDK
Run with Node.js SDK
Run with PHP SDK
Invoke Agent - Full endpoint reference

Tool approvals

When a tool needs approval, the invoke response has status: "awaiting_approval" and pending_tool_approvals. Decide with decide_tool_action_approval. decision is "allow_once" or "deny". List pending approvals with list_tool_action_approvals, or fetch one with get_tool_action_approval. always_allow is only available in the dashboard. An API key call resumes on the server after the decision. Poll the run or use the webhook. Do not send decided_tool_approvals. A workspace owner or admin can allow this API key to auto-approve actions in Settings → API keys. Pass tool_approval as "auto_approve" on invoke_agent, invoke_agent_stream, or invoke_workflow. That applies to this call only. Omit the field, or pass "policy", to follow workspace rules and any saved auto-approve switch. Destructive actions still ask. Deny rules still block the action. See Tool approvals.

Getting Started

Live Chat

Prompts

Workflows

Hive Agents

Agents

Knowledge Bases

Your Workspace

Monitoring

User Tracking

MCP Gateway

Resources

Installation

Authentication

Basic example

Method reference

Handling the response

Streaming

Multi-turn conversations

Persistent threads

Stateless history

Multimodal inputs

Configuration

Errors

Links

Next steps

Tool approvals

​Installation

​Authentication

​Basic example

​Method reference

​Handling the response

​Streaming

​Multi-turn conversations

​Persistent threads

​Stateless history

​Multimodal inputs

​Configuration

​Errors

​Links

​Next steps

​Tool approvals

Installation

Authentication

Basic example

Method reference

Handling the response

Streaming

Multi-turn conversations

Persistent threads

Stateless history

Multimodal inputs

Configuration

Errors

Links

Next steps

Tool approvals