Start with the first check that fails in the integration flow. Check authentication and the signed assertion, current public policy, session state, workspace readiness where required, and the specific input or stream event. Before retrying, find out whether the request failed, is waiting for a person, or already completed.
The diagram highlights the browser, server, agent, session, result, and error path; use those boundaries to locate a symptom before changing the integration.
Locate the first failing boundary
Scroll horizontally to see all columns.
| Boundary and symptom | Evidence to inspect | Safe next step |
|---|---|---|
| Authentication — no session | Confirm the app user reaches the assertion endpoint and the callback returns a signed assertion string. | Fix app authentication or server-side assertion generation; keep the signing credential on the server. |
| Policy — missing or denied control | Check current capability flags, relevant policy fields, and any returned negotiated settings. | Hide unavailable controls; a stable unsupported_capability denial is not empty data. |
| Session — missing or stale state | Check session methods and public sessionRef metadata; inspect the app's active conversationRef separately. | Verify each ref at its own boundary; follow the session lifecycle to refresh or revoke. Never log the bearer token. |
| Workspace — durable action blocked | Check that the task needs a workspace, the granted capabilities, and runtime status. | The current guide lists no workspace need for chat, streaming, or turn artifacts; for workspace tasks, wait during provisioning and treat failed: true as terminal. |
| Input — host or file rejected | Check accepted host fields and byte limit; for files, check policy, type, size, and status. | Send permitted flat fields; wait until a file is available before attaching its supported fileRef. |
| Stream — turn incomplete | Check completion, the retryable field on an error event, pending interaction or approval, and interruption. | Keep pending states open; retry only when the error and operation make repetition safe, and reconcile an unknown outcome first. |
These checks come from the current integration guides. The order narrows the search; it does not guarantee that every symptom has one cause. Capture the public method, relevant policy fields, event type, and runtime flags without logging bearer tokens, assertions, private inputs, or raw internal identifiers.
Check the input contract, not just compilation
The getting-started guide documents hostContext as a flat map of primitive values. It also gives a specific example where a nested object type-checks against the SDK declarations but the server rejects it because the value is not public. This is a useful reminder that the TypeScript declaration and the request’s runtime contract answer different questions. Read the current hostContextPolicy.acceptedFields and maxTotalBytes, and send only the allowed primitive fields.
Documented diagnostic record (not a live reproduction)
Call input:hostContextcontainscustomer: { type: 'returning', value: true }.
Compile check: The current declaration accepts a JSON object shape.
Guide behavior: The getting-started documentation says nested{ type, value }data is rejected with400 host_context_field_not_public.
Diagnosis: Type acceptance did not validate the runtime field shape.
Next check: Compare flat primitive keys with the effective policy’s accepted fields and byte limit.
This record summarizes the local SDK declarations and guide; it is not a claim that this article independently exercised a live runtime. If a production request behaves differently, preserve a minimal sanitized reproduction and have the SDK owner verify the current implementation before documenting a fix.
Distinguish a denial from a retryable failure
The documentation describes disabled capabilities as a stable denial rather than an empty response. A mismatch between requested and granted policy is therefore a configuration or feature-availability issue, not a reason to retry blindly. Retry only when the public error marks the failure retryable and the specific operation is documented as safe to repeat; for a pending action or interrupted stream with an unknown outcome, stop and reconcile its state first. Likewise, failed: true on a workspace runtime is terminal; a polling timeout or cancelled wait has a different meaning. A stream may also be waiting on an approval or interaction rather than being broken.
Record the failing step, policy fields, public refs, runtime booleans, and normalized event/error category. Do not capture session tokens or assertion strings. For the session, conversation, and stream lifecycle, see agent sessions, conversations, and artifacts; for policy details, see external agent policy and capabilities, and for the trust boundary read public references and secure bootstrap.