Skip to main content
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

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, Python SDK and HTTP implementation. 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. Begin at the HTTP reference index 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; this integration guide does not replace them. Continue with combination selection, the HTTP index or reconciliation.

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.
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

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 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 to identify unfinished content, never to infer runtime capability. Next: first Session, backend integration, reconciliation.