Skip to main content
Cloud Adapter’s included agents help compare observations, question a suspected bottleneck and prepare a tuning experiment. A useful proposal connects a measured workload problem to one supported control. The proposal must identify what would improve, how you would measure it and what you would do if the change makes things worse. Use Support Agents to bring a support question into the investigation. Use Agents and Permissions for agent identity, tool restrictions and model processing. Use Bounded Work and Approval for change authority and War Rooms for collaboration. This page focuses on the performance experiment.

​
Start with workload evidence

“Make this faster” leaves the agent to guess both the problem and the acceptable tradeoffs. Give it the actual mapping, effective settings and measurements instead. If requests fail for an unknown reason, first use Debugging with Agents to establish what happened. The configuration worker’s assessment is useful context, but it does not establish live health, placement or sufficient capacity. Obtain those observations through separately authorized tools. Keep missing measurements explicitly unknown.

​
Ask for one reviewable experiment

Have the agent produce a proposal with these parts: Use only controls documented for the selected mapping. A target-cloud API field is not automatically a supported t9:tuning: tag. An SQS receive parameter, a table-owned Cosmos capacity setting and a shared PostgreSQL server size have different scopes and owners. See Tuning Your Adapters. A model recommendation cannot approve its own change. Review it through the separate change decision before execution, including any infrastructure spending. Record proposed savings as estimates until measured.

​
Worked example: reduce empty SQS receives

Suppose a Standard queue on Google Pub/Sub receives intermittent notifications. Consumers issue many empty receives between bursts. The bounded question is: does a twenty-second receive wait reduce empty application calls while preserving successful processing and the application’s latency budget? Use a disposable queue and test project prepared with the SQS on Pub/Sub trial. That guide establishes origin authentication, target permissions, the adapter endpoint and SQS_TUNING_QUEUE_URL. Run the following commands in that configured shell. Receiving claims messages; process and delete each returned message through the test consumer only after successful processing.

​
Establish the baseline

Choose a fixed arrival schedule containing both idle time and a burst. Record payloads, consumer count, retry policy and processing time. Use fresh test job IDs for each run, while keeping the workload comparable. Set the client’s read timeout above twenty seconds, allowing for network overhead, for both comparisons. The baseline consumer explicitly uses a zero-second wait:
This is one receive request, not a load generator. Apply the same parameters to the baseline test consumer and record empty receives, total calls, completed jobs, duplicate processing, errors, retries and end-to-end job latency for the chosen window. Include target utilization and native operation volume.

​
Propose and test the candidate

The candidate changes only the per-request wait:
The request overrides the queue’s default wait. An available message can return immediately; twenty seconds is the maximum wait, not an added processing delay. Keep visibility, consumer count, payloads and arrival schedule fixed. Do not add a tuning tag or resize Pub/Sub for this experiment. Before running, agree on the maximum test duration and cost, required completed-job count, latency budget and acceptable duplicate/error rates. Stop if correctness or recovery requirements fail. Compare completed work and arrival-to-completion latency, rather than interpreting a longer empty receive as slower job processing. Fewer application calls do not establish an equal reduction in native Pub/Sub operations or billing. Measure target operation volume and the applicable cost drivers separately. An agent should report the observed result and remaining uncertainty, rather than invent a savings percentage.

​
Keep or reverse the change

If the candidate meets the agreed requirements, submit the measured result and exact consumer configuration change for approval through its normal owner. Preserve the test resource identities and source revisions with the result. To reverse this experiment, restore the consumer’s explicit --wait-time-seconds 0 equivalent. The queue default was not changed. Restoring the wait does not release messages already claimed or undo completed jobs: settle successful work using its current receipt handle, and allow unacknowledged work to become available under the visibility policy. Consumers still need idempotent processing. The SQS guide covers backend-specific claim and restart behavior.

​
Use Explain as supporting evidence

Use Explaining SDK Requests for the report endpoint, signing settings and retrieval procedure. ExecuteAndExplain preserves the ordinary native AWS service response and supplies a report receipt when capture is admitted. Retrieve stored evidence separately through the dedicated t9 service using the report owner’s origin IAM credentials, SigV4 signing and GetExplanation. A report ID does not give an agent permission to read it. x-t9-explain: true executes the operation. Explicit preview mode suppresses the operation and returns 409 ExplainedNotPerformed for a completed preview; it does not return a successful native operation result. Neither preview nor a report proves that a tuning change improves performance. Preserve independent native-state checks and workload measurements. Use the report’s stated expiry as the deadline for exporting needed evidence privately. Retention is fixed from creation, with a default of twenty-four hours; reads do not renew it. Review the contents before sharing with a person or model; choosing Agent format does not sanitize it or authorize disclosure. PostgreSQL planning evidence is specific to the captured operation and backend. Its complete native JSON may contain relation and index names, predicates and application literals, including private values. The EXPLAIN (FORMAT JSON) observation estimates a plan against committed state through a separate connection. It does not use ANALYZE, reproduce the original transaction snapshot or measure actual execution. Use the PostgreSQL query-plan guide when comparing that evidence. Continue with Tuning Examples or the DynamoDB, SQS and PostgreSQL guides for supported controls and complete experiments.