hashbrown

Upgrade to v0.8

Follow actual agent progress, stable activity links, and a new activity ID in the next turn.

Recorded in the real React workbench with OpenAI and the actual Hashbrown SDK. The local AG-UI agent maps shared state into instructions and authors state, activity and approval events around unchanged provider text. No browser tools, generated UI schema or executed plan steps. Approval permits another explanation only. The approval store is bounded, expiring and process-local. Unchanged provider events are paced at 20 ms for filming; the normal host adds no delay. Footage slowed to half speed for readability. Replay makes no requests or writes. No narration. Read the text walkthrough.

The teaser shows the current client flow. It does not run the historical SDK versions in this upgrade guide. Apply the version-specific steps below to your application before comparing its behavior with the current workbench.

Hashbrown v0.8 adds AG-UI activities to the message list and gives user and assistant messages an id. It also moves the hashbrown object on the AG-UI run input from the top level into forwardedProps.hashbrown, the AG-UI extension point for values the agent reads and intermediaries pass through untouched. The object itself, responseSchema and ui, is unchanged. A v0.8 client sends only the new shape, so upgrade the server's adapter together with the client. It removes few-shot UI examples and the prompt template, and the OpenAI and Azure adapters move to the Responses API with reasoning.

Your React components and hooks keep their APIs, apart from the removed examples option, and code that switches on a message role needs an 'activity' case. The run-input change lands in server code that reads the run input itself: a custom provider, a custom transport, or a route that inspects input.hashbrown before handing the input to an official adapter. Every step after the first says when it applies, so skip the ones that don't match your app.


Checklist

  1. Update Hashbrown packages together.
  2. Read the extension from forwardedProps.hashbrown. Only if your server, provider or transport reads input.hashbrown.
  3. Replace UI examples with rules. Only if you pass examples to a kit or a UI hook, or build a system prompt with prompt.
  4. Move transformRequestOptions to the Responses API. Only if you use the OpenAI or Azure adapter.
  5. Stop expecting activity messages in run input. Only if your server reads role: 'activity' messages from input.messages.
  6. Handle role: 'activity' in code that switches on message role. Only if your app reads Chat.Message values.
  7. Expect id on user and assistant messages. Only if you compare whole messages or build them by hand.

Prefer to let an AI coding assistant do the mechanical parts? Jump to Migrate with an AI assistant.


Update Packages

Hashbrown packages are released together, and every @hashbrownai/* package in your app must be on the same version. The official adapters on v0.8 read only forwardedProps.hashbrown, so update the server's adapter together with the client.

terminal
npm install @hashbrownai/core@0.8.0 @hashbrownai/react@0.8.0

Read the Extension from forwardedProps

Any code that reads the extension from the top level sees undefined on v0.8. Replace it with the forwardedProps path.

before
const responseSchema = input.hashbrown?.responseSchema;
after
const responseSchema = input.forwardedProps?.hashbrown?.responseSchema;

If your server rewrites the extension, for example to pin the response schema, write it back under forwardedProps and keep the rest of forwardedProps intact, since other values of yours may travel there too.

pin the schema
return {
  ...input,
  forwardedProps: {
    ...input.forwardedProps,
    hashbrown: { ...input.forwardedProps?.hashbrown, responseSchema },
  },
};

The custom provider guide shows the full input type.


Replace UI Examples with Rules

v0.8 removes few-shot UI examples: the examples option on useUiKit, useUiChat, the UI completion and createUiJsonSchema(), and the prompt tagged template with its <ui> blocks. The system option is a plain string. Strict structured output already guarantees the shape, hand-written examples drift when a component changes, and reasoning models do better without them.

Put the guidance where it travels with the component:

  1. Component descriptions say when to use the component, when not to, and how it differs from similar ones.
  2. Prop descriptions and schema constraints carry value conventions: units, formats, ranges and allowed values.
  3. A short plain-string system holds layout and composition rules.
before
system: prompt`
  You are a smart home assistant.

  <ui>
    <LightCard lightId="light-1" brightness={80} />
  </ui>
`,
after
system: `
  You are a smart home assistant.

  - Show one LightCard for each light the user asks about.
  - Add at most one Markdown summary, after the cards.
`,

Then delete every examples option, and replace the removed types SystemPrompt, HBTree, PromptDiagnostic, PromptDiagnosticCode and PromptDiagnosticSeverity with string or drop them. Kits that used examples now produce a shorter schema description, so regenerate any copy of the schema you keep on the server or on disk. Use the component catalogue guidance to keep component names and descriptions useful alongside those rules.


OpenAI and Azure on the Responses API

The OpenAI and Azure adapters now stream from OpenAI's Responses API instead of Chat Completions, and request reasoning summaries from reasoning models. Chat history, tools, and structured output work as before. Four things can need changes on the server. Both packages raise their openai peer dependency to ^6.45.0, so update that too.

transformRequestOptions receives Responses params

transformRequestOptions now receives and returns OpenAI.Responses.ResponseCreateParamsStreaming. Messages, including system messages, become input items, and max_tokens and max_completion_tokens become max_output_tokens. To add server instructions, you can set instructions.

before
transformRequestOptions: (options) => ({
  ...options,
  max_completion_tokens: 2048,
  messages: [
    { role: 'system', content: 'You are a helpful assistant.' },
    ...options.messages,
  ],
}),
after
transformRequestOptions: (options) => ({
  ...options,
  max_output_tokens: 2048,
  instructions: ['You are a helpful assistant.', options.instructions]
    .filter(Boolean)
    .join('\n\n'),
}),

Chat Completions-only servers are no longer supported

@hashbrownai/openai requires a server that implements the Responses API. If you point baseURL at a Chat Completions-only server, for example vLLM, OpenRouter, or LM Studio depending on the server and mode, requests fail. Use a server that supports the Responses API, or keep that server on Hashbrown v0.7.

Reasoning is on by default for reasoning models

When you don't set reasoning, models whose names start with o and a digit, gpt-5, or gpt- followed by a major version of 5 or later, other than -chat variants such as gpt-5-chat-latest, get reasoning: { summary: 'auto' }. The client then receives AG-UI reasoning events, and assistant messages expose reasoning and reasoningDetails. Hashbrown never sends effort unless you set it.

To stop requesting summaries, set reasoning: false. This does not disable reasoning in the model: a reasoning model may still return encrypted reasoning, which Hashbrown replays on the next turn. To tune it, pass reasoning: { effort: 'low' }.

turn off reasoning summaries
HashbrownOpenAI.stream.text({
  apiKey: process.env.OPENAI_API_KEY!,
  model: 'gpt-5',
  input,
  reasoning: false,
});

Every request now sends store: false, and Hashbrown replays earlier reasoning from the client's history.

Azure endpoint and deployment

HashbrownAzure.stream.text keeps clientOptions: AzureClientOptions. Set endpoint and an apiVersion that supports the Responses API (for example '2025-04-01-preview'), and remove clientOptions.deployment: setting it now fails the run with a RUN_ERROR. The model option is the deployment name.

before
HashbrownAzure.stream.text({
  clientOptions: {
    apiKey: process.env.AZURE_API_KEY!,
    endpoint: process.env.AZURE_ENDPOINT!,
    apiVersion: process.env.AZURE_API_VERSION!,
    deployment: process.env.AZURE_DEPLOYMENT,
  },
  model: process.env.AZURE_MODEL!,
  input,
});
after
HashbrownAzure.stream.text({
  clientOptions: {
    apiKey: process.env.AZURE_API_KEY!,
    endpoint: process.env.AZURE_ENDPOINT!,
    apiVersion: process.env.AZURE_API_VERSION ?? '2025-04-01-preview',
  },
  model: process.env.AZURE_DEPLOYMENT!,
  input,
});

Because the deployment name decides whether Hashbrown requests reasoning, set reasoning explicitly when the name doesn't reveal the model, and reasoning: false for a non-reasoning deployment whose name happens to match. Azure does not stream partial images and does not guarantee a reasoning summary on every request.


Activity Messages Stay on the Client

Keep activities in the transcript, out of the next run

Scroll horizontally to see the full diagram, or expand it.

AG-UI activity eventsSnapshot and deltaClient messagesConversation + activitiesNext run inputConversation; activitiesremovedSaved transcriptCan retain activity records
The v0.8 change affects display and request history differently. Saving canonical messages can retain activities.
Read the diagram

Server activity events reach the client’s message list alongside conversation messages. On the next run, Hashbrown removes role activity records from outbound messages. A saved client transcript can retain them; they are not instructions for the agent.

Keep activities in the transcript, out of the next run

The v0.8 change affects display and request history differently. Saving canonical messages can retain activities.

Read the diagram

Server activity events reach the client’s message list alongside conversation messages. On the next run, Hashbrown removes role activity records from outbound messages. A saved client transcript can retain them; they are not instructions for the agent.

AG-UI activity messages (role: 'activity') are display material for the client. The AG-UI specification says a client must not send them back to the agent. Hashbrown now removes them from input.messages before each run. Before 0.8, an activity message that reached Hashbrown through a MESSAGES_SNAPSHOT event was sent back on later runs.

Hashbrown's own providers already ignored these messages, so most apps need no change. If your server read activity messages from the run input, keep that state on the server or send it through AG-UI state instead.


Activity Messages in the Message List

AG-UI activities now reach your app. Chat.Message gains a fourth variant, ActivityMessage, with role: 'activity'. Activity messages appear in chat.messages where they arrived, with an id, an activityType, untyped content, and links to the run, assistant message and tool call they belong to. Before 0.8, Hashbrown dropped them from the message list.

Most code that switches on message.role still type checks. What breaks is an exhaustive check that assigns the leftover role to never, and an else or default branch that assumes the message is an assistant message. Add an 'activity' case, even if you ignore it, so an activity is not mistaken for a user or assistant message.

before
switch (message.role) {
  case 'user':
  case 'assistant':
  case 'error':
  // ...
}
after
switch (message.role) {
  case 'user':
  case 'assistant':
  case 'error':
    // ...
    break;
  case 'activity':
    // Render it by `message.activityType`, or ignore it.
    break;
}

Two behaviors follow from this:

  • reload and the logic that decides whether the last message needs an answer skip trailing activities. An activity is never the last user or assistant message.
  • Activity messages round-trip through setMessages and the initial messages, so a stored transcript keeps them. They are still never sent to the agent.

React apps that persist chat.messages to storage need no change, but the stored value may now contain activity messages. See Activities for rendering them and for groupTurns.


User and Assistant Messages Have an id

User and assistant messages now expose a stable id, the canonical AG-UI message id. Activities link to it through links.assistantMessageId, and groupTurns keys by it. The id of a streaming assistant message does not change when the message is committed. Error messages are synthetic and have no id.

On input, id is optional. setMessages, the initial messages option and sendMessage keep an id you supply and mint one only when it is absent, so a transcript you save and restore keeps its links. Code that builds messages by hand needs no change.

Code that compares whole message objects, for example in tests with toEqual, now sees the extra id field. Match on the fields you care about, or use expect.any(String) for the id.


Migrate with an AI Assistant

This upgrade is mostly mechanical. Paste this prompt into an AI coding assistant such as Claude Code from the root of your repository. It inventories your code first and shows you a plan before it changes anything.

migration-prompt.md
Upgrade this repository from Hashbrown v0.7 to v0.8. The full guide is at https://hashbrown.dev/docs/react/migrations/v0-8 (React) and https://hashbrown.dev/docs/angular/migrations/v0-8 (Angular). Read the guide for my framework before changing anything, and do not invent APIs that are not in it.

First, inventory. Search the repository and list every place that:

1. Depends on any `@hashbrownai/*` package, with its current version.
2. Reads `hashbrown` from an AG-UI run input, such as `input.hashbrown`, `input.hashbrown?.responseSchema` or a destructured `{ hashbrown }`.
3. Writes a `hashbrown` key onto a run input, for example to pin or replace a response schema.
4. Declares a type that extends `RunAgentInput` with a top-level `hashbrown` member.
5. Passes `transformRequestOptions` to `HashbrownOpenAI` or `HashbrownAzure`, sets `baseURL` on `HashbrownOpenAI`, or sets `clientOptions.deployment` on `HashbrownAzure`.
6. Passes `examples` to a UI kit, a UI chat or completion hook or resource, or `createUiJsonSchema`.
7. Imports `prompt`, `SystemPrompt`, `HBTree` or `PromptDiagnostic*` from `@hashbrownai/core`, or writes a `system` with `<ui>` blocks.

Show me the inventory and a short plan before editing.

Then make these changes, only where the inventory found something:

- Update every `@hashbrownai/*` package to exactly 0.8.0, together.
- Read the extension from `input.forwardedProps?.hashbrown` instead of `input.hashbrown`, and remove any `?? input.hashbrown` fallback.
- Write the extension back under `forwardedProps.hashbrown`, spreading the existing `forwardedProps` so other values in it survive.
- Move the top-level `hashbrown` member of your own input types under `forwardedProps`.
- Delete every `examples` option. Move its guidance into the component's `description`, the prop descriptions and schema constraints, and a short plain-string `system` with layout rules.
- Replace `prompt` tagged templates with plain strings, dropping `<ui>` blocks, and replace the removed prompt types with `string`.
- Rewrite `transformRequestOptions` for `OpenAI.Responses.ResponseCreateParamsStreaming`: `messages`, including system messages, become `input` items, `max_tokens` or `max_completion_tokens` become `max_output_tokens`, and server instructions, if any, can go in `instructions`.
- Remove `clientOptions.deployment` from `HashbrownAzure` and pass the deployment name as `model`.
- Add a `'activity'` case to every switch on a chat message `role`, rendering `message.activityType` or ignoring the message, and match messages in tests without assuming they have no `id`.
- Flag any `baseURL` that points at a Chat Completions-only server so I can decide what to do. Do not change it yourself.

Finally, run the project's type check, build, lint and tests, fix what fails, and summarize every file you changed and anything you could not migrate automatically.

Review the inventory and plan it shows you before letting it continue.


Toolchain

@hashbrownai/core 0.8 uses package imports entries. Your bundler and test runner must support package imports: Node 20 and later, Vite, webpack 5, Next.js, the Angular CLI, Jest 29.4 and later, and Vitest all do. Older toolchains, such as webpack 4 or Jest before 29.4, cannot load @hashbrownai/core 0.8; upgrade them before you upgrade Hashbrown.


Verify the upgrade

Send an ordinary message and a follow-up after upgrading the client and adapter together. Inspect forwardedProps.hashbrown at the server boundary. Verify message-role handling, retained IDs, and the revised UI guidance. If you use OpenAI or Azure, also test the Responses request transformation and deployment configuration your app actually uses.

For a separate current implementation, open /react.html?lesson=activities in the conversation workbench. Inspect activity messages and their links beside the assistant reply. Check that a subsequent request omits display-only activities. This current lesson does not run a v0.7 client or establish compatibility with a Chat Completions-only server. The upgrade commands and before/after examples above remain specific to their stated versions.

Next Steps

Upgrade to v0.8ChecklistUpdate PackagesRead the Extension from forwardedPropsReplace UI Examples with RulesOpenAI and Azure on the Responses APItransformRequestOptions receives Responses paramsChat Completions-only servers are no longer supportedReasoning is on by default for reasoning modelsAzure endpoint and deploymentActivity Messages Stay on the ClientActivity Messages in the Message ListUser and Assistant Messages Have an idMigrate with an AI AssistantToolchainVerify the upgradeNext Steps