Oshara Docs

Overview

HTTP tools let the agent call an external REST endpoint. The agent constructs the call arguments based on the conversation, the worker executes an HTTP request, and the JSON response is returned to the LLM as tool output.

Tool definition


{
  "name": "ticket_lookup",
  "kind": "http",
  "description": "Look up a support ticket by ID. Returns status, priority, and last update.",
  "input_schema": {
    "type": "object",
    "properties": {
      "ticket_id": {
        "type": "string",
        "description": "Ticket ID, e.g. TICKET-123"
      }
    },
    "required": ["ticket_id"]
  },
  "config": {
    "url": "https://api.yoursite.com/tickets/lookup",
    "method": "POST",
    "timeout_seconds": 10,
    "headers": {
      "Authorization": "Bearer your-service-token",
      "X-Tenant": "acme"
    }
  }
}

`config` reference

Field	Type	Default	Description
`url`	string	—	Required. Full URL of the endpoint to call.
`method`	`"POST"` \| `"GET"` \| `"PUT"` \| `"PATCH"`	`"POST"`	HTTP method.
`timeout_seconds`	number	`10`	Request timeout. Calls exceeding this are aborted and the LLM receives an error.
`headers`	object	`{}`	Static headers included with every call (e.g. auth tokens, tenant IDs).

Request contract

The worker sends the LLM’s tool arguments as a JSON body (for POST/PUT/PATCH) or as query parameters (for GET).

Example POST request sent by the worker:


POST https://api.yoursite.com/tickets/lookup
Content-Type: application/json
Authorization: Bearer your-service-token
 
{
  "ticket_id": "TICKET-123"
}

Example GET request:


GET https://api.yoursite.com/tickets/lookup?ticket_id=TICKET-123
Authorization: Bearer your-service-token

Response contract

Your endpoint should return JSON. The entire response body is returned to the LLM as tool output, truncated to max_tool_output_chars (default 16 000 chars).


{
  "ticket_id": "TICKET-123",
  "status": "open",
  "priority": "high",
  "subject": "Login not working",
  "last_update": "2025-06-09T11:30:00Z",
  "assigned_to": "alice@support.acme.com"
}

Return any 2xx status. Non-2xx responses are treated as errors; the LLM receives a message saying the tool call failed.

Authentication patterns

Bearer token (static)


{
  "headers": { "Authorization": "Bearer sk-your-token" }
}

API key header


{
  "headers": { "X-API-Key": "your-api-key" }
}

Per-session headers (via mcp_headers override)

For tokens that change per user, pass them at session start via the mcp_headers field (these are merged into all HTTP and MCP tool calls for that session):


POST /api/agents/agent-session/
{
  "agent": "support-bot",
  "mcp_headers": {
    "X-User-Token": "user-jwt-here"
  }
}

Example: weather lookup (GET)


{
  "name": "get_weather",
  "kind": "http",
  "description": "Get current weather for a city. Use when the user asks about weather.",
  "input_schema": {
    "type": "object",
    "properties": {
      "city": { "type": "string", "description": "City name, e.g. London" }
    },
    "required": ["city"]
  },
  "config": {
    "url": "https://api.weatherapi.com/v1/current.json",
    "method": "GET",
    "headers": { "key": "your-weatherapi-key" }
  }
}

Example: CRM lead creation (POST)


{
  "name": "create_lead",
  "kind": "http",
  "description": "Create a new CRM lead after the user expresses interest in purchasing.",
  "input_schema": {
    "type": "object",
    "properties": {
      "name":    { "type": "string" },
      "email":   { "type": "string" },
      "company": { "type": "string" },
      "notes":   { "type": "string", "description": "Summary of the conversation" }
    },
    "required": ["name", "email"]
  },
  "config": {
    "url": "https://crm.yoursite.com/api/leads",
    "method": "POST",
    "timeout_seconds": 15,
    "headers": {
      "Authorization": "Bearer crm-service-token"
    }
  }
}