Skip to main content

UTCP HTTP Plugin

PyPI Downloads

HTTP communication protocol plugin for UTCP, supporting REST APIs, Server-Sent Events (SSE), and streaming HTTP.

Features

  • HTTP/REST APIs: Full support for GET, POST, PUT, DELETE, PATCH methods
  • Authentication: API key, Basic Auth, OAuth2 support
  • Server-Sent Events (SSE): Real-time event streaming
  • Streaming HTTP: Large response handling with chunked transfer
  • OpenAPI Integration: Automatic tool generation from OpenAPI specs
  • Path Parameters: URL templating with {parameter} syntax
  • Custom Headers: Static and dynamic header support

Installation

pip install utcp-http

Quick Start

from utcp.utcp_client import UtcpClient

# Basic HTTP API
client = await UtcpClient.create(config={
    "manual_call_templates": [{
        "name": "api_service",
        "call_template_type": "http",
        "url": "https://api.example.com/users/{user_id}",
        "http_method": "GET"
    }]
})

result = await client.call_tool("api_service.get_user", {"user_id": "123"})

Configuration Examples

Basic HTTP Request

{
  "name": "my_api",
  "call_template_type": "http",
  "url": "https://api.example.com/data",
  "http_method": "GET"
}

With API Key Authentication

{
  "name": "secure_api",
  "call_template_type": "http",
  "url": "https://api.example.com/data",
  "http_method": "POST",
  "auth": {
    "auth_type": "api_key",
    "api_key": "${API_KEY}",
    "var_name": "X-API-Key",
    "location": "header"
  }
}

OAuth2 Authentication

{
  "name": "oauth_api",
  "call_template_type": "http",
  "url": "https://api.example.com/data",
  "auth": {
    "auth_type": "oauth2",
    "client_id": "${CLIENT_ID}",
    "client_secret": "${CLIENT_SECRET}",
    "token_url": "https://auth.example.com/token"
  }
}

Server-Sent Events (SSE)

{
  "name": "event_stream",
  "call_template_type": "sse",
  "url": "https://api.example.com/events",
  "event_type": "message",
  "reconnect": true
}

Streaming HTTP

{
  "name": "large_data",
  "call_template_type": "streamable_http",
  "url": "https://api.example.com/download",
  "chunk_size": 8192
}

OpenAPI Integration

Automatically generate UTCP tools from OpenAPI specifications:

from utcp_http.openapi_converter import OpenApiConverter

converter = OpenApiConverter()
manual = await converter.convert_openapi_to_manual(
    "https://api.example.com/openapi.json"
)

client = await UtcpClient.create()
await client.register_manual(manual)

Security

Every outbound request must use HTTPS or address a literal loopback host over plain HTTP; plain HTTP to any other host is refused. Loopback is a trust boundary: it exists for local development, so a manual or OpenAPI spec fetched from a remote (non-loopback) origin may not aim requests at the agent's own interface, and nothing that happens later may move a request there.

  • A remote manual or spec may not declare a loopback tool URL, server URL or OAuth2 token_url (http://127.0.0.1:9200/..., https://localhost/token, any 127.0.0.0/8, 0.0.0.0, ::1 or IPv4-mapped spelling).
  • At call time a resolved URL may only be loopback when the call template names a loopback host literally. http://localhost:8080/items/{id} works; http://{host}:8080/items with host=127.0.0.1 is refused, whoever wrote the template. A template may still take its host from an argument for any other destination, and OpenAPI server variables with a default are resolved when a spec is converted.
  • A redirect is never followed into loopback from a non-loopback URL, and the local-dev exemption is judged by the final URL a manual or spec was served from, not the one first requested.

The same rules apply to the HTTP, SSE and Streamable HTTP protocols. The OpenAPI rules can be lifted for a spec you trust: the text call template's base_url (or OpenApiConverter(..., base_url=...) when you drive the converter yourself) replaces the spec's servers with your own choice and is treated as your trust decision for the spec's OAuth token URL as well.

Error Handling

from utcp.exceptions import ToolCallError
import httpx

try:
    result = await client.call_tool("api.get_data", {"id": "123"})
except ToolCallError as e:
    if isinstance(e.__cause__, httpx.HTTPStatusError):
        print(f"HTTP {e.__cause__.response.status_code}: {e.__cause__.response.text}")

Examples

For complete examples, see the UTCP examples repository.

Metadata

Release files for utcp-http 1.1.15

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for utcp-http 1.1.15
File Size Uploaded Provenance Actions
utcp_http-1.1.15.tar.gz 77.3 kB Without provenance Details for utcp_http-1.1.15.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for utcp-http 1.1.15
File Interpreter ABI Platform Actions
utcp_http-1.1.15-py3-none-any.whl Python 3 none any Details for utcp_http-1.1.15-py3-none-any.whl

Total release size: 127.6 kB

Release files / utcp_http-1.1.15.tar.gz

Download URL utcp_http-1.1.15.tar.gz
Size 77.3 kB
Tags Source
SHA-256 checksum
How to use checksums
980fb3417b0f50005b869bd98de8fdaa2fb04f0f9426a89095d9a08c1a67a1d7
BLAKE2b-256 checksum
How to use checksums
d2034e406c396109e0a38f3f00fde8b23a88be08af1ed9e90ac8cecd30b6d048
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.5

Release files / utcp_http-1.1.15-py3-none-any.whl

Download URL utcp_http-1.1.15-py3-none-any.whl
Size 50.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4074110b5304a5e5606d05ecfb778f622129d07e33fca4af7932cbbc4de010eb
BLAKE2b-256 checksum
How to use checksums
e5b822501d514c4377e734440e347bbeaafadd5451ac22781db1542af5ec7871
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.13.5

Security for utcp-http 1.1.15

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page