🏠
Toolhouse
DiscordGithubSign upGo to App
  • 🏠Toolhouse
  • Quick start: deploy your first agent
  • Build agents with the th file
  • Test agents before deploying
  • Deploy and run your agents
  • Using RAG
  • Build stateful agents
  • Agent workers
    • Running Agents asynchronously
      • API Reference
    • Schedule autonomous runs
      • API Reference
  • Choose MCP servers for your agent
  • Customize agents for your end users
  • Go to app
  • Toolhouse Platform: walkthrough
    • Agent Studio
      • Variables
Powered by GitBook
On this page
  • Overview
  • Resources

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

PreviousUsing RAGNextAgent workers

Last updated 1 day ago

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

: 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.

Toolhouse Help
Stateful agent boilerplate