Build stateful agents

Stateful Agents automatically maintain persistent conversation context across multiple interactions without requiring external database configuration. Each conversation is assigned a unique run ID that preserves the complete interaction history, including user messages, agent responses, and MCP server calls.

Overview

By default, all Toolhouse agents are stateful and start with a clear context. New POST agent call to https://agents.toolhouse.ai/{YOUR_AGENT_ID} will start a new interaction between the agent and the user. Each call will return an X-Toolhouse-Run-ID header that will identify the state ID. You can of this X-Toolhouse-Run-ID as a session ID:

curl -v -XPOST https://agents.toolhouse.ai/{YOUR_AGENT_ID}
... curl output ...
< x-toolhouse-run-id: 92fa77db-507e-4c16-9a6d-06fb69eb1caf

¿Sobre qué tema te gustaría hablar hoy?

From now on, you can reference the Run ID in a PUT call to keep adding user messages to the conversation:

curl -XPUT https://agents.toolhouse.ai/{YOUR_AGENT_ID}/{RUN_ID} \
  --json '{ "message": "no sé, puedes escoger tu un tema para esta conversación?" }'
  
¿Hablamos de inteligencia artificial?

At any point, you can get the full history of the conversation through a GET request:

curl -GET https://agents.toolhouse.ai/{YOUR_AGENT_ID}/{RUN_ID}
[
  { "role": "user", "content": "Hola" },
  { "role": "assistant", "content": "¿Sobre qué tema te gustaría hablar hoy?" },
  { "role": "user", "content": "no sé, puedes escoger tu un tema para esta conversación?" },
  { "role": "assistant", "content": "¿Hablamos de inteligencia artificial?" }
]

Resources

• Toolhouse Help: our "talk to your docs" implementation leverages a Toolhouse stateful agents with no storage or database.

• Stateful agent boilerplate: this boilerplate contains a UX complete with all the logic to initiate and continue a stateful conversation with an agent. This code powers our Toolhouse Help Agent.