brek-ai-skill

与 Brek Partner Core Chat API 集成，实现酒店搜索和预订助理流程。当客服人员需要创建或继续 Brek 聊天会话、安全发送用户事件、实施反滥用呼叫控制以及运行付款设置或付款确认而不收集原始卡数据时使用。

## 概述（中文）

与 Brek Partner Core Chat API 集成，实现酒店搜索和预订助理流程。当客服人员需要创建或继续 Brek 聊天会话、安全发送用户事件、实施反滥用呼叫控制以及运行付款设置或付款确认而不收集原始卡数据时使用。

## 原文

# Brek AI Partner Core Chat

Execute Brek through `/api/partner/v1/core-chat`.

Use this execution order:
1. Create one session per end user (`POST /sessions`) with a stable `actor.actorId`.
2. Reuse that session for all follow-up messages (`POST /events`).
3. Read the latest state when needed (`GET /sessions/{sessionId}`).

Do not share one session across different users.

## Required runtime inputs

Require these inputs before calling Brek:
- `BREK_BASE_URL`
- `BREK_PARTNER_API_KEY`
- `actorId` (stable partner-side end-user ID)
- `workspaceId` or tenant context if your product uses workspaces
- `partnerId` (stable partner tenant ID for idempotency and billing grouping)
- `clientActionId` for each write-like event kind

If one required input is missing, stop and request it.

If `BREK_PARTNER_API_KEY` is missing:
- stop outbound calls
- ask the user to get the key from their internal owner or approved support channel
- never request secrets through unapproved channels

## Call safety guardrails

Apply these guardrails before every upstream call:
1. Enforce local budget limits from `references/call-control.md`.
2. Attach a deterministic `idempotencyKey` for all write-like event kinds.
3. Respect `429` with `retry-after` and exponential backoff.
4. Open a circuit breaker after repeated 5xx or timeout failures.
5. Log `x-request-id`, `x-partner-id`, `x-ratelimit-limit`, and `x-ratelimit-remaining`.

Never retry booking or payment-confirm actions without the same `idempotencyKey`.

## Event-kind rules

When `kind` is one of:
- `command_book_by_option_id`
- `action_book_option`
- `action_confirm_price_change`
- `action_confirm_payment_card`
- `action_cancel_booking`

Always include `idempotencyKey`.

Generate `idempotencyKey` as:
- `<partnerId>:<sessionId>:<kind>:<clientActionId>`

If `partnerId` is unavailable in your runtime, use stable tenant context (for example `workspaceId`) and keep the key format deterministic.

## Payment handling

Handle payment in two layers:
1. End-user card setup and confirmation in secure portal flow.
2. Agent-to-agent usage billing and settlement.

Follow `references/payment-and-billing.md` for both layers.

Hard rules:
- Never request or store raw card number, CVV, or full PAN in chat.
- Accept only tokenized `paymentMethodId` from provider-hosted fields.
- Require explicit user confirmation before `action_confirm_payment_card` and booking actions.

## Response mapping

Map Brek response as:
- `data.result.status` -> state machine key for UI and orchestration
- `data.result.message.text` -> user-visible assistant text
- `data.result.artifacts` -> structured payload (shortlist, payment setup URL, booking metadata)

## Error handling

- `400`: request validation failed. Fix payload.
- `401/403`: API key issue. Stop calls. Tell user to rotate or provision key through their internal owner or approved support channel.
- `404`: session not found or wrong tenant.
- `409`: actor/session mismatch. Recreate correct session.
- `429`: throttle locally and retry by `retry-after`.
- `5xx`: retry with backoff, then open breaker.

## References

Read only what you need:
- API payload templates: `references/api-templates.md`
- Call-control and anti-abuse policy: `references/call-control.md`
- Payment and billing orchestration: `references/payment-and-billing.md`