Workers API

Each worker can be called as an API. The API endpoint is formatted as https://agents.toolhouse.ai/$AGENT_ID, where $AGENT_ID is a unique GUID assigned to your worker. You must authenticate your request with your API Key.

You can create an API Key in the API Keys page.

Calling your worker

You can call your worker by simply making a POST request towards its endpoint.

curl -XPOST \
  https://agents.toolhouse.ai/$AGENT_ID \
  -H 'Authorization: Bearer YOUR_TOOLHOUSE_API_KEY'
  --json '{"message": "Book at meeting over lunch with Jessica."}'

Handling the response from the worker

The agent will stream its response as NDJSON. You will be able to see both the agent's output and the tool calls.

The response headers will contain a X-Toolhouse-Run-ID header containing a unique ID for the execution run. You can use this value to continue the interaction with your worker. You can think of this ID as an identifier of the current context including the initial message, any tool call, and the response from the worker.

Continuing an interaction with an agent

The X-Toolhouse-Run-ID header returned in the initial response from the POST call will allow you to continue the interaction with this worker while keeping a reference of the current context. Using a Run ID is particularly useful for conversational workers, because it allows them to retain all the content and history from previous messages.

To continue a conversation, you can use the Run ID in a PUT request to the same agent endpoint.

# Initial request to execute the worker, assuming $AGENT_ID finds pro
curl -XPOST https://agents.toolhouse.ai/$AGENT_ID \
  -v -H 'Authorization: Bearer YOUR_TOOLHOUSE_API_KEY' \ 
# Headers will contain x-toolhouse-run-id: $RUN_ID
# Worker will stream the response

# Continuing the conversation using the X-Toolhouse-Run-ID
curl -XPUT https://agents.toolhouse.ai/$AGENT_ID/$RUN_ID \
-H 'Authorization: Bearer YOUR_TOOLHOUSE_API_KEY' \
--json '{
  "message": "thank you, now find products similar to an iPhone"
}'
# Headers will contain x-toolhouse-run-id: $RUN_ID
# Agent will stream a new response using the current context

The PUT request will also send a X-Toolhouse-Run-ID header containing the run ID for subsequent requests.