Ejecutar con el SDK de Ruby

Usa la gema oficial fetch_hive cuando quieras enviar un mensaje a un agente desde Ruby. El SDK envuelve el endpoint público POST /v1/agent/invoke, maneja la autenticación, admite streaming mediante un bloque y acepta entradas multimodales.

Instalación

Agrega a tu Gemfile:

gem "fetch_hive"

Luego ejecuta:

bundle install

O instala directamente:

gem install fetch_hive

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

Autenticación

Establece la variable de entorno FETCH_HIVE_API_KEY con la clave de API de tu espacio de trabajo (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 Claves de API para saber cómo crear y rotar claves.

Ejemplo básico

Envía un mensaje a un agente y lee la respuesta final:

require "fetch_hive"

client = FetchHive::Client.new

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

puts reply["response"]

Consulta el formato de respuesta sin streaming.

Referencia del método

Palabra clave	Tipo	Requerido	Descripción
`agent`	`String`	Sí	El ID del agente
`message`	`String`	Sí	El mensaje que quieres enviar
`thread_id`	`String`	No	Una cadena arbitraria que identifica un hilo de conversación persistente
`messages`	`Array<Hash>`	No	Historial de conversación administrado por el llamador. Cada elemento: `{ role: "user" \| "assistant" \| "system", content: String }`.
`image_urls`	`Array<String>`	No	URLs HTTPS de imágenes adjuntas al `message` actual para entradas multimodales
`user`	`String`	No	Identificador opaco del llamador expuesto en Seguimiento de usuarios
`metadata`	`Hash`	No	Metadatos planos definidos por el llamador para auditoría y filtrado de registros. Consulta Metadatos de invocación

El SDK inyecta streaming: false para invoke_agent. Para hacer streaming, usa invoke_agent_stream (abajo).

Manejo de la respuesta

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

Usa invoke_agent_stream para recibir Server-Sent Events a medida que llegan. El método entrega cada hash de evento analizado al bloque:

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

El stream genera los mismos tipos de eventos documentados en Invocar Agente → Respuesta: summary (cuando se dispara el resumen automático), reasoning, response, tool, un evento final usage, o un evento error si el proveedor falla a mitad del stream. Si omites el bloque, el método devuelve un Enumerator que puedes pasar por ahí:

enum = client.invoke_agent_stream(agent: "AGENT_UUID", message: "Hello")
enum.each { |chunk| handle(chunk) }

Conversaciones de múltiples turnos

Hilos persistentes

Pasa cualquier cadena como thread_id y Fetch Hive creará el hilo en la primera llamada y lo reanudará en llamadas posteriores con el mismo valor:

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"
)

Historial sin estado

Administra el estado tú mismo pasando los turnos previos en messages. Fetch Hive usa el historial proporcionado como contexto pero no lo persiste:

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." }
  ]
)

Entradas multimodales

Adjunta imágenes al mensaje actual con image_urls:

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

Las URLs deben comenzar con https://.

Configuración

Opción	Valor predeterminado	Descripción
`api_key`	`ENV["FETCH_HIVE_API_KEY"]`	Token Bearer del panel
`base_url`	`https://api.fetchhive.com/v1`	Sobrescribe la URL base de la API
`timeout`	`120`	Tiempo de espera de la solicitud en segundos

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

Errores

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

begin
  reply = client.invoke_agent(agent: "AGENT_UUID", message: "Hello")
rescue => e
  warn "Fetch Hive error: #{e.message}"
end

Consulta Errores y límites de tasa para conocer el significado de los códigos de estado.

Enlaces

Próximos pasos

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
Invocar Agente - Referencia completa del endpoint

​Ejecutar con el SDK de Ruby

​Instalación

​Autenticación

​Ejemplo básico

​Referencia del método

​Manejo de la respuesta

​Streaming

​Conversaciones de múltiples turnos

​Hilos persistentes

​Historial sin estado

​Entradas multimodales

​Configuración

​Errores

​Enlaces

​Próximos pasos