---
title: "How do agents retrieve brand context at runtime? | Rainbrand"
description: "Retrieve task-specific brand guidance and files, pass them to the tools making the work, and record the version used. Implement deliberate reuse and a visible failure path."
url: "https://www.rainbrand.com/blog/how-agents-retrieve-brand-context-at-runtime/"
---

By [Tomas Ward](https://www.linkedin.com/in/tomasward1/)

Published 28 Oct 2026

9 min read

# How do agents retrieve brand context at runtime?

Retrieve task-specific brand guidance and files, pass them to the tools making the work, and record the version used. Implement deliberate reuse and a visible failure path.

## TL;DR

Retrieve brand context before the step that creates branded work. Identify the intended brand, describe the task, wait for usable guidance and files, then pass them to the producing tools. Record the version used. Reuse context only while the task and relevant brand inputs still fit, and make retrieval failures visible instead of silently producing generic work.

## Fetch the context before creating the work

An agent asked to make a launch image needs more than the instruction “follow the brand”. It needs the applicable rules and usable files before it calls the image model or renderer. If an earlier step retrieves them but never passes them on, the producing tool still lacks that context.

Runtime retrieval means fetching those inputs while the task runs. Your application can do it before invoking a model, or the agent can call a tool when it recognises brand work.

| Retrieval point | Who initiates it | What to make explicit |
| --- | --- | --- |
| Application step before generation | Your code | The fetch must complete before creation starts |
| Agent tool call during the task | The model, following its instructions | When to call, what to request and what to do if it fails |
| Local snapshot read during the task | The agent or application | Which version is installed and when to replace it |

Anthropic describes [retrieving context as needed](https://www.anthropic.com/research/effective-context-engineering-for-ai-agents) through lightweight references and tools. OpenAI's [function-calling guide](https://developers.openai.com/api/docs/guides/function-calling) explains the execution loop: the model requests a tool call, your application runs it and returns the result.

An application fetch and an agent tool call can both retrieve current context. A local snapshot stays at the version installed. In each case, check whether the step making the work actually receives the guidance and files.

## Keep retrieval instructions separate from brand details

Use standing instructions to explain when the agent should retrieve a brand. Keep changeable product names, palettes and detailed guidance in the maintained context.

For an agent, cover:

- Which brand to use, and how to resolve an ambiguous request.
- Which tasks need brand context.
- How to pass the guidance and files to the tools making the output.
- What to report when retrieval fails or the guidance does not cover the task.

In a product serving several customers, use an authenticated mapping from the current customer to the Brand ID, the identifier for the maintained brand. Do not let a model guess an accessible brand from a similar name. When the selected brand is already known, pass its identifier directly.

Then describe the actual task: output format, dimensions where relevant, audience, channel, required copy and constraints. “Make a launch asset” leaves the selection underspecified. “Make a 1600 × 900 launch image for product designers with this headline and call to action” tells retrieval what the next step needs.

Keep temporary campaign instructions visible alongside the brand guidance. A proposed offer or packaging colour supplied in the task should remain distinguishable from established brand facts.

## Request and wait for usable context

Rainbrand maintains brand guidance and assets for connected agents and products. A [Brief](https://docs.rainbrand.com/guides/request-brief) selects the guidance and files relevant to one task. You send the Brand ID and task, then retrieve the completed result.

Through [MCP](https://docs.rainbrand.com/mcp/tools), the tools are `create_brief` and `get_brief`. Create the Brief, then call `get_brief` with its `brief_id` and `wait: true`. Repeat the read if it is still pending or processing.

The same sequence is available through REST. Acme and Atlas Pro, its design software for product designers, are fictional in this example. The request was checked against the current contract but not executed for this article. Set your API key in the environment and replace the example Brand ID with an accessible, ready brand.

```
curl --request POST https://www.rainbrand.com/api/v1/briefs \
  --header "x-api-key: $RAINBRAND_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "brandSessionId": "e6220a5e-4a68-4d39-8bb9-5105e9a3a164",
    "task": "A 1600 × 900 launch image for Acme Atlas Pro, aimed at product designers. Include the headline Meet Atlas Pro and the call to action Explore Atlas Pro."
  }'
```

Take the returned `data.id`, then read `GET /briefs/{id}?wait=true` using the same authentication. Continue reading while the status is `pending` or `processing`. Use the result only when it is `completed`. A `failed` result contains error details, including whether a new attempt may succeed.

The [API quickstart](https://docs.rainbrand.com/api/quickstart) covers this sequence, and [Get a Brief](https://docs.rainbrand.com/api-reference/briefs/get-a-brief) defines the response:

| REST field | Use |
| --- | --- |
| ``` data.id ``` | Save the Brief reference with the output |
| ``` data.skillId ``` | Record the brand version used; it can be null if that version was deleted |
| ``` data.guidance ``` | Pass the completed Markdown guidance to the producing step |
| ``` data.assets ``` | Route the selected files by their kind, media type and URL |
| ``` data.error ``` | Inspect failure details rather than treating a failed Brief as empty guidance |

The response from creating a Brief identifies a job; it is not the finished brand context.

## Pass both guidance and files to the producing tools

Keep the original task with the Brief. The task says what to make, while the guidance says how to apply the brand. The files supply things prose cannot reproduce exactly.

A renderer needs font bytes to set the supplied typeface. An image model may need reference images and a font specimen. A layout needs a usable logo file rather than a sentence describing the mark.

The saved [Eager demonstration](https://www.rainbrand.com/examples/eager/) shows the files supplied to Claude. Eager is a juice brand; we asked Claude to create packaging and launch material for a blackcurrant-flavour concept. The saved Brief includes logo SVGs, P22 Mackinac Pro font files at several weights, specimen images and carton references. It distinguishes the hypothetical flavour's campaign instructions from source-backed brand facts.

Pass the supported inputs to [your own generation tools](https://docs.rainbrand.com/guides/use-your-own-generation-tools). Where a tool cannot consume a supplied format, choose an appropriate rendering or composition step rather than silently dropping the asset.

For an agent connected to Rainbrand, this standing instruction can make the handoff explicit. Acme is fictional.

Add to your agent’s instructions

```
For Acme brand work, request a Rainbrand Brief describing the output, audience, channel and exact copy. Wait for completion and inspect the guidance and files. Give the original task, guidance and relevant assets to each tool creating the work. Use the supplied logo and fonts where the tool supports them. If the guidance does not fit, correct the task and request another Brief. If retrieval fails or a required file cannot be used, report it before continuing.
```

If a workflow needs the complete brand locally, [retrieve or export a Brand Skill](https://docs.rainbrand.com/guides/use-brand-skill), a versioned snapshot of the brand's identity, guidance and asset references. Keep an export's folder structure together and record its version. That snapshot needs a refresh policy too.

## Reuse by task and version

A completed Brief is useful for closely related work. Rainbrand's [Brief tools](https://docs.rainbrand.com/mcp/tools) recommend reuse when the goal, audience, creative direction and source material remain the same. Request another when those change meaningfully.

For work that should follow today's brand, check the active version before reusing saved context. [Get a brand](https://docs.rainbrand.com/api-reference/brands/get-a-brand) returns `data.activeSkill.id`; compare that with the Brief's `data.skillId`. If they differ, [request a new Brief after the edit](https://docs.rainbrand.com/guides/edit-brand). If either reference is missing, retrieve and inspect current context instead of treating missing values as a match.

A match only answers the guidance-version question. Also check whether the task still fits and whether relevant files changed. The [Brand Library](https://docs.rainbrand.com/guides/manage-brand-library) is the collection of assets available for brand work; files can be added or removed directly. [Removing a file](https://docs.rainbrand.com/api-reference/library/remove-from-a-brand-library) affects future Briefs; it does not rewrite a completed Brief. Invalidate affected cached context when your workflow changes those inputs.

A practical reuse decision is:

1. Confirm the requesting customer can still access the intended brand.
2. Confirm the cached context belongs to that brand and intended version.
3. Check that the task and relevant asset inputs have not materially changed.
4. Check that required files are usable before handing them to the producing step.

Keep historical work tied to its original inputs. A task intentionally reproducing an old campaign has a different version policy from one making new material.

A timer can bound cache age, but a one-hour expiry can still serve old guidance for an hour after an edit. Checking the active version makes that decision explicit. It does not make retrieval and generation an atomic operation: if the brand changes after your check, the task may still use the earlier context. Record the version actually used and choose when your workflow needs to recheck it.

Brief requests use credits, so avoid requesting one for every message when closely related work can reuse the result. See [Credits and limits](https://docs.rainbrand.com/api/usage-limits) for account-specific costs and limits.

## Distinguish context reuse from prompt caching

Your saved Brief and the model provider's prompt cache solve different problems.

A prompt cache reuses processing for matching input. OpenAI's [prompt-caching guide](https://developers.openai.com/api/docs/guides/prompt-caching) recommends keeping stable instructions and shared reference material early, with changing content later. That can make repeated processing cheaper or faster, depending on the model and cache behaviour.

A prompt cache does not fetch the current brand. You still decide which task context enters the request. Keep short standing instructions stable, then include the retrieved guidance and files in the task's messages or tool results.

File availability is separate again. A [Brief's asset URLs](https://docs.rainbrand.com/api-reference/briefs/get-a-brief) have no scheduled expiry while the Brief, brand, saved version and asset remain available. Anyone with a link can open the asset, so treat the URLs as shareable links. Files in a [retrieved Brand Skill](https://docs.rainbrand.com/api-reference/brands/inspect-a-brand-skill) use temporary signed URLs; retrieve again to refresh expired links. Check the returned version too, since the active brand may have changed since the previous retrieval.

## Make failure visible before generation

Do not convert retrieval failure into an empty string and let generation carry on. The output can look finished even though the model never received the brand.

Give each failure a concrete response:

| Failure | Response |
| --- | --- |
| Wrong or ambiguous brand | Resolve the intended accessible brand before requesting context |
| Brief still pending | Continue reading the same Brief |
| Brief failed | Read its error; retry only when appropriate and within your retry budget |
| Missing permission | Correct access instead of using another customer's or a default brand |
| Rate limit | Wait for the returned delay before retrying |
| Required asset unavailable | Refresh access or report the missing input |
| Context omitted from a downstream tool | Repair the handoff and repeat the affected creation step |

Rainbrand's [limits guide](https://docs.rainbrand.com/api/usage-limits) documents `Retry-After` handling. Use bounded retries and keep the failed stage visible in the job record.

After creation, [Rainbrand Review](https://docs.rainbrand.com/guides/request-review) can check the work against the brand and return findings. Follow the documented input procedure; for a visual composition, supply the finished image and expected copy. Your creation tools use those findings to revise the work. Review does not correct the asset automatically.

## Verify the entire handoff

Before relying on the integration, inspect one task record containing the selected Brand ID, Brief ID, version, supplied guidance and files, and final output.

Then test what happens when retrieval is unavailable, a cached version is outdated or the producing tool cannot read a required file. Verify that creation stops with an actionable reason instead of producing apparently complete work without its required context.

The [embedded-product guide](https://www.rainbrand.com/blog/embed-brand-context-in-your-ai-product/) covers using this arrangement inside a product. Keep the input record close to the output so a future investigation can distinguish stale context from a failure to apply it.

## More in Developers

[All 5 Developers articles](https://www.rainbrand.com/blog/topics/developers/)

- 28 Oct 2026 13 min read

    ### [Which APIs provide brand assets and guidelines?](https://www.rainbrand.com/blog/brand-apis-for-ai-agents/)

    Brand APIs return different things. Lookups describe any company’s public identity, platform APIs read the files a customer already stores, and a maintained brand returns guidance and files for each task. Compare what each returns, who keeps it current, how access works and how pricing differs.

- 28 Oct 2026 10 min read

    ### [How to add brand context to your AI product](https://www.rainbrand.com/blog/embed-brand-context-in-your-ai-product/)

    Follow a generation job from the customer’s task and authorized brand through guidance, assets, rendering and review. Keep future jobs current with saved brand versions and applied corrections.

- 28 Oct 2026 9 min read

    ### [How to manage your customers’ brands in an AI product](https://www.rainbrand.com/blog/manage-customer-brands-in-an-ai-product/)

    Tie each customer to the right brand on your server, then handle creation, corrections, versions and deletion without exposing another customer's guidance or files.

One brand, every agent.

[Connect your agents](https://docs.rainbrand.com/mcp/getting-started)