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

# 调用元数据

> 将调用方定义的元数据传递给公开的 invoke 端点,并用于检查和筛选日志

# 调用元数据

当你想为实时的提示、工作流或智能体运行附加自己的审计字段时,请使用调用元数据。元数据与运行一同存储,在日志详情中显示,并可作为日志中的 **User metadata** 筛选条件使用。

## 概述

Fetch Hive 在以下公开 invoke 端点上接受 `metadata` 对象:

* `POST /v1/prompt/invoke`
* `POST /v1/workflow/invoke`
* `POST /v1/agent/invoke`

将元数据用于来自你应用的字段,帮助你之后调查和细分流量,例如客户 ID、套餐名称、区域、实验名称、环境、租户 ID 或功能开关。

元数据不是提示、工作流或智能体的输入。提示变量和工作流启动变量属于 `inputs`。智能体消息属于 `message` 或 `messages`。

## 元数据结构

`metadata` 必须是一个扁平对象。键必须是非空字符串,值必须是字符串、数字、布尔值或 `null`。

嵌套对象和数组会在运行开始之前被拒绝。

良好的元数据示例:

```json theme={null}
{
  "customer_id": "cus_123",
  "plan": "enterprise",
  "region": "us-east-1",
  "experiment": "checkout_v2",
  "beta_user": true
}
```

避免在元数据中发送敏感数据、密钥、原始用户消息或大型负载。保持其小巧且稳定,以便筛选器持续有用。

## cURL 示例

### Prompt invoke

```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"
    }
  }'
```

### Workflow invoke

```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"
    }
  }'
```

### Agent invoke

```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
    }
  }'
```

## SDK 示例

官方 SDK 在提示、工作流和智能体 invoke 辅助方法上接受相同的 `metadata` 对象。

### 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);
```

在 `invokeWorkflow` 和 `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"])
```

在 `invoke_workflow` 和 `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'];
```

## 按元数据筛选日志

在带有元数据的运行到达后,打开对应的日志页面:

* 提示运行:打开提示并选择 **Activity Logs**
* 工作流运行:打开 **Workflows** 并选择 **Logs**
* 智能体运行:打开 **Agents** 并选择 **Logs**

使用 **User metadata** 按元数据进行筛选。

选择一个元数据键以查找该键存在的运行。当你想要精确的标量匹配时,可添加一个值,例如 `customer_id = cus_123`、`plan = enterprise`、`beta_user = true` 或 `renewal_window_days = 30`。

Fetch Hive 会随时间从 invoke 请求中跟踪元数据属性名称,以便筛选器能够建议你的工作区实际发送过的键。没有该元数据的早期运行仍可正常查看,但在匹配的元数据筛选器处于激活状态时会被排除。

当你打开一个运行详情面板时,元数据会出现在 **User metadata** 部分,方便你确认哪些调用方定义的字段附加到了该次运行。

## 另请参阅

* [Invoke Prompt](../api-reference/prompts/invoke)
* [Invoke Workflow](../api-reference/workflows/invoke)
* [Invoke Agent](../api-reference/agents/invoke)
* [提示日志](../prompts/logs)
* [工作流日志](../workflows/logs)
* [智能体日志](../agents/logs)