Skip to main content
Hexagon exposes two distinct paths: named HTTP Tools discovered/called by a Harness, and protected HTTP connections called by Sandbox code through delegated access. Select by invocation model; their approval and call-record semantics are different.

Define fixed read/write operations

Prepare a controlled test service: a Bearer-authenticated verification path, a read endpoint returning a known report, and a write endpoint storing reference/text that can be independently looked up by reference. Return JSON. Save this template as http-tool.json, replace the base_url placeholder and implement the endpoints first. These are not built-in Hexagon services.
Operations fix path and GET/POST. GET puts arguments into query parameters, preserving strings and JSON-encoding other values. POST sends JSON arguments. Agent input cannot select arbitrary URLs, headers, methods, or path templates. input_schema must be a supported synchronous object JSON Schema; reject additional fields where appropriate. Paths exclude query, fragment, backslash, leading double slash, and .. segments. The adapter injects Bearer authorization and a stable call idempotency-key. Custom authentication-header mapping is not exposed here. Receiving that header does not prove upstream deduplication, so this example uses replay=never. Consider idempotency_key only after verifying real upstream deduplication. GET alone does not establish absence of side effects.

Review the mapping and replay contract

For read_report, arguments {"id":"report-1"} become a query parameter on the fixed /reports/read path. A numeric or object argument is JSON-encoded as a query value, not expanded into path segments. For save_report, {"reference":"request-1","text":"Reviewed"} becomes the JSON body. No mapping step interpolates arbitrary arguments into the upstream host or authentication header. In the current broker, an uncertain dispatched GET can be retried even when its operation says replay: never. The broker treats GET as replayable independently of the non-GET policy. Therefore only expose genuinely repeat-safe reads through GET; do not map a state-changing endpoint to GET and expect replay: never to prevent repetition. For POST, idempotency_key is appropriate only when the upstream actually honors the stable call key and preserves the same result across retries. Keep never for writes without that contract. Connection verification may return sanitized account/scope display metadata from a small JSON response. Missing metadata remains unknown; the displayed scope does not replace the selected operation policy or approve a write. A successful verification endpoint also does not prove permission to every operation path.

Create, validate, enable, and bind

These local management examples read private credentials; see self-hosting for hosted initialization. Retain/reuse the returned ID.
Validation requests the fixed verify_path, which must not mutate data. Success does not prove every business operation. Follow Tool binding, placing the ID in tools: {reports: connection_id} with a Tools-capable Harness, then preflight/create the Session. Required Tools need authorization during initialization. optional_tools does not bypass authorization or approval. First call read_report and verify actual content. Then request save_report and inspect reference/text before approving. approval=true controls invocation approval independently of existing connection credentials. Confirm rejection causes zero upstream writes, then test one authorized write to a dedicated record. See approvals.

Responses and unknown outcomes

Requests time out after 20 seconds and reject redirects. 401/403 take the authentication-error path. Results must parse as JSON; response text exceeding 1048576 JavaScript code units fails. That check is not a byte-level download-limit guarantee. A remote write can succeed before its response is lost or fails parsing. A task error does not establish no side effect. Call records retain request hash and dispatched policy. Reconcile unknown outcomes instead of generating a new reference and repeating the business action. Inspect tool_calls / toolCalls, verify the original reference remotely, then use resolve_tool_call / resolveToolCall with completed/failed and evidence. Resolution does not send another remote request. Leave genuinely unknown outcomes waiting or cancel; do not invent success. Later connection edits cannot change the original call’s replay qualification. See reconciliation.

Test a write by its business reference

Use a dedicated report reference such as hexagon-acceptance-001. The reference identifies the business record; the Tool call ID identifies one platform invocation. Preserve both. The following is an acceptance procedure for your controlled service, not an execution result from this documentation update. If the service cannot query the reference or distinguish duplicate writes, it cannot support this reconciliation proof yet. Do not infer “not written” from a failed request, and do not reuse this procedure on production data. GET operations have the separate repeat-safe requirement described above. A direct protected HTTP binding bypasses ToolBroker approval, so it cannot substitute for the approved-write test.

Direct guest HTTP access

Use kind=http/provider=http with endpoint, authentication, and access.rules, for example:
This path supports bearer or a named header injected by the trusted backend. Upstreams must be public HTTPS; rules match exact paths/methods. Bind via connections; guest code reads base_url and delegated headers from HEXAGON_CONNECTIONS. Generic HTTP validation checks structure/header safety, not remote authentication. This channel has no automatic ToolBroker approval or per-Tool reconciliation state. Use Agent Tools when a write requires that approval flow. Original keys do not enter new Harness invocations. Delegated tokens still convey authority: never log them or include them in model context/artifacts. Delegation does not grant the entire upstream API. See credential boundaries and the Secret contract. This page was reviewed against both adapters and execution contracts without fresh test-service execution. Acceptance must independently prove read content, zero preapproval writes, one approved write, no duplicate after lost response, absence of raw keys in guests, both SDKs, and cleanup. Examples are not evidence those checks passed. Sources: HTTP Tool, protected HTTP policy, Tool reconciliation. Next: approvals, reconciliation, credential boundaries.