Quick start: deploy your first agent

This guide will show you how to creating and deploy a new agent using the th command line interface.

Initial setup

First, install the Toolhouse CLI:

npm i -g @toolhouseai/cli

The CLI will need a Toolhouse API key. Type th login to automatically get one. This command will open your default browser and ask you to log into Toolhouse or create a new account, if you haven't done so already.

Note: you will only need to run this command once.

th login

Your API Key will be stored in the ~/.toolhouse file.

Other ways to login

As an alternative you can pass an API Key by doing one of these actions:

• Manually create a ~/.toolhouse file and add TOOLHOUSE_API_KEY=(your API Key)

• Set a TOOLHOUSE_API_KEY environment variable with your API Key.

Step 0: Create your th file

You can now create a Toolhouse agent file, or th file for short. A th file is a YAML file containing the setup for your agent. Type th new to create a new agent file:

th new hello.yaml

The CLI will create a hello.yaml file in your current folder.

Step 1: Test your agent

You can test your agent by running it via th run.

th run hello.yaml

Running the agent will show the configuration parameters and will stream any MCP server calls and the final output. You can change the th file and run th run again to see new results.

Once you're happy with the results, you can deploy your agent.

Step 2: Deploy your agent

You can deploy your agent by typing th deploy. You agent will be deployed as an API with its own unique URL:

th deploy hello.yaml

You will receive a URL similar to this:

https://agents.toolhouse.ai/a1d93c2e-7013-4cea-b857-a27980a52ba2

You can simply call your agent as an HTTP POST request, and it will stream the response using the configuration from your th file.

cURL

curl -XPOST https://agents.toolhouse.ai/a1d93c2e-7013-4cea-b857-a27980a52ba2

fetch

// Remember to run npm i fetch-event-stream
import { events, stream } from 'fetch-event-stream';

const agent = 'https://agents.toolhouse.ai/a1d93c2e-7013-4cea-b857-a27980a52ba2';

const abort = new AbortController();
const response = await fetch(agent, { method: 'POST' });

if (response.ok) {
  const stream = events(res, abort.signal);
  for await (let event of stream) {
    process.stdout.write(event.data);
  }
}

httpx

import httpx
import asyncio

agent_url = 'https://agents.toolhouse.ai/a1d93c2e-7013-4cea-b857-a27980a52ba2'

async def main():
    async with httpx.AsyncClient() as client:
        async with client.stream('POST', agent_url) as response:
            if response.status_code == 200:
                async for chunk in response.aiter_bytes():
                    print(chunk.decode(), end='')

asyncio.run(main())

requests

import requests

agent = 'https://agents.toolhouse.ai/a1d93c2e-7013-4cea-b857-a27980a52ba2'

response = requests.post(agent, stream=True)
response.raise_for_status()

for chunk in response.iter_content(decode_unicode=True):
    print(chunk, end='', flush=True)

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.

Learn more