# Set up Hexagon with an AI agent

Give an agent scoped access to product readiness and configuration while keeping provider and payment approvals with the owner.

[Developer setup](https://joinhexagon.com/start/developer) lets you create a scoped Hexagon key for an agent helping configure an existing product. The public contract currently lists personal Milo and workspace WhatsApp Sales. Ordinary visual setup remains available at [Start](https://joinhexagon.com/start).

This interface reads product and billing status, prepares supported setup changes and returns hosted owner actions. It is not a general model API or an unrestricted connection to your business data.

## Choose the correct identity

A Milo key is personal and tied to the person's Milo account. A Sales key is scoped to one selected workspace and product. Issuing a workspace key requires the appropriate owner or administrator authority.

Create the key through developer setup or [Agent access](https://joinhexagon.com/start/agent-access). Store the `hx_agent_` value in a secure environment variable such as `HEXAGON_API_KEY`; do not paste it into chat or place it in a URL, frontend code or logs. The full key is shown once. A merchant `hx_live_` key is a different credential and cannot replace it.

If a key is exposed or no longer needed, revoke it in Agent access. Workspace keys belong to the workspace: leaving as the original creator is not a substitute for revocation. Current authority is checked on requests, and a workspace key can act through the current owner when its creator is no longer an owner or administrator.

## Grant only the required scopes

| Scope | Authority |
| --- | --- |
| `products:read` | Read the selected product's status, setup version and next owner actions. |
| `billing:read` | Read the selected product's billing readiness and applicable agreement. |
| `checkout:create` | Prepare an eligible unpaid hosted checkout or management link for the customer. |
| `setup:write` | Read and save supported Sales drafts and reviewed instructions; prepare its inactive configuration. |
| `products:activate` | Activate, pause or retry ready Sales work under the workspace's accepted agreement. |

A checkout scope does not authorize payment. Activation can start real, billable automation under already accepted terms and therefore needs an explicit instruction matching the intended action.

## Use the current public contract

Read the [product catalog](https://api.joinhexagon.com/api/v1/agent-commerce/catalog), [OpenAPI reference](https://api.joinhexagon.com/api/v1/agent-commerce/openapi.json) and [published agent setup guide](https://joinhexagon.com/skills/hexagon-setup/SKILL.md). Authenticate with a bearer key only to the documented API base:

```text
https://api.joinhexagon.com/api/v1/agent-commerce
```

Use `milo` or `sales_v3` exactly as the product identifier. Start with `GET /products/{product}` and, if authorized, `GET /billing/{product}`. Follow returned owner links for missing account linking, provider authorization, business verification or billing consent.

For Sales, read the supported setup state, preserve the current `version` as `expectedVersion`, and submit only fields the OpenAPI permits. Save reviewed instructions only after the customer has reviewed them. Prepare verifies prerequisites without activating the assistant. Activate only when the current requirements are ready and the customer has authorized that outcome.

Shopify and Meta authorization, dedicated iMessage connection consent, business verification submission and new billing acceptance remain in the human setup flow. Never request provider secrets or raw payment card details in chat.

## Handle retries without duplicating actions

On a version conflict, read the current state and reconcile the intended change. Retry activation uses the saved version; it does not create a different intent. `operationPending: true` means the result is unconfirmed. A pending pause is not a confirmed stop.

For an eligible checkout request, preserve its UUID `requestKey` and selection on retry. Inspect the returned result: a management link is not a purchase, a hosted checkout still needs the customer, and a completed-payment receipt should not lead to a second payment request. Respect any `Retry-After` response.

## Keep product billing separate

For Milo, resolve an existing account link and subscription first. If the company already covers the person, do not offer a duplicate plan. Use the returned management or hosted subscription destination and its current terms.

Sales outcome enrollment uses the exact owner link returned by billing. Existing prepaid agreements have separate credit and automatic-reload terms. Do not buy credits as a prerequisite for an outcome agreement or treat an old balance as proof that a new agreement is active.

## Related guides

- [WhatsApp Sales](https://joinhexagon.com/docs/whatsapp-sales.md)
- [Set up and activate Sales](https://joinhexagon.com/docs/sales-setup.md)
- [Manage your subscription](https://joinhexagon.com/docs/billing.md)
- [Permissions and approvals](https://joinhexagon.com/docs/permissions-and-approvals.md)

## References

- [Developer setup](https://joinhexagon.com/start/developer)
- [Hexagon product catalog](https://api.joinhexagon.com/api/v1/agent-commerce/catalog)
- [Agent setup API reference](https://api.joinhexagon.com/api/v1/agent-commerce/openapi.json)
- [Hexagon setup guide for agents](https://joinhexagon.com/skills/hexagon-setup/SKILL.md)

Last updated: 2026-10-31
Canonical: https://joinhexagon.com/docs/agent-assisted-setup
Markdown: https://joinhexagon.com/docs/agent-assisted-setup.md