Customize agents for your end users

You can configure your agents to behave in a different way for each one of your end users. This behavior is useful if you're using Memory and you want the same agent to store and retrieve with a user's own memories.

In Toolhouse you accomplish this with metadata.

Toolhouse only supports one type of metadata called id. You can use it to set a unique identifier for a user.

Toolhouse does not send metadata to the LLM.

By default, Toolhouse uses a user ID with value default. If you don't specify a metadata, your agent will assume to be a generic agent that has no context over all the end users of your app.

Setting metadata in the SDK

To set metadata, use the set_metadata method.

Python SDK

from toolhouse import Toolhouse

th = Toolhouse()
th.set_metadata('id', 'alice')

TypeScript SDK

import { Toolhouse } from '@toolhouseai/sdk';

const toolhouse = new Toolhouse({
  apiKey: process.env.TOOLHOUSE_API_KEY,
  metadata: {
    "id": "daniele"
  }
});

Alternatively, you can pass metadata after initialization:

import { Toolhouse } from '@toolhouseai/sdk';

const toolhouse = new Toolhouse({
  apiKey: process.env.TOOLHOUSE_API_KEY,
});

toolhouse.metadata = { id: "daniele" }; 

Metadata scoping

Toolhouse automatically scopes any metadata you pass to your app. In other words, suppose you have a user whose ID is alice. If you have two Toolhouse API keys (for example production and development), production alice will be treated as a separate user than development alice.

While metadata is scoped at the API key level, all MCP servers in that instance will share the same metadata. Effectively, this means you cannot override metadata on a per-tool basis.

Hashed users

Hashing is a one-way process that converts input data into a fixed-size string of characters. It's deterministic, meaning the same input always produces the same output, but it's computationally infeasible to reverse.

Toolhouse automatically protects your data and the data of your users by hashing the value you pass in the id metadata. This means you can safely pass any user ID you normally use, and Toolhouse will convert it into its hashed representation.

Hashing your username avoids MCP servers (including those built by Toolhouse) to see your actual user IDs, while still working with a deterministic representation of the value you pass. For example, if you pass a user value of [e-mail], Toolhouse will automatically it into something like 5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8. Due to the one-way nature of hashing, it is infeasible to convert this long string into its input user ID.

This makes it safe to pass your unique IDs as user metadata, because MCP servers will not be able to decode them. Toolhouse will not pass your cleartext user ID to any server, including those built by Toolhouse.