- 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:
- Create one session per end user (
POST /sessions) with a stableactor.actorId. - Reuse that session for all follow-up messages (
POST /events). - 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_URLBREK_PARTNER_API_KEYactorId(stable partner-side end-user ID)workspaceIdor tenant context if your product uses workspacespartnerId(stable partner tenant ID for idempotency and billing grouping)clientActionIdfor 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:
- Enforce local budget limits from
references/call-control.md. - Attach a deterministic
idempotencyKeyfor all write-like event kinds. - Respect
429withretry-afterand exponential backoff. - Open a circuit breaker after repeated 5xx or timeout failures.
- Log
x-request-id,x-partner-id,x-ratelimit-limit, andx-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_idaction_book_optionaction_confirm_price_changeaction_confirm_payment_cardaction_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:
- End-user card setup and confirmation in secure portal flow.
- 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
paymentMethodIdfrom provider-hosted fields. - Require explicit user confirmation before
action_confirm_payment_cardand booking actions.
Response mapping
Map Brek response as:
data.result.status-> state machine key for UI and orchestrationdata.result.message.text-> user-visible assistant textdata.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 byretry-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