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.
Last updated