What the agent does
The agent reads the service definition and the handler before changing either. In a service shaped like aws-node-express-dynamodb-api from serverless/examples, serverless.yml declares frameworkVersion: "4", a provider on nodejs24.x and arm64, an IAM statement granting dynamodb:Query, Scan, GetItem, PutItem, UpdateItem and DeleteItem on UsersTable, an environment variable USERS_TABLE set from ${param:tableName} (users-table-${sls:stage}), one function api with handler.handler on httpApi: "*", and a PAY_PER_REQUEST DynamoDB table in resources. handler.js builds an Express 5 app behind serverless-http, creates one DynamoDBClient wrapped in DynamoDBDocumentClient.from(...), and serves GET /users/:userId and POST /users with GetCommand and PutCommand. package.json lists @aws-sdk/client-dynamodb and @aws-sdk/lib-dynamodb at ^3.585.0, express at ^5.2.1 and serverless-http at ^4.0.0, with no lockfile committed and no tests; .gitignore covers node_modules and .serverless. There is no tracing key anywhere in the repository.
The agent adds tracing: { lambda: true } under provider, which makes the Framework set TracingConfig: Active on the function and add the X-Ray write permissions to the generated role. It does not add tracing: { apiGateway: true }, because this service uses the httpApi event, and API Gateway's HTTP API does not emit X-Ray segments; that setting applies to REST API (http events) only. The pull request says so plainly, so nobody waits for gateway segments that cannot appear. If the team wants gateway-level traces they can move to http events, which is a separate change with its own costs.
For the function itself, the Lambda runtime opens the segment; what the service lacks is subsegments for its DynamoDB calls. The agent adds aws-xray-sdk-core to dependencies and wraps the client once at module load with captureAWSv3Client(new DynamoDBClient()), so every GetCommand and PutCommand through docClient shows as a subsegment with the table name and the call's status. Outside Lambda the SDK logs a missing-context error, so the agent sets AWS_XRAY_CONTEXT_MISSING=LOG_ERROR in the function's environment rather than letting a local require fail, and notes that in the sandbox the module loads cleanly with node -e "require('./handler')".
Verification depends on one thing the sandbox may not have. The Framework's v4 CLI signs in with a Serverless access key, so serverless package only runs when the Project has SERVERLESS_ACCESS_KEY saved as a secret. When it does, the agent runs npm install, serverless package, and reads .serverless/cloudformation-template-update-stack.json to show TracingConfig on the function and the X-Ray actions in the role policy, and pastes those lines in the pull request. When it does not, the agent says so, validates the YAML by reading the Framework's documented schema, and leaves the packaged-template check as the first thing a maintainer runs. The .serverless directory is already ignored, so nothing generated is committed.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add X-Ray tracing to this Serverless Framework service and open a pull request. Read serverless.yml, handler.js, package.json and .gitignore first. Under provider add tracing with lambda set to true. Do not add apiGateway tracing: this service uses the httpApi event and HTTP API does not produce X-Ray segments, so say that in the pull request instead and name the alternative of REST API http events. Add aws-xray-sdk-core to dependencies and wrap the DynamoDBClient once at module load with captureAWSv3Client so every DynamoDB call becomes a subsegment; set AWS_XRAY_CONTEXT_MISSING to LOG_ERROR in the function environment so the module loads outside Lambda. Run npm install and node -e \"require('./handler')\" to show the handler loads. If SERVERLESS_ACCESS_KEY is present in the environment, run serverless package and paste the TracingConfig block and the X-Ray role statements from .serverless/cloudformation-template-update-stack.json in the pull request description; if it is not present, say so and list that command as the first thing to run. Commit nothing from .serverless or node_modules, and change nothing else.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request with three changed files: serverless.yml with tracing: lambda: true and the new environment variable, package.json with aws-xray-sdk-core added, and handler.js with the wrapped client. The description states that HTTP API produces no gateway segments and why the apiGateway flag was not set, shows the node -e require succeeding, and, when the Project had the Framework access key, quotes the TracingConfig and role statements from the packaged template.
A reviewer checks that the client is wrapped exactly once at module scope and not per request, that the function role gained only the X-Ray write actions the Framework adds for tracing.lambda, and that no .serverless output was committed. After merge, the next serverless deploy turns on active tracing, and the first requests to /users show a Lambda segment with DynamoDB subsegments in the X-Ray console.
Run it on every Linear issue labelled agent
In the console, an automation with a linear trigger on linear.issue.labeled and the label agent starts one run per labelled issue, with the issue as its context, in the Project that has the repository. An issue titled Enable X-Ray on the users API with this prompt in its description is the whole input, and because the Project holds SERVERLESS_ACCESS_KEY as a secret, every run from it can package the service. Changes made by an app integration never fire the trigger, so the agent's own comment on the issue does not start a second run.
From your own server, the same run is one POST /o/{org}/p/{project}/sessions per issue, so the secret is in front of the agent: the repository in resources, plus the issue's https://linear.app/<workspace>/issue/<ID> URL there too, read through your Linear connection into the prompt. A webhook on the API key posts run.completed or run.failed when the turn finishes, with the session_url to read the pull request link.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
The two lines in serverless.yml are easy; knowing which of them does nothing is the work. apiGateway: true is in every tutorial and silently has no effect on an httpApi service, and a wrapped SDK client that is created per request or without the context-missing setting fails in exactly the environment where nobody looks, local tests. The agent reads the event type, picks the settings that apply, loads the handler in its own sandbox, and packages the service when it has the key, so the pull request carries the generated template's TracingConfig as evidence instead of a screenshot of the console.
A Project secret makes that evidence routine. Once SERVERLESS_ACCESS_KEY is saved on the Project, every run started in it, from a Linear label or from your server, can run serverless package and read the template, and the run's record keeps the output beside the diff.
Frequently asked questions
Why no API Gateway traces?
The service's function listens on an httpApi event, which is API Gateway's HTTP API, and HTTP API does not integrate with X-Ray. The tracing.apiGateway setting only applies to REST API, the http event. The agent leaves it out and says so, rather than adding a flag that would do nothing.
Does it need a Serverless access key?
Only to run serverless package, because the v4 CLI signs in. Save it as a Project secret named SERVERLESS_ACCESS_KEY and start the run in that Project, and the agent packages the service and quotes the template. Without it, the agent still makes the change and names the command as the first thing to run.
Will it deploy to AWS?
No. The prompt stops at serverless package, which renders the CloudFormation template locally and needs no AWS credentials. Deploying is the maintainers' step after review, and the first deployment is when active tracing takes effect.
Why wrap the client at module load instead of in each route?
The handler already creates one DynamoDBClient at module scope and reuses it across invocations, which is what keeps connections warm. Wrapping that one instance with captureAWSv3Client once gives every command a subsegment; wrapping per request would create a client per call and lose the reuse.