Saltar al contenido principal

​
Metadatos de invocación

Usa los metadatos de invocación cuando quieras adjuntar tus propios campos de auditoría a ejecuciones en vivo de prompts, workflows o agentes. Los metadatos se almacenan junto con la ejecución, se muestran en los detalles del registro y están disponibles como filtros de User metadata en los registros.

​
Descripción general

Fetch Hive acepta un objeto metadata en estos endpoints públicos de invocación:
  • POST /v1/prompt/invoke
  • POST /v1/workflow/invoke
  • POST /v1/agent/invoke
Usa los metadatos para campos de tu aplicación que te ayuden a investigar y segmentar el tráfico más tarde, como IDs de clientes, nombres de planes, regiones, nombres de experimentos, entornos, IDs de inquilinos o feature flags. Los metadatos no son la entrada del prompt, del workflow ni del agente. Las variables del prompt y las variables iniciales del workflow van en inputs. Los mensajes del agente van en message o messages.

​
Estructura de los metadatos

metadata debe ser un objeto plano. Las claves deben ser cadenas no vacías y los valores deben ser cadenas, números, booleanos o null. Los objetos anidados y los arrays se rechazan antes de que comience la ejecución. Buenos ejemplos de metadatos: 
{
  "customer_id": "cus_123",
  "plan": "enterprise",
  "region": "us-east-1",
  "experiment": "checkout_v2",
  "beta_user": true
}
Evita enviar datos sensibles, secretos, mensajes de usuario en bruto o cargas útiles grandes en los metadatos. Mantenlos pequeños y estables para que los filtros sigan siendo útiles.

​
Ejemplos de cURL

​
Invocación de prompt

curl 'https://api.fetchhive.com/v1/prompt/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "deployment": "support-classifier",
    "variant": "default",
    "inputs": {
      "ticket_text": "The export button is disabled."
    },
    "metadata": {
      "customer_id": "cus_1234",
      "plan": "enterprise",
      "experiment": "support_triage_v2"
    }
  }'

​
Invocación de workflow

curl 'https://api.fetchhive.com/v1/workflow/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "deployment": "research-brief",
    "variant": "default",
    "inputs": {
      "topic": "AI infrastructure trends"
    },
    "metadata": {
      "customer_id": "cus_123",
      "region": "us-east-1",
      "source": "daily_digest_job"
    }
  }'

​
Invocación de agente

curl 'https://api.fetchhive.com/v1/agent/invoke' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "agent": "AGENT_UUID",
    "message": "Summarize this account before renewal.",
    "metadata": {
      "customer_id": "cus_123",
      "plan": "enterprise",
      "renewal_window_days": 30
    }
  }'

​
Ejemplos de SDK

Los SDK oficiales aceptan el mismo objeto metadata en los helpers de invocación de prompts, workflows y agentes.

​
Node.js

import { FetchHive } from "@fetch-hive/sdk";

const client = new FetchHive({ apiKey: process.env.FETCH_HIVE_API_KEY });

const result = await client.invokePrompt({
  deployment: "support-classifier",
  variant: "default",
  inputs: { ticket_text: "The export button is disabled." },
  metadata: {
    customer_id: "cus_123",
    plan: "enterprise",
    experiment: "support_triage_v2",
  },
});

console.log(result.response);
Usa el mismo campo con invokeWorkflow e invokeAgent: 
await client.invokeWorkflow({
  deployment: "research-brief",
  variant: "default",
  inputs: { topic: "AI infrastructure trends" },
  metadata: { customer_id: "cus_123", source: "daily_digest_job" },
});

await client.invokeAgent({
  agent: "AGENT_UUID",
  message: "Summarize this account before renewal.",
  metadata: { customer_id: "cus_123", renewal_window_days: 30 },
});

​
Python

from fetch_hive_sdk import FetchHive

client = FetchHive()

result = client.invoke_prompt(
    deployment="support-classifier",
    variant="default",
    inputs={"ticket_text": "The export button is disabled."},
    metadata={
        "customer_id": "cus_123",
        "plan": "enterprise",
        "experiment": "support_triage_v2",
    },
)

print(result["response"])
Usa el mismo argumento con invoke_workflow e invoke_agent: 
client.invoke_workflow(
    deployment="research-brief",
    variant="default",
    inputs={"topic": "AI infrastructure trends"},
    metadata={"customer_id": "cus_123", "source": "daily_digest_job"},
)

client.invoke_agent(
    agent="AGENT_UUID",
    message="Summarize this account before renewal.",
    metadata={"customer_id": "cus_123", "renewal_window_days": 30},
)

​
Ruby

require "fetch_hive"

client = FetchHive::Client.new(api_key: ENV.fetch("FETCH_HIVE_API_KEY"))

result = client.invoke_prompt(
  deployment: "support-classifier",
  variant: "default",
  inputs: { ticket_text: "The export button is disabled." },
  metadata: {
    customer_id: "cus_123",
    plan: "enterprise",
    experiment: "support_triage_v2"
  }
)

puts result["response"]

​
PHP

<?php
require_once 'vendor/autoload.php';

use FetchHive\Sdk\FetchHive;

$client = new FetchHive(['api_key' => getenv('FETCH_HIVE_API_KEY')]);

$result = $client->invokePrompt([
    'deployment' => 'support-classifier',
    'variant'    => 'default',
    'inputs'     => ['ticket_text' => 'The export button is disabled.'],
    'metadata'   => [
        'customer_id' => 'cus_123',
        'plan'        => 'enterprise',
        'experiment'  => 'support_triage_v2',
    ],
]);

echo $result['response'];

​
Filtrado de registros por metadatos

Después de que las ejecuciones lleguen con metadatos, abre la página de registros correspondiente:
  • Ejecuciones de prompts: abre el prompt y selecciona Activity Logs
  • Ejecuciones de workflows: abre Workflows y selecciona Logs
  • Ejecuciones de agentes: abre Agents y selecciona Logs
Usa User metadata para filtrar por metadatos. Elige una clave de metadatos para encontrar ejecuciones donde exista esa clave. Agrega un valor cuando quieras una coincidencia escalar exacta, como customer_id = cus_123, plan = enterprise, beta_user = true o renewal_window_days = 30. Fetch Hive registra los nombres de propiedades de metadatos a lo largo del tiempo desde las solicitudes de invocación para que el filtro pueda sugerir las claves que tu espacio de trabajo realmente ha enviado. Las ejecuciones más antiguas sin esos metadatos permanecen visibles normalmente, pero quedan excluidas cuando hay un filtro de metadatos coincidente activo. Cuando abres una hoja de detalle de ejecución, los metadatos aparecen en la sección User metadata para que puedas confirmar qué campos definidos por el llamador se adjuntaron a esa ejecución.

​
Consulta también