Primitive of the day · 2026-10-07

textgrad-wrap-inputs-as-variables

TextGrad's BlackboxLLM and TextLoss operate on tg.Variable objects, never raw strings — wrap every input, with requires_grad=True only on the text being optimized and requires_grad=False on task briefs.

When this applies

Feeding any prompt, system prompt, or task input into a TextGrad forward/backward pipeline.

Preconditions

• textgrad is installed and the pipeline uses BlackboxLLM/TextLoss/TGD
• It is decided which single variable is the optimization target

Do this

Wrap the optimization target as tg.Variable(text, requires_grad=True, role_description=...) and every other input as tg.Variable(..., requires_grad=False, role_description=...); pass only Variables into model() and loss_fn().

What you should see

The computation graph tracks the target variable; backward() produces a text gradient for it and optimizer.step() rewrites it.

How it fails if ignored

Passing raw strings breaks the forward/backward API (it operates on Variables, not strings); forgetting requires_grad flags either optimizes the wrong text or tracks nothing.

Do not use when

Not applicable outside the textgrad library; do not wrap values consumed by non-textgrad code paths.

Kind: gotcha-fix. Part of the skill Textgrad prompt optimizer. Free to reuse in your own agent skills.