# Agent integrations

URL: https://theelena.me/docs/avileo/tiendas/agent-integration
Text: https://theelena.me/docs/avileo/tiendas/agent-integration.txt
Description: Connect a trusted server-side agent with read or mutate access.
Context: environment=production; apiBaseUrl=https://tienda.theelena.me; activation=active; rubro=tiendas

# Agent integrations

Avileo has two credential boundaries:

| Credential                 | Use                                         | Storage                         |
| -------------------------- | ------------------------------------------- | ------------------------------- |
| `avileo_pk_...` Client Key | Public catalog, storefronts and public SDK  | Browser or public environment   |
| `avileo_sk_...` Agent Key  | Private business and catalog administration | Server-side secret manager only |

The public Client Key keeps the existing storefront contract. The Agent Key is
bound to one business and has two modes:

- **read**: business, profile, catalog, assets and inventory inspection;
- **mutate**: reads plus proposals for administrative changes.

Availability comes from the effective `agentCatalogAccessEnabled` business-mode
capability, including tenant overrides. It is not hardcoded to a rubro slug.

## Human approval

A mutate-mode key still cannot change data immediately:

1. The agent submits an allowlisted operation and exact payload.
2. Avileo generates the summary and diff and returns an approval URL.
3. An authorized staff user reviews and approves or rejects it.
4. The agent applies the same payload with that approval ID.
5. Avileo records the terminal result and prevents reuse for another payload.

Reads and import previews do not require approval. Product, variant, taxonomy,
asset, inventory and import-apply mutations do.

## Creating a web credential

A mutate-mode agent may propose creating a public Client Key. After staff
approval, the one-shot apply response returns `avileo_pk_...`; a coding agent
can place it in the web project's `.env` and use the public SDK. The secret
`avileo_sk_...` must never enter that project or a browser bundle.

## Manage the existing Agent Key

From Avileo settings, open the current Agent Key and switch it between **Solo
lectura** and **Lectura y mutación**. This updates the same credential; it does
not rotate or reveal its secret. Existing write-enabled keys appear as mutate.

See [Agent HTTP API](/docs/avileo/tiendas/agent-http), [Agent SDK](/docs/avileo/tiendas/agent-sdk), and
[Agent CLI](/docs/avileo/tiendas/agent-cli) for concrete usage.