UTCP HTTP Plugin
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, any127.0.0.0/8,0.0.0.0,::1or 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/itemswithhost=127.0.0.1is refused, whoever wrote the template. A template may still take its host from an argument for any other destination, and OpenAPI server variables with adefaultare 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}")
Related Documentation
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.