# Add Custom Search Attributes to Temporal Workflows

Yes. An agent defines typed search attributes for your workflows, sets them at start and on each stage change, registers them for the dev server, and opens a PR.

[Run this on Rush](https://cloud.getrush.ai/run/add-search-attributes/temporal/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The agent clones the repository into its own cloud sandbox and reads what a workflow carries that an operator would want to search by. In a project like temporalio/money-transfer-project-template-ts, `src/shared.ts` defines `PaymentDetails` with `amount`, `sourceAccount`, `targetAccount` and `referenceId`, and `src/client.ts` starts `moneyTransfer` with `workflowId: 'pay-invoice-801'` on the `money-transfer` task queue. None of those fields is visible in a list query: today the only way to find the transfers for one account is to open executions one by one, because nothing is indexed beyond the default attributes. `src/workflows.ts` moves through three stages, withdraw, deposit and, on a failed deposit, refund, with no record of which stage an execution is in other than its event history. Tests run in `TestWorkflowEnvironment.createLocal()` from `@temporalio/testing` at `~1.14.1`.

It adds typed keys to `src/shared.ts` with `defineSearchAttributeKey` from `@temporalio/common`: `SourceAccount` and `TargetAccount` as `KEYWORD`, `ReferenceId` as `KEYWORD`, `TransferAmount` as `DOUBLE`, and `TransferStage` as `KEYWORD`. In `src/client.ts` the start call passes `typedSearchAttributes` with the first four taken from `details`, so every new execution is searchable from its first event. In `src/workflows.ts` the workflow calls `upsertTypedSearchAttributes` from `@temporalio/workflow` to set `TransferStage` to `withdrawn` after the first activity returns, `deposited` after the second, and `refunded` or `failed` on the error paths, each before the `ApplicationFailure` that ends the run, so a failed transfer is still findable by where it failed.

Custom attributes must exist on the namespace before a start or upsert names them, or the call is rejected. The agent adds a `scripts/search-attributes.sh` that registers all five with `temporal operator search-attribute create --namespace default --name ... --type ...`, references it from the README beside the existing steps for starting the server and worker, and makes the tests self-contained by starting the local test server with the attributes declared through the test environment's server options, so `npm test` needs no manual registration. For Temporal Cloud the README notes that the same five are created once per namespace in the Cloud UI or with its CLI, with the same names and types.

A new `src/list.ts` behind `npm run list` shows the payoff: it calls `client.workflow.list` with a query such as `WorkflowType = "moneyTransfer" AND SourceAccount = "85-150"` and prints each execution's id, status and `TransferStage` from `typedSearchAttributes` on the description. The tests in `src/mocha/workflows.test.ts` gain assertions that `handle.describe()` after a successful run reports `TransferStage` as `deposited` and the account keys as passed, and that the failed-deposit case ends with `refunded`. `npm run lint`, `npm run build` and `npm test` run in the sandbox before the pull request opens.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Add custom search attributes to this Temporal TypeScript project so transfers can be found by account, reference and stage. Read src/shared.ts, src/client.ts, src/workflows.ts and the mocha tests first. Define typed keys with defineSearchAttributeKey for SourceAccount, TargetAccount and ReferenceId as Keyword, TransferAmount as Double and TransferStage as Keyword. Pass the first four as typedSearchAttributes when the client starts the workflow, and upsert TransferStage inside the workflow at each stage including the refund and failure paths. Add a script that registers the attributes on a namespace with the temporal CLI, document it and the Temporal Cloud equivalent in the README, and start the local test server with the attributes declared so the tests need no manual step. Add a list script that queries by SourceAccount and prints id, status and stage, extend the workflow tests to assert the attributes on describe, run lint, build and the test suite, and open a pull request.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **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.
2. **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.
3. **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 that changes `src/shared.ts`, `src/client.ts`, `src/workflows.ts`, `src/mocha/workflows.test.ts`, `package.json` and `README.md`, and adds `src/list.ts` and `scripts/search-attributes.sh`. The description lists the five attributes with their types and where each is set, and shows the list query and its output from the sandbox run against the local dev server.

The run's record keeps the `npm test` output with the new assertions visible, the registration command's output, and the `list` script's output, so a reviewer can see the query returning the started execution with its stage without running a Temporal server themselves.

Before merging, a reviewer confirms the attribute names do not collide with ones already defined on the production namespace, since names are namespace-wide and a type mismatch with an existing name is an error, and plans the one-time registration on each environment before the worker that upserts them is deployed.

## Run it on every Linear issue labelled observability

In the console, an automation in the Project that has the repository, with a `linear` trigger on `linear.issue.labeled` and `labels` set to `observability`, starts one run per issue with the issue as context after the prompt; the saved prompt is the whole instruction and the trigger fills in no placeholder. Later issues ask for one more attribute, a `Currency` keyword or a `RetryCount` integer, and each run adds the key, the registration line, the upsert and the test assertion together, which is the set that is easy to leave half done by hand.

From your own tracker, a handler sends one `POST /o/{org}/sessions` with this body and the repository in `resources`, with a `request_id` that is a UUID v5 of the issue id so a repeated webhook returns the run already started. Set a webhook URL on the API key and Rush posts `run.completed` with the `session_url` when the pull request is up.

## Why run it on Rush?

Search attributes touch four places that must agree: the key definitions, the start call, the upserts inside the workflow, and the namespace registration, and the failure mode for a mismatch is a rejected start in production rather than a compile error. The agent's sandbox runs a real dev server through the SDK's test environment, so a name or type that does not match is caught by a failing test in the run, with the server's error in the record.

It also produces the proof an operator wants before trusting a new query: the `list` script's actual output against executions the run started, kept with the pull request, instead of a promise that the attributes will show up in the UI after deploy.

## Frequently asked questions

### Why Keyword rather than Text for the account fields?

Keyword attributes match exactly and support equality and `IN` queries, which is what an account number or reference id needs. Text attributes are tokenised for full-text search, which would split or normalise identifiers in ways that make exact lookup unreliable.

### Does upserting inside the workflow add history events?

Yes, one `UpsertWorkflowSearchAttributes` event per call, which is why the agent upserts only on stage transitions rather than on every activity attempt. Four or five events across a transfer's lifetime is a small addition to a history that already records each activity and its retries.

### Will adding the upserts break executions already running?

An upsert is a new command in the workflow code, so executions started before the deploy would hit a non-determinism error on replay. The pull request guards the new calls with `patched()` when the prompt says executions may be in flight, the same technique used for any workflow code change, and the description says which to choose.

### How are the attributes created on Temporal Cloud?

Once per namespace, through the Cloud UI or its CLI, with the same names and types the script uses for the local server. The README section the pull request adds lists them so the production registration is a copy of the development one rather than a reconstruction.

### Is there a limit on how many attributes a namespace can have?

Namespaces have a cap on custom attributes and on the size of their values, and the numbers differ between self-hosted and Cloud. Five typed keys for one workflow is well within either, and the agent reuses an attribute such as `TransferStage` across stages rather than defining one key per stage.

## More Temporal jobs

- [Add Signals and Queries to a Temporal Workflow](https://getrush.ai/run/add-signals-and-queries/temporal/)
- [Add Structured Logging to a Temporal TypeScript Worker](https://getrush.ai/run/add-structured-logging/temporal/)
- [Add Cancellation Handling to a Temporal Workflow](https://getrush.ai/run/add-workflow-cancellation/temporal/)

## More jobs like this: Turn a Linear label into a PR

- [Add Search to an Eleventy Blog from a Linear Issue](https://getrush.ai/run/add-search/eleventy/)
- [Add Search to a Gatsby Blog from a Linear Issue](https://getrush.ai/run/add-search/gatsby/)
- [Move Airflow Connections to a Secrets Backend](https://getrush.ai/run/add-secrets-backend/airflow/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
