> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hexagon.autos/llms.txt
> Use this file to discover all available pages before exploring further.

# Integration reading guide for coding Agents

Use this guide when building an application on Hexagon. It is product integration documentation, not repository AGENTS.md instructions. Repository instructions still govern edits, tests, credentials and publication in your checkout. This Markdown file is the reading entry point; it does not imply an available hosted documentation endpoint or a separate machine API.

## Read in execution order

| Step | Read and establish | Persist or verify |
| - | - | - |
| 1. Version and deployment | [Installation](https://docs.hexagon.autos/en/start/install.md), [SDK source guide](https://github.com/NexusFox88/docs/blob/main/resources/sdk/README.md), [CLI](https://docs.hexagon.autos/en/reference/cli.md) | Actual control-plane source/build, installed SDK artifact/version, local versus hosted authentication |
| 2. Capability discovery | [Choose integrations](https://docs.hexagon.autos/en/integrations/choose.md), [Harnesses](https://docs.hexagon.autos/en/integrations/harnesses.md), [verified combinations](https://docs.hexagon.autos/en/integrations/verified-combinations.md) | Exact Harness id/version/digest, model protocol, Sandbox capabilities and dated scenario evidence |
| 3. Configuration/preflight | [Connection lifecycle](https://docs.hexagon.autos/en/build/connection-lifecycle.md), [Sandbox policy](https://docs.hexagon.autos/en/build/sandbox-policy.md), [initialization](https://docs.hexagon.autos/en/concepts/initialization.md) | Ready enabled connections, ownership, requested policies and immutable Session inputs |
| 4. Session | [First Session](https://docs.hexagon.autos/en/start/first-session.md), [backend integration](https://docs.hexagon.autos/en/build/backend-integration.md) | Business ownership, creation intent, returned Session ID; saved Agent is optional |
| 5. Run | [Backend integration](https://docs.hexagon.autos/en/build/backend-integration.md), [project context](https://docs.hexagon.autos/en/build/project-context.md) | Exact input/origin, stable idempotency key and returned Run ID |
| 6. Durable observation | [Event streaming](https://docs.hexagon.autos/en/build/stream-events.md) | Event plus cursor in one application transaction; deduplicate by Run/event ID |
| 7. Authorization/approval | [Tool authorization](https://docs.hexagon.autos/en/build/tool-authorization.md), [approvals](https://docs.hexagon.autos/en/build/approvals.md) | Original call and pending decision; account access and side-effect approval are separate |
| 8. Result | [Artifacts](https://docs.hexagon.autos/en/build/artifacts.md), [private preview](https://docs.hexagon.autos/en/build/private-preview.md) | Terminal query, actual output/file content, authenticated preview where supported |
| 9. Recovery and cleanup | [Recovery](https://docs.hexagon.autos/en/build/recovery.md), [reconciliation](https://docs.hexagon.autos/en/operate/reconciliation.md) | Original operation/resource IDs, externally checked outcomes and confirmed Session closure |

Do not assume an SDK package version certifies every server build. Check the running catalog and the installed SDK's actual signatures. For exact requests while the dedicated references are still being completed, use the checked-in [TypeScript SDK](https://github.com/NexusFox88/docs/blob/main/resources/sdk/typescript/index.ts), [Python SDK](https://github.com/NexusFox88/docs/blob/main/resources/sdk/python/hexagon/__init__.py) and [HTTP implementation](https://github.com/NexusFox88/docs/blob/main/resources/apps/control-plane/server.ts). These are source references, not promises of an OpenAPI endpoint.

## Select the contract before constructing a call

Use the exact resource reference for parameters, authorization, response shape and side effects. The guides explain how to assemble those calls into an application; they are not a substitute for the contract.

| Intended action | Contract to read | Decision to preserve |
| - | - | - |
| Configure/validate execution prerequisites | [Connections](https://docs.hexagon.autos/en/reference/connections.md), [Harness registration](https://docs.hexagon.autos/en/reference/harness-registration.md) | Connection readiness, selected version and actual capability support |
| Preflight, create, upload or close | [Sessions](https://docs.hexagon.autos/en/reference/sessions.md) | Creation intent, pinned definition and cleanup outcome |
| Submit, query or cancel a task | [Runs](https://docs.hexagon.autos/en/reference/runs.md) | Same input/origin/key for retries; cancellation is explicit |
| Observe progress | [Events and states](https://docs.hexagon.autos/en/reference/events-and-states.md) | Public event cursor differs from Runtime cursor; unknown events cannot invent state transitions |
| Decide a Tool action | [Approvals and Tool calls](https://docs.hexagon.autos/en/reference/approvals-tools.md) | Account authorization, operation approval and outcome reconciliation remain distinct |
| Deliver files or previews | [Artifacts and previews](https://docs.hexagon.autos/en/reference/artifacts-previews.md) | Artifact integrity and preview authorization have separate lifecycles |
| Investigate resource uncertainty | [Resource operations](https://docs.hexagon.autos/en/reference/resource-operations.md) | Original operation/resource identity and review state; acknowledgement is not completion |
| Translate calls to SDK code | [Python](https://docs.hexagon.autos/en/reference/python.md), [TypeScript](https://docs.hexagon.autos/en/reference/typescript.md), [errors](https://docs.hexagon.autos/en/reference/errors.md) | Actual method signatures, error handling and language-specific byte/cursor types |

Begin at the [HTTP reference index](https://docs.hexagon.autos/en/reference/http.md) when you cannot identify the resource. These are version-sensitive repository references; verify them against the checked-out source when changing contracts. Do not derive an endpoint by guessing from an SDK method name.

## Journal facts must survive a process restart

Treat the following as application data requirements, not a new Hexagon JSON schema:

* The original submission contains Session ID, exact input, exact origin and the stable idempotency key. Keep it before the network call so a lost response can be recovered.
* Run ID and a decimal-string event cursor identify accepted work and observation progress. Save each event and its advanced cursor atomically; an in-memory map does not survive a worker restart.
* Keep creation/closure intent separate from confirmed results. An operation ID, remote resource ID and unresolved outcome are evidence to reconcile, not instructions to repeat the mutation.
* Keep authorization material out of the ordinary journal. If a preview URL must be retained, use private storage with appropriate access controls; that URL can itself grant access.

For example, a journal holding Run R and committed event cursor `104` after a client crash means “observe R after 104,” not “resubmit the task.” A journal holding only a Session-creation intent means “investigate whether creation succeeded,” not “allocate another Session.” Different missing fields imply different recovery actions.

Repository development rules remain in [AGENTS.md](https://github.com/NexusFox88/docs/blob/main/resources/AGENTS.md); this integration guide does not replace them. Continue with [combination selection](https://docs.hexagon.autos/en/integrations/choose.md), the [HTTP index](https://docs.hexagon.autos/en/reference/http.md) or [reconciliation](https://docs.hexagon.autos/en/operate/reconciliation.md).

## Integration algorithm with a durable journal

The following is pseudocode. `journal`, business authorization and transactions are application-owned, not Hexagon SDK methods. The concrete Python and TypeScript calls are in the linked build guides and [first-Session examples](https://github.com/NexusFox88/docs/blob/main/resources/examples/documentation/first-session.py).

```text theme={null}
authorize business user against the work context
load/create a private journal for this business request
record selected connections, exact Harness version, policy and creation intent

if Session ID is absent:
    if a previous create request has an unknown outcome:
        investigate Sessions and resource operations; stop automatic creation
    create Session once; persist returned Session ID

commit submission intent:
    Session ID, exact input, exact origin, one stable idempotency key
submit that saved intent; persist returned Run ID
if submission response is lost:
    retry the same Session/input/origin/key with bounded transport backoff
    never generate a new key to conceal a conflict

cursor = last committed event ID, or string "0"
observe original Run after cursor
for each event with an ID:
    transactionally deduplicate/store event and advance cursor
for stream loss:
    reconnect to the same Run with the committed cursor
for authorization/approval wait:
    surface the original request to the permitted decision-maker
for unknown Tool result:
    record call ID, request hash and dispatch policy
    investigate externally; do not re-dispatch the write

query the Run for its terminal state and final output
verify/download authorized artifacts; preserve intended follow-up context
when the Session is no longer needed:
    record close intent; request closure; verify confirmed cleanup
    retain pending operation/resource IDs until reconciliation finishes
```

Record at least business request/owner, Session ID, Run ID, exact submission payload/key, event cursor, cleanup intent/status and unresolved operation references. Resource identifiers belong in private evidence, not public example output. Store timestamps and errors without logging Tokens or original account credentials. Every external lookup and result delivery still requires application authorization, even when several business users share one Hexagon tenant.

Run submission idempotency does not extend to Session creation or arbitrary provider operations. Event IDs should remain numeric strings, not JavaScript Numbers. An event without a durable ID, such as `stream.end`, is not a cursor checkpoint. A drained stream or empty event page does not replace the terminal Run query. A network disconnect does not cancel execution.

## Conditions that change the next action

| Condition | Action |
| - | - |
| Unsupported model protocol/network/Tool capability | Correct selection before allocation; do not silently weaken the requested policy |
| `session_busy` | Keep the application message pending until the active Run settles, or use a deliberately separate Session |
| Idempotency conflict | Compare stored input/origin/key; do not manufacture a new request to hide the conflict |
| Authentication/permission error | Correct identity or authorization; do not loop transient retries |
| Missing Tool authorization | Obtain authorized account access through the existing flow; do not pass upstream keys to the guest |
| Pending write approval | Wait for a permitted decision; a model instruction is not approval |
| Unknown create/write/delete outcome | Reconcile the original operation; absence of a response is not proof of failure |
| Failed or cancelled Run | Inspect output, events and possible side effects before another task; cancellation does not undo writes |
| Unconfirmed cleanup | Retain the journal and provider identifiers; do not mark the account free of orphan resources |

## Use examples and evidence accurately

Examples have different scopes: a complete tutorial, an SDK excerpt requiring existing variables, a structural sketch, or a deterministic fixture. Read the label and prerequisites before executing. Placeholder connection IDs, `.invalid` domains and local image tags are not deployed services. A fixture model does not prove real model behavior; a registered Harness does not prove that image/provider/protocol combination works.

For each integration change, report the files changed, actual commands and outcomes, exact tested scope, limitations and cleanup status. Preserve failed attempts. Follow [testing and evidence](https://docs.hexagon.autos/en/contribute/testing.md) and both SDK journeys where the change affects their shared contract. Do not use generated Agent text as proof that tests passed: inspect actual test output and artifacts.

The linked product pages are checked-in documentation drafts. This page links existing files; it does not claim that a public documentation site, `llms.txt` service, or every planned reference page has been published. Use the [coverage ledger](https://github.com/NexusFox88/docs/blob/main/resources/docs/product/coverage.json) to identify unfinished content, never to infer runtime capability.

Next: [first Session](https://docs.hexagon.autos/en/start/first-session.md), [backend integration](https://docs.hexagon.autos/en/build/backend-integration.md), [reconciliation](https://docs.hexagon.autos/en/operate/reconciliation.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.