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

# Tuning with Agents

> Turn workload evidence into a bounded tuning proposal, compare it with a baseline and plan reversal or recovery.

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](https://docs.tensor9.com/cloud-adapter/support/agents.md) to bring a support question into the investigation. Use [Agents and Permissions](https://docs.tensor9.com/cloud-adapter/operations/agents.md) for agent identity, tool restrictions and model processing. Use [Bounded Work and Approval](https://docs.tensor9.com/cloud-adapter/operations/bounded-work.md#review-a-change-as-a-separate-decision) for change authority and [War Rooms](https://docs.tensor9.com/cloud-adapter/operations/war-rooms.md) 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](https://docs.tensor9.com/cloud-adapter/debugging/agents.md) to establish what happened.

| Input | Why it matters |
| - | - |
| Adapter version, backend, region and resource identities | A supported control or measured result may apply only to this mapping and deployment. |
| Current configuration and native readback | Requested settings can differ from effective settings. Identify the system that owns each field. |
| Operation mix, payload sizes, keys, arrival pattern and concurrency | An idle queue, a hot partition and a saturated shared database need different experiments. |
| Completed work, latency distribution, errors and retries | Lower latency is not an improvement if more work fails or is retried. |
| Native utilization and cost drivers | A client bottleneck does not establish a need for more backend capacity. |
| Correctness and recovery requirements | Ordering, duplicate handling and recovery time can constrain a performance change. |

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:

| Part | Required detail |
| - | - |
| Baseline | Exact workload, current effective settings and measurement window. |
| Hypothesis | The suspected limiting factor and the evidence that supports it. |
| Candidate | One supported field or application setting, old and new values, units, scope and documented change path. |
| Comparison | Same workload and measurements, including correctness and failure checks. |
| Cost | Expected changes in native operations, capacity, storage and model use, with separate limits. |
| Acceptance and stopping rules | Numeric requirements chosen before the run, plus conditions that stop it. |
| Approval | The resource owner, executing principal and exact permitted effects. |
| Reversal and recovery | How to restore the previous configuration and how to handle work or data already affected. |

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](https://docs.tensor9.com/cloud-adapter/tuning/overview.md).

A model recommendation cannot approve its own change. Review it through the [separate change decision](https://docs.tensor9.com/cloud-adapter/operations/bounded-work.md#review-a-change-as-a-separate-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](https://docs.tensor9.com/cloud-adapter/tuning/aws-sqs.md#try-sqs-on-pubsub). 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:

```bash theme={null}
aws sqs receive-message \
  --queue-url "$SQS_TUNING_QUEUE_URL" \
  --max-number-of-messages 1 \
  --wait-time-seconds 0 \
  --visibility-timeout 120
```

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:

```bash theme={null}
aws sqs receive-message \
  --queue-url "$SQS_TUNING_QUEUE_URL" \
  --max-number-of-messages 1 \
  --wait-time-seconds 20 \
  --visibility-timeout 120
```

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](https://docs.tensor9.com/cloud-adapter/tuning/aws-sqs.md) covers backend-specific claim and restart behavior.

## Use Explain as supporting evidence

Use [Explaining SDK Requests](https://docs.tensor9.com/cloud-adapter/debugging/explain-sdk.md) 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](https://docs.tensor9.com/cloud-adapter/debugging/postgres-query-plans.md) when comparing that evidence.

Continue with [Tuning Examples](https://docs.tensor9.com/cloud-adapter/tuning/examples.md) or the [DynamoDB](https://docs.tensor9.com/cloud-adapter/tuning/aws-dynamodb.md), [SQS](https://docs.tensor9.com/cloud-adapter/tuning/aws-sqs.md) and [PostgreSQL](https://docs.tensor9.com/cloud-adapter/tuning/aws-rds-postgresql.md) guides for supported controls and complete experiments.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.