Build Powerful AI Agents, Faster.

import requests
import json

# Your secure API Key (from Developer Settings)
API_KEY = "ts_sec_..." 

# The structured request from your LLM or application logic
payload = {
  "connection_name": "My-Work-Jira",
  "tool_call": {
    "name": "jira_tool.add_comment",
    "arguments": {
      "task_key": "PROJ-123",
      "body": "The analysis is complete. The results are attached."
    }
  }
}

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

# Make the API call to toolstream.dev
response = requests.post(
    "https://toolstream.dev/v1/tools/execute", 
    headers=headers, 
    data=json.dumps(payload)
)

# Pass the result back to your agent for the next step
tool_result = response.json()
print(tool_result)

Handling User Approvals (Human-in-the-Loop)

For sensitive actions, users can require that a tool execution be verified. When this happens, our API will respond with an HTTP 428 Precondition Required status instead of executing the tool.

Your application must be designed to handle this response, present the details to the user for approval, and then resubmit the request with an approval flag.

Example HITL Workflow

1. Initial Request: Your agent attempts to send an email.

# The is_approved_execution flag is omitted or false by default
payload = {
  "connection_name": "My Gmail",
  "tool_call": {
    "name": "gmail_tool.send_email",
    "arguments": { "recipient": "team@example.com", "subject": "Update", "body": "..." }
  }
}
response = requests.post(...)

2. API Response (428): Because the user has flagged `send_email` for verification, Toolstream returns an error.

# response.status_code will be 428
# response.json() will look like this:
{
  "detail": {
    "error": "Human in the Loop Approval Required",
    "message": "The tool 'gmail_tool.send_email' requires user approval...",
    "tool_call": {
      "name": "gmail_tool.send_email",
      "arguments": { "recipient": "team@example.com", ... }
    },
    "remedy": "Re-submit the request with 'is_approved_execution: true'..."
  }
}

3. Application Logic: Your backend handles the error, shows the `tool_call` from the error response to your user, and gets their confirmation.

if response.status_code == 428:
    error_data = response.json().get("detail", {})
    tool_to_approve = error_data.get("tool_call")
    
    # In your application, you would show this to the user in your UI
    print(f"Please approve this action: {tool_to_approve}")
    user_approval = input("Type 'yes' to approve: ")

    if user_approval.lower() == 'yes':
        # Resubmit with the approval flag
        approved_payload = {
            "connection_name": payload["connection_name"],
            "tool_call": tool_to_approve,
            "is_approved_execution": True  # The crucial flag
        }
        
        final_response = requests.post(
            "https://toolstream.dev/v1/tools/execute",
            headers=headers,
            data=json.dumps(approved_payload)
        )
        print("Action approved and executed:", final_response.json())