Build agents with the th file

You can build agents as code using the Toolhouse Agent File, or th file for short. The th file is a YAML file that defines the configuration of an agent deployed on the Toolhouse platform. This file contains essential information about the agent, such as its ID, behavior, and interactions. In this documentation, we will walk you through the different sections of the configuration file, explaining the purpose and usage of each entry.

File Structure

The configuration file is a YAML file that consists of several key-value pairs. The file is divided into sections, each defining a specific aspect of the agent.

Agent ID

The first section of the file defines the agent's ID.

id

• Type: String

• Description: The unique identifier of the agent. This value is automatically generated when creating a new agent. Do not change this value unless you know what you're doing, as it may cause issues with the agent's functionality.

title

• Type: String

• Description: The name of the agent. This value is used for display purposes and can be changed at any time.

Agent Behavior

The next section defines the agent's behavior.

message

• Type: String

• Description: The prompt that the agent will use to generate responses. This value will be used when run the agent autonomously, and it has the role of a user message. When your agent is deployed, you or your end users can dynamically set this value when calling the agent.

system_prompt

• Type: String

• Description: The system prompt that sets the context for the agent.

vars

• Type: Dictionary

• Description: A dictionary of variables used in the system_prompt. You can define default values for these variables. Ensure that the variable names match those used in the system_prompt.

Example:

system_prompt: "Your task is to write a short story about {topic} featuring {name}"
vars:
  topic: "a mysterious island"
  name: "John Doe"

In this example, the system_prompt is set to "Write a short story about {topic} featuring {name}" , which means the vars section must contain topic and name. When running the agent, Toolhouse will compile the system_prompt by replacing the variables with these values:

curl -XPOST "https://agents.toolhouse.ai/$YOUR_AGENT_ID"
# Prompt will be "Write a short story about a mysterious island featuring John Doe"

You can overwrite the value of one or more of your variables by passing values when making an API request to your agent:

curl -XPOST "https://agents.toolhouse.ai/$YOUR_AGENT_ID" \
  --json '{ "vars": {"topic": "a space odyssey"}, "message": "what story do you have for me today?" }'
# System prompt will be "Write a short story about a space odyssey featuring John Doe"

curl -XPOST "https://agents.toolhouse.ai/$YOUR_AGENT_ID" \
  --json '{ "vars": {"topic": "a space odyssey", "name": "Philip J. Fry"}, "message": "what story do you have for me today?" }'
# System prompt will be "Write a short story about a space odyssey featuring Philip J. Fry"

Agent Configuration

The next section defines additional configuration options for the agent.

bundle

• Type: String

• Description: The bundle configuration for the agent. You can specify a bundle name

Example:

bundle: "default"

public

Agents are public on the Free plan

Free plan users can only create public agents.

Pro users can set the visibility of their agents to Private before deploying.

• Type: Boolean

• Default: true

• Description: A flag indicating whether the agent is public or private. Public agents are visible to all users and can be used by anyone. Private agents are only visible to the owner and can only be used when called with the owner's API key. Toolhouse Pro users can create private agents that are not visible to other users.

toolhouse_id

• Type: String

• Description: The end-user ID that provides context about the user interacting with the agent.

MCP - Model Context Protocol

All Toolhouse agents support connecting with HTTP Streamable and SSE remote MCP servers.

mcp_servers

• Type: Array

• Description: A list of one or more MCP server url (must start with https://) that you want your agent to use to perform its duty

Example:

mcp_servers:
  - https://mcp.toolhouse.ai/@toolhouse/supabase?access_token=sbp_192839128319238123bb5416947c1863334ffd61&project_ref=nvbuionbuviobnviuobnvuinvboui

We do not currently support OAuth MCP servers

RAG

The final section defines the RAG folder you want to use for this agent.

rag

• Type: String

• Description: The RAG folder you previously created using the th rag command.

Examples

Here are a few examples of how you can use the Toolhouse Agent Configuration file.

Product Description Generator

This th file will create an agent that searches the web for a particular product. Using the search results, it will generate a compelling product description.

title: Product Description Generator
system_prompt: "You are a brilliant marketer for an e-commerce. Your job it so write a compelling product description for the product the user will give you. This descrpition must suitable for the product detail page of an e-commerce website. Your product description will be based on its features and benefits. Use the results from the web search to inform your response. You should aim to write a {length} description."
vars:
  length: "long"
message: "Write a description for the latest iPhone at https://apple.com/iphone"
bundle: "default"
public: true

Marketing Deep Personalization

This agent reads the purchase history for a specific user to create and send a personalized marketing email.

Based on the prompt, the agent will use RAG to retrieve the purchase history for that specific user identified by its ID. When done, it will prepare the marketing email and send it to the user.

title: Personalized Marketing Email Generator
system_prompt: |-
  You are a skilled marketing email writer. Use the customer's data to generate a personalized email. This is what you need to know about the user:
  Customer ID: {customer_id}
  Name: {customer_name}
  Email: {customer_email}
  
  First, search for {customer_id}'s purchase history in RAG. When done, use the customer's data to inform your response and send the email to {customer_email}.
    
vars:
  customer_id: "6js3ONksv"
  customer_name: "John Doe"
  customer_email: "[email protected]"
 
message: "Write a personalized marketing email to {customer_name}"


bundle: "default"
rag: purchase_history
public: false