Ejecutar con el SDK de Ruby

Usa la gema oficial fetch_hive cuando quieras invocar un deployment de flujo de trabajo desde Ruby. El SDK envuelve el endpoint público POST /v1/workflow/invoke, maneja la autenticación y admite tanto respuestas directas como entrega por callback.

Instalación

Agrega a tu Gemfile:

gem "fetch_hive"

Luego ejecuta:

bundle install

O instálala directamente:

gem install fetch_hive

La gema usa faraday por debajo y admite Ruby 3.0+.

Autenticación

Configura la variable de entorno FETCH_HIVE_API_KEY con tu clave de API del workspace (el cliente la lee automáticamente):

export FETCH_HIVE_API_KEY=fhk_...

require "fetch_hive"

client = FetchHive::Client.new

O pasa la clave explícitamente:

client = FetchHive::Client.new(api_key: "fhk_...")

Consulta API Keys para saber cómo crear y rotar claves.

Ejemplo básico

Ejecuta un deployment de flujo de trabajo directamente. La llamada se bloquea hasta que el flujo de trabajo termina:

require "fetch_hive"

client = FetchHive::Client.new

run = client.invoke_workflow(
  deployment: "YOUR_DEPLOYMENT_NAME",
  variant: "YOUR_VARIANT_NAME",
  inputs: { topic: "State of enterprise AI in 2026" }
)

puts run["run_status"]
puts run["output"]

Consulta la forma de respuesta directa.

Referencia del método

Palabra clave	Tipo	Requerido	Descripción
`deployment`	`String`	Sí	El nombre del deployment del flujo de trabajo
`variant`	`String`	No	El nombre de la variante del deployment
`inputs`	`Hash`	No	Pares clave-valor para las variables definidas en el paso Start
`async_mode`	`Boolean`	No	Cuando es `true`, devuelve respuesta inmediatamente y entrega el resultado mediante callback firmado
`callback_url`	`String`	No	Requerido cuando `async_mode: true` - la URL HTTPS de callback a la que llamar cuando la ejecución termine
`user`	`String`	No	Identificador opaco de quien llama, expuesto en User Tracking
`metadata`	`Hash`	No	Metadata plana definida por quien llama, para auditoría y filtrado de registros. Consulta Metadata de invoke

invoke_workflow construye el cuerpo de la solicitud por ti. Cuando pasas async_mode: true, el SDK envía:

{
  "async": { "enabled": true, "callback_url": "https://example.com/webhook" }
}

Manejo de la respuesta

run = client.invoke_workflow(deployment: "my-workflow", variant: "default")

puts run["run_status"]    # "completed" | "failed" | "running" | "queued"
puts run["output"]        # final workflow output
puts run["request_id"]    # use this to look up the run in Logs

Entrega por callback

Pasa async_mode: true para devolver respuesta inmediatamente y hacer que Fetch Hive llame a tu URL de callback cuando la ejecución termine:

run = client.invoke_workflow(
  deployment: "YOUR_DEPLOYMENT_NAME",
  variant: "YOUR_VARIANT_NAME",
  inputs: { topic: "State of enterprise AI in 2026" },
  async_mode: true,
  callback_url: "https://example.com/callback"
)

puts "Queued: #{run['run_status']}"
puts "Webhook secret: #{run['webhook_secret']}"

Almacena el webhook_secret para que puedas verificar la firma en el callback entrante. Consulta Entrega por callback y disparadores de webhook para el flujo de verificación y la forma del payload firmado.

Configuración

Opción	Predeterminado	Descripción
`api_key`	`ENV["FETCH_HIVE_API_KEY"]`	Token bearer del dashboard
`base_url`	`https://api.fetchhive.com/v1`	Sobrescribe la URL base de la API
`timeout`	`120`	Timeout de la solicitud en segundos - aumenta para solicitudes directas de flujos de trabajo de larga duración

client = FetchHive::Client.new(
  api_key: "fhk_...",
  base_url: "https://api.fetchhive.com/v1",
  timeout: 600
)

Errores

Las respuestas distintas a 2xx lanzan un RuntimeError con el código de estado y el cuerpo. Rescátalas si necesitas manejar fallos:

begin
  run = client.invoke_workflow(deployment: "my-workflow", variant: "default")
rescue => e
  warn "Fetch Hive error: #{e.message}"
end

Consulta Manejo de errores para los casos de fallo específicos del flujo de trabajo y Errors and Rate Limits para el significado de los códigos de estado HTTP.

Enlaces

Siguientes pasos

Entrega por callback y disparadores de webhook - Verifica las firmas de callback
Ejecutar con API - El mismo flujo con cURL
Ejecutar con el SDK de Python
Ejecutar con el SDK de Node.js
Ejecutar con el SDK de PHP
Invoke Workflow - Referencia completa del endpoint

Primeros pasos

Live Chat

Prompts

Flujos de trabajo

Hive Agents

Agentes

Bases de conocimientos

Experimentos

Tu espacio de trabajo

Monitoreo

Seguimiento de usuarios

Recursos

Ejecutar con el SDK de Ruby

Ejecutar con el SDK de Ruby

Instalación

Autenticación

Ejemplo básico

Referencia del método

Manejo de la respuesta

Entrega por callback

Configuración

Errores

Enlaces

Siguientes pasos

​Ejecutar con el SDK de Ruby

​Instalación

​Autenticación

​Ejemplo básico

​Referencia del método

​Manejo de la respuesta

​Entrega por callback

​Configuración

​Errores

​Enlaces

​Siguientes pasos

Ejecutar con el SDK de Ruby

Instalación

Autenticación

Ejemplo básico

Referencia del método

Manejo de la respuesta

Entrega por callback

Configuración

Errores

Enlaces

Siguientes pasos