ProtocolHTTP Lifecycle

Handling Requests

Your plugin is just a web server. This guide details the exact JSON payload you will receive and how you should format your response.

1The HTTP Request

When the AI decides to run a tool, it sends a POST request to your plugin's configured URL. By default, this is /execute, but you can customize it per-tool in your manifest.

Incoming Payload
POST /execute
{
  // 1. The Tool Name
  "tool": "create_ticket",

  // 2. The User's Input
  "input": {
    "title": "Fix the printer",
    "priority": "high",
    "email": "bob@acme.com"
  },

  // 3. Metadata Context
  "context": {
    "user": { "id": "U_8f7a..." },
    "org": { "id": "ORG_123" },
    "config": {
       "my_api_key": "sk_live_..."
    }
  }
}

1. Route by Tool Name

Your server handles method dispatch. Switch on the tool field to decide which internal function to run.

2. Validate Input

The input object matches the JSON Schema you defined in your Manifest. Always validate this data before using it.

3. Use Context

The context object gives you the "User ID" (hashed) and any Installation Config (like API keys) needed to talk to external APIs.

2The Response

You must return a 200 OK status with a JSON body. The AI will read the entire JSON response and use it to formulate a reply to the user.

Expected JSON Response
{ // Success! "ticket_id": "TICKET-492", "status": "created", "estimated_time": "4 hours", // You can include raw data objects "assignee": { "name": "Sarah", "role": "Support" } }

Best Practices

POST /execute (default)
Authorization: Bearer <token>
  • Be Verbose: Include details (ID, status, links). The AI is smart; give it context so it can explain things better.
  • No Markdown: Don't format text. Return raw data. Let the AI handle the formatting.
  • Keep it Fast: Responses over 10s will timeout.

3Error Handling

Client Errors (400-499)

Use this when the user's request is invalid (e.g., "User not found"). The AI will read the error message and explain it to the user.

HTTP 404 Not Found
{ "error": "Contact 'bob@acme.com' does not exist." }

Server Errors (500+)

Use this when your system crashes. The AI will apologize to the user and say "The tool failed."

HTTP 500 Internal Server Error
{ "error": "Database connection timeout" }