brek-ai-skill

name	brek-ai-skill
description	Integrate with Brek Partner Core Chat API for hotel-search and booking assistant flows. Use when an agent needs to create or continue Brek chat sessions, send user events safely, enforce anti-abuse call controls, and run payment setup or payment confirmation without collecting raw card data.
metadata	{"required_env_vars":"BREK_BASE_URL,BREK_PARTNER_API_KEY","primary_credential":"BREK_PARTNER_API_KEY","required_runtime_inputs":"actorId,workspaceId,partnerId,clientActionId","storage_requirements":"durable idempotency dedupe store,budget counter store,usage metering log","autonomous_invocation":"false","always_on_presence":"false","config_paths":"none"}

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