DiscordGithubAsk the DocsGo to App

Running Agents asynchronously

Toolhouse allows you to deploy agents as an API service. This functionality is called Agent Runs.

Any agent you build in Agent Studio is automatically deployed as an API; this allows you to use your agents in a repeatable way by calling their dedicated API endpoint.

Agent Runs This feature is particularly useful because it allows you to build and deploy agents directly from your application without needing direct access to an AI model or requiring the adoption of additional frameworks and APIs.

When the agent is done, it can optionally send an HTTP request to a URL such as a webhook or a callback you specify.

Agent Runs are equipped with all the default Toolhouse MCP servers. You can optionally specify a bundle to further tailor the functionality of your agent.

IMPORTANT: Agent run uses only the first message of a conversation as the prompt. To ensure proper agent execution, make sure your initial message provides comprehensive instructions and examples.

Creating an Agent Run

  1. Make sure you have your API Key ready. You can see or create an API key in the API Keys page.

  2. Head over to Agent Studio and create a chat. If you're looking for inspiration, you can use this prompt.

  3. Click the Share button, then copy the Chat ID.

Agent tokens are free

All Agents Runs use a premium LLM model. For a limited time, LLM tokens are free, meaning you will not need to worry about cost per token. Your account will only be charged for Toolhouse Execs.

  1. Create an Agent Run using the Agent Runs API:

import requests
import json

def send_request(toolhouse_api_key, chat_id):
    url = "https://api.toolhouse.ai/v1/agent-runs"
    headers = {
        "Authorization": f"Bearer {toolhouse_api_key}",
        "Content-Type": "application/json"
    }

    # Set the JSON payload
    payload = {
        "chat_id": chat_id,
        "vars": {
            "name": "John Doe"
        }
    }

    # Send the POST request
    response = requests.post(url, headers=headers, json=payload)

    return response

# Example usage
if __name__ == "__main__":
    toolhouse_api_key = "YOUR_TOOLHOUSE_API_KEY"
    chat_id = "YOUR_CHAT_ID"

    response = send_request(toolhouse_api_key, chat_id)

    # Check if the request was successful
    if response.status_code == 200:
        print("Request successful. Response:")
        print(response.json())
    else:
        print("Request failed with status code", response.status_code)

Your Agent Run will be queued for execution:

{
  "data": {
    "id": "bcb7e865-9e6c-xxxx-xxxx-c0110fdf5c2e",
    "user_id": "665618fbdeadd84260aa",
    "status": "queued",
    "results": [],
    "created_at": "2025-01-15T01:46:23.568338",
    "updated_at": "2025-01-15T01:46:23.568338",
    "bundle": "default",
    "toolhouse_id": "default"
  }
}

Checking an Agent Run status

Use the Get Agent Runs endpoint to retrive the status of a run.

import requests

TOOLHOUSE_API_KEY = "your_toolhouse_api_key"
YOUR_RUN_ID = "your_run_id_here"  # replace with your actual run ID
url = f"https://api.toolhouse.ai/v1/agent-runs/{YOUR_RUN_ID}"

headers = {
    "Authorization": f"Bearer {TOOLHOUSE_API_KEY}",
    "Content-Type": "application/json"
}
response = requests.get(url, headers=headers)

# Check if the request was successful
if response.status_code == 200:
    print("Request successful. Response:")
    print(response.json())
else:
    print("Request failed with status code", response.status_code, response.text)

You will see the run status and its results. The run status will be one of these values:

Status
Meaning

queued

The Agent Run is being scheduled and will be executed shortly.

in_progress

The agent is currently running and its results are being generated

completed

The Agent Run completed successfully. You will be able to see the results of the run in the results field of the API response.

failed

The Agent Run completed with one or more errors. You will be able to see the errors in the results field of the API response.

This is what a response will look like:

{
  "data": {
    "id": "bcb7e865-9e6c-xxxx-xxxx-c0110fdf5c2e",
    "chat_id": "a3a26d33-6f4d-4490-a56f-e17f867ba451",
    "callback_url": "https://webhooks.example.com/my-webhook",
    "status": "queued",
    "results": [],
    "last_agent_message": null,
    "created_at": "2025-01-15T01:46:23.568338",
    "updated_at": "2025-01-15T01:46:59.270078",
    "bundle": "default",
    "toolhouse_id": "default"
  }
}

Continuing an Agent Run

If an Agent Run completed successfully, you can add further messages to it. This will cause the Agent Run to be queued and start again. The agent will keep its context.

import requests
import json

def send_request(toolhouse_api_key, run_id):
    url = f"https://api.toolhouse.ai/v1/agent-runs/{run_id}"
    headers = {
        "Authorization": f"Bearer {toolhouse_api_key}",
        "Content-Type": "application/json"
    }

    payload = {
        "message": "Perfect, thank you!"
    }

    response = requests.put(url, headers=headers, json=payload)

    return response

# Example usage
if __name__ == "__main__":
    toolhouse_api_key = "YOUR_TOOLHOUSE_API_KEY"
    run_id = "YOUR_RUN_ID"

    response = send_request(toolhouse_api_key, run_id)

    # Check if the request was successful
    if response.status_code == 200:
        print("Request successful. Response:")
        print(response.json())
    else:
        print("Request failed with status code", response.status_code)
PreviousAgent workersNextAPI Reference

Last updated