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.

prompt

• Type: String

• Description: The prompt that the agent will use to generate responses. You can use variables in the prompt by wrapping them in curly braces (e.g., {variable_name}). The variables will be replaced with their corresponding values when the agent is executed.

vars

• Type: Dictionary

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

Example:

prompt: "Write a short story about {topic} featuring {name}"
vars:
  topic: "a mysterious island"
  name: "John Doe"

In this example, the prompt is "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 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 '{ "topic": "a space odyssey" }'
# Prompt will be "Write a short story about a space odyssey featuring John Doe"

curl -XPOST "https://agents.toolhouse.ai/$YOUR_AGENT_ID" \
  --json '{ "topic": "a space odyssey", "name": "Philip J. Fry" }'
# Prompt will be "Write a short story about a space odyssey featuring Philip J. Fry"

system_prompt

• Type: String

• Description: The system prompt that sets the context for the agent. Variables are not allowed in the system_prompt. This value is used to provide additional context to the agent.

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.

Scheduling

The final section defines the scheduling configuration for the agent.

schedule

• Type: String (Cron format)

• Description: A cron expression that specifies when the agent should run. For example, "0 0 * * *" would run the agent every day at midnight.

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.

id: $GUID
title: Product Description Generator
prompt: "Write a compelling product description for {product_name} suitable for an e-commerce. 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:
 product_name: "Apple iPhone 14"
 length: "long"
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.

id: $GUID
title: Personalized Marketing Email Generator
prompt: "Write a personalized marketing email to {customer_name} based on their purchase history and preferences. 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: "[e-mail]"
system_prompt: "You are a skilled marketing email writer. Use the customer's data to generate a personalized email."
bundle: "default"
rag: "https://my-internal-api.example.com/purchase-history"
public: false