Toolhouse AI Agent icon

Toolhouse AI Agent

Send and continue conversations with Toolhouse agent
Join our community

Actions2

Overview

This node integrates with Toolhouse AI agents to either start a new conversation or continue an existing one. It is useful for automating interactions with AI agents deployed on the Toolhouse platform, enabling workflows that require conversational AI capabilities such as customer support bots, virtual assistants, or interactive tools.

Typical use cases include:

  • Starting a fresh conversation with a selected AI agent by sending an initial message.
  • Continuing an ongoing conversation by providing a run ID and sending follow-up messages, maintaining context across multiple interactions.

For example, you could automate a customer support chat where each user session corresponds to a run ID, allowing the bot to remember previous messages and provide coherent responses.

Properties

Name Meaning
Agent Name or ID Select a Toolhouse AI agent from a list or specify its ID. Agents can be public or private.
Message The text message to send to the selected Toolhouse agent.
Run ID (Only for "Continue Conversation" operation) The identifier of the existing conversation to continue.

The Agent Name or ID property supports loading available agents dynamically and checking whether the selected agent is public or private.

The Operation property (not listed in your JSON but present in code) lets you choose between:

  • Start Conversation
  • Continue Conversation

Output

The node outputs two main data streams:

  1. Main output (index 0): Contains successful responses from the Toolhouse API. Each item has a json object with:

    • response: The full response body from the Toolhouse agent, typically including the agent's reply.
    • runId: The current conversation run ID, which is important for continuing conversations.
    • agentId: The ID of the agent used.
    • public: Boolean indicating if the agent is public (true) or private (false).

  2. Error output (index 1): Contains error information when requests fail, structured as:

    • json.error.message: Error message string.
    • json.error.status: HTTP status code.
    • json.error.details: Additional error details if available.
    • json.runId: Usually empty on errors.
    • json.agentId: The agent ID involved.
    • json.public: Boolean indicating agent visibility.

If the node encounters a 403 error due to access restrictions on a private agent, it returns a specific error message indicating lack of access.

No binary data output is produced by this node.

Dependencies

  • Requires an API authentication token credential for Toolhouse API access.
  • The node makes HTTP requests to:
    • https://api.toolhouse.ai/v1/agents to fetch agent metadata.
    • https://agents.toolhouse.ai/{agentId} endpoints to start or continue conversations.
  • Proper configuration of the API key credential in n8n is necessary for the node to function.
  • The node uses built-in n8n helper methods for authenticated HTTP requests.

Troubleshooting

  • Missing or invalid API credentials: The node throws an error if the Toolhouse API token is not configured or invalid. Ensure the API key credential is set up correctly.
  • Access denied (403) errors: Occur when trying to interact with a private agent without proper permissions. The node returns a clear error message: "You do not have access to this private agent." To resolve, verify your API token has rights to the private agent or select a public agent.
  • Invalid agent ID: If the specified agent ID does not exist or is malformed, the node will throw an error during the GET request to fetch agent info.
  • Run ID issues: For continuing conversations, providing an incorrect or expired run ID may cause errors or unexpected behavior.
  • Network or API downtime: Standard HTTP errors may occur; check network connectivity and Toolhouse service status.

Links and References

Discussion