Skip to main content
Cloud Adapter includes agents that help explain why an adapter request returned an unexpected result. Give the agent the request, native response, selected service mapping and relevant Explain evidence. Require a conclusion that names its sources, distinguishes observations from hypotheses and identifies the next check that could prove it wrong. Start with the included Support Agents for a bounded investigation into observed behavior. Use Operations with Agents for ownership, tool permissions, ongoing work and collaboration. Use Tuning Your Adapters when the question becomes whether a measured change improves a workload.

​
Keep the result, receipt and report together

The application receives its service’s native response. Explain adds a receipt when report capture is admitted; retrieve the report separately. These artifacts answer different questions: Preserve the original response before retrying. x-t9-explain: true means ExecuteAndExplain: the request executes. A preview requires the signed explicit version-1 control with mode Explain. A completed preview returns a native 409 ExplainedNotPerformed error and a receipt without performing the requested action. See Explaining SDK Requests for the supported controls. Use the dedicated synthetic AWS t9 report service with the receipt’s report ID and T9CloudAdapter.GetExplanation on the install’s published t9 endpoint. Retrieval uses the original report owner’s IAM credentials, SigV4 signing service t9 and the configured report region. A report ID, Tensor9 account API key or target-cloud credential is not a replacement for that identity. Decode the outer AWS JSON response first; its body string contains the rendering. Record the revision and lifecycle on every read. Poll the same report ID if collection continues. Export needed evidence before acknowledgment or the reported expiry deadline. Default retention is 24 hours from creation; the configured deadline is fixed, and reads do not renew it. Reading a report does not replay the request. Follow Diagnostic Response Headers for receipt, access and acknowledgment details.

​
Prepare one evidence bundle

Start with one question, such as “Why did this Query return no items?” Include enough context to distinguish a client-input problem, a selected mapping, an adapter decision and a target observation:
  • Product, adapter and SDK versions; customer environment and observation time.
  • Origin service, operation, selected target backend and relevant configuration revision.
  • Reviewed request and native response, including request identifiers and receipt headers.
  • Report ID, revision, mode, lifecycle, capture assurance and every relevant limitation.
  • Agent-format explanation or JSON, preserving event and fact IDs and their supporting references.
  • Independent state observations, their source and time, and the question each check answered.
Agent format presents compact evidence; it does not sanitize it, grant access or make payloads trustworthy. Review an exported copy before giving it to an agent or another recipient. Remove credentials, authorization headers, session tokens, signed URLs and unrelated application data. Preserve the original privately when needed, and label what the shared copy omits. If removing a value prevents a comparison, record that comparison as unavailable. Full PostgreSQL plans require particular care. The planning evidence preserves relation and index names, predicates and application literals in Human, Agent and JSON output. Format selection does not remove those values. See PostgreSQL Query Plans in Explain for the complete contract. Keep a small manifest alongside the files. This example is an investigation brief, not an executable configuration or a captured report:
Enforce access limits in the agent’s environment. A prompt describing a restriction does not implement that restriction. The operations guide separates tools, model processing and customer authority.

​
Worked example: an empty DynamoDB Query

Suppose an application expects an order but receives an empty Query result. The selected backend is PostgreSQL. The following is an illustrative evidence ledger, not production output or a byte-for-byte Agent rendering. In a real case, replace the source descriptions with the actual filenames and report fact IDs. The report properties above are real DynamoDB instrumentation. They describe the selected access path and request shape. They do not copy key values, filter operands or cursor values into these facts. The source dynamodb.access-planner observes the plan chosen inside the adapter; it does not observe the contents of the table. An evidence-linked answer should therefore say:
This avoids a tempting shortcut: a filter’s presence does not prove that it removed the expected item. Nor should the agent apply an AWS pagination explanation without checking the selected mapping. The PostgreSQL adapter pushes supported filters into SQL and has documented differences in result-window and ScannedCount behavior. Consult the DynamoDB mapping before interpreting those fields. If the original request used an unintended cursor, that comparison supplies evidence for a client-input explanation. If it matches the intended request, keep the alternative hypotheses open and choose an authorized read that can distinguish them. Record a new read as a new observation with its own request identity and time. It does not recreate the original transaction snapshot.

​
Ask the agent to show its reasoning from evidence

Use a task prompt like this after reviewing the bundle:
The agent should preserve missing and unsupported evidence. An absent fact does not prove an operation was unsupported or did not run. Capture order is not a global clock. A provider acceptance is not necessarily final convergence. Reading an Explanation explains these distinctions.

​
When the investigation includes a PostgreSQL plan

The query-plan integration adds another observation, rather than a substitute for the native result. Its illustrative fact-postgres-lookup contains an Index Scan, a named index, an index condition and Plan Rows: 1. An agent can explain that PostgreSQL estimated this access path for the named statement and recorded observation context. It cannot conclude that the native request returned one row, committed a write, took the estimated cost in milliseconds or used that exact plan during execution. Keep planningContext: committed-state-observation in the conclusion. Collection uses a separate observation of committed state, not the original transaction snapshot or its uncommitted changes. It uses planning-only EXPLAIN, without ANALYZE; estimated costs and rows are not execution measurements. A missing plan does not prove that no SQL ran, and ordinary Explain support does not establish plan coverage for every operation or backend. For the empty-query case, a plan can help explain a selected access strategy once exact statement coverage is available. A full plan may expose a request value inside a predicate, so review every occurrence when preparing the shared copy. It still cannot prove why the original result was empty. Use the shared plan guide to interpret the complete JSON and its limitations.

​
Review the conclusion before acting

Accept a finding only when its material claims name their evidence and its uncertainty matches the report’s scope. Reject an answer that invents commands, diagnostic headers, missing facts or target effects, or proposes replaying an ambiguous write to obtain another report. The next step may be a local comparison, a permitted state read, a controlled reproduction or a product-defect report. State the exact evidence needed and who may obtain it. A proposed resource or configuration change belongs in the separate change-review workflow. A performance comparison belongs in Tuning Your Adapters.