> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fetchhive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Metadatos de invocación

> Pasa metadatos definidos por el llamador a los endpoints públicos de invocación y úsalos para inspeccionar y filtrar registros

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

```json theme={null}
{
  "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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```typescript theme={null}
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`:

```typescript theme={null}
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

```python theme={null}
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`:

```python theme={null}
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

```ruby theme={null}
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 theme={null}
<?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

* [Invoke Prompt](../api-reference/prompts/invoke)
* [Invoke Workflow](../api-reference/workflows/invoke)
* [Invoke Agent](../api-reference/agents/invoke)
* [Registros de prompts](../prompts/logs)
* [Registros de workflows](../workflows/logs)
* [Registros de agentes](../agents/logs)