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 Toolhouse ID.

Toolhouse only supports one type of metadata called toolhouse_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 an ID, your agent will assume to be a generic agent that has no context over all the end users of your app.

Setting the Toolhouse ID

To set an ID, you simply need to pass it in your first agent request:

curl -XPOST "https://agents.toolhouse.ai/$YOUR_AGENT_ID" \
  --json '{ "message": "what did I eat last summer?", "toolhouse_id": "user_1ee7c0de" }'

Scoping (Pro or Business plans only)

If you are on a Pro or Business plan, your Toolhouse ID is further separated by the API Key you use to call the agent. This allows your team to test agents in paraller, or to further separate and control who has access to your agent.

For example, 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:

curl -XPOST "https://agents.toolhouse.ai/$YOUR_AGENT_ID" \
  -H "Authorization: Bearer th-123xxxx567"
  --json '{ "message": "what did I eat last summer?", "toolhouse_id": "alice" }'

# In the following request, the API key changes, so
# the user "alice" will map to a new user
curl -XPOST "https://agents.toolhouse.ai/$YOUR_AGENT_ID" \
  -H "Authorization: Bearer th-654xxxx981"
  --json '{ "message": "what did I eat last summer?", "toolhouse_id": "alice" }'

ID privacy and data protection

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 Toolhouse ID value. 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 the Toolhouse built-in server) to see your actual user IDs. For example, if you pass a user value of [email protected], 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.

In other words, if you are using emails or other values as IDs, hashing makes it safe to pass them to Toolhouse, because neither Toolhouse nor the MCP servers will be able to decode them. Toolhouse will never pass your user IDs to any MCP server, including those built by Toolhouse itself.