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

# Bridge Options Reference

> Options for callToolViaGateway and callToolViaGatewayWithAgent bridge functions.

The bridge functions (`callToolViaGateway` and `callToolViaGatewayWithAgent`, exported from `sec0-sdk/middleware`) are the client-side interface for routing tool calls through the gateway. They construct the HTTP request with all required headers (auth, trace context, agent state, idempotency key, and AP2 mandates) then forward to the gateway's `POST /mcp/:server/:toolAtVersion` endpoint. The gateway validates, enforces policy, and proxies to the upstream tool server, preserving full custody chain continuity.

## callToolViaGateway (BridgeCallOptions)

| Key                      | Type      | Required | Description                       |
| ------------------------ | --------- | -------- | --------------------------------- |
| `gatewayBaseUrl`         | string    | Yes      | Gateway base URL                  |
| `server`                 | string    | Yes      | Tool server name                  |
| `toolAtVersion`          | string    | Yes      | Tool name\@version                |
| `args`                   | any       | No       | Tool arguments                    |
| `authHeader`             | string    | No       | Authorization header (Bearer)     |
| `tenant`                 | string    | No       | Tenant override                   |
| `traceparent`            | string    | No       | W3C traceparent header            |
| `baggage`                | string    | No       | W3C baggage header                |
| `runId`                  | string    | No       | Graph run identifier              |
| `nodeId`                 | string    | No       | Graph node identifier             |
| `idempotencySalt`        | string    | No       | Extra entropy for idempotency key |
| `timeoutMs`              | number    | No       | Request timeout (ms)              |
| `ap2.intent`             | string    | No       | AP2 intent mandate header         |
| `ap2.cart`               | string    | No       | AP2 cart mandate header           |
| `ap2.bundle`             | string    | No       | AP2 bundle header                 |
| `cause.traceId`          | string    | Yes      | Parent trace ID                   |
| `cause.spanId`           | string    | Yes      | Parent span ID                    |
| `identity.authorization` | string    | No       | Downstream auth context           |
| `identity.tenant`        | string    | No       | Tenant claim                      |
| `identity.roles`         | string\[] | No       | Roles claim                       |
| `identity.userId`        | string    | No       | User ID                           |
| `identity.userHash`      | string    | No       | User hash                         |
| `identity.assertion`     | string    | No       | Extra assertion                   |
| `agentState`             | object    | No       | Agent state payload               |

### agentState (AgentStatePayload)

| Key         | Type   | Required | Description              |
| ----------- | ------ | -------- | ------------------------ |
| `nodeId`    | string | Yes      | Node identifier          |
| `runId`     | string | No       | Run identifier           |
| `parentRef` | string | No       | Parent reference         |
| `variables` | object | No       | Agent variables by scope |
| `metadata`  | object | No       | Arbitrary metadata       |

## callToolViaGatewayWithAgent (AgentBridgeCallOptions)

`AgentBridgeCallOptions` is `BridgeCallOptions` plus an `agent` block (and without `agentState`).

### agent

| Key               | Type   | Required | Description           |
| ----------------- | ------ | -------- | --------------------- |
| `agent.nodeId`    | string | Yes      | Agent node ID         |
| `agent.runId`     | string | Yes      | Agent run ID          |
| `agent.variables` | object | No       | Agent state variables |
| `agent.metadata`  | object | No       | Agent state metadata  |

## buildIdempotencyKey

```typescript theme={null}
buildIdempotencyKey({
  runId?: string;
  nodeId?: string;
  toolAtVersion: string;
  args?: any;
  salt?: string;
}): string
```

Returns a composite key built from `runId`, `nodeId`, `toolAtVersion`, and a short digest of `args`. For deterministic keys, pass stable `runId` and `nodeId` values; if `runId` is omitted, the helper generates one.