From b2b8cfb108f50105ba5d475b725b7fecd68785f9 Mon Sep 17 00:00:00 2001 From: Luca Perrozzi Date: Sun, 7 Sep 2025 21:54:52 +0000 Subject: [PATCH 1/4] Add OpenAPI compatibility documentation - Add OpenAPI compatibility section explaining UTCP as agent-focused extension - Include minimal OpenAPI ingestion example in Quick Start - Position information early in documentation for better user understanding --- docs/index.md | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 2355a3e..c8300d9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -28,6 +28,10 @@ UTCP acts as a **"manual"** that tells agents how to call your tools directly: *"If a human can call your API, an AI agent should be able to call it too - with the same security and no additional infrastructure."* ::: +## OpenAPI Compatibility + +UTCP extends OpenAPI for AI agents while maintaining full backward compatibility. Where OpenAPI describes APIs for human developers, UTCP adds agent-focused enhancements: `tags` for categorization, `average_response_size` for resource planning, multi-protocol support (CLI, gRPC, WebSocket), and direct execution instructions. Existing OpenAPI specs are automatically converted to UTCP manuals without requiring API changes. + ## Quick Start (5 Minutes) ### 1. Install UTCP @@ -44,7 +48,16 @@ npm install @utcp/core @utcp/http ### 2. Expose Your First Tool -Add a discovery endpoint to your existing API: +**Option A: From existing OpenAPI spec** +```python +from utcp_http.openapi_converter import OpenApiConverter + +converter = OpenApiConverter.from_url("https://api.example.com/openapi.json") +manual = converter.convert() +# Your OpenAPI spec is now a UTCP manual with agent-friendly metadata +``` + +**Option B: Add a discovery endpoint to your existing API** **Add endpoint**: `GET /utcp` **Return your UTCP manual**: From 8c15ca80d82b65b44d7f32ee990e6112f6d8caf4 Mon Sep 17 00:00:00 2001 From: Luca Perrozzi Date: Sun, 7 Sep 2025 21:58:39 +0000 Subject: [PATCH 2/4] Clarify OpenAPI conversion is optional - Change 'are automatically converted' to 'can be automatically converted' - More accurate description of optional conversion process --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index c8300d9..7a6094d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -30,7 +30,7 @@ UTCP acts as a **"manual"** that tells agents how to call your tools directly: ## OpenAPI Compatibility -UTCP extends OpenAPI for AI agents while maintaining full backward compatibility. Where OpenAPI describes APIs for human developers, UTCP adds agent-focused enhancements: `tags` for categorization, `average_response_size` for resource planning, multi-protocol support (CLI, gRPC, WebSocket), and direct execution instructions. Existing OpenAPI specs are automatically converted to UTCP manuals without requiring API changes. +UTCP extends OpenAPI for AI agents while maintaining full backward compatibility. Where OpenAPI describes APIs for human developers, UTCP adds agent-focused enhancements: `tags` for categorization, `average_response_size` for resource planning, multi-protocol support (CLI, gRPC, WebSocket), and direct execution instructions. Existing OpenAPI specs can be automatically converted to UTCP manuals without requiring API changes. ## Quick Start (5 Minutes) From e819b569d1e4d67847b37963cd935d5a41fff95a Mon Sep 17 00:00:00 2001 From: Luca Perrozzi Date: Sun, 7 Sep 2025 22:00:17 +0000 Subject: [PATCH 3/4] Emphasize zero infrastructure requirement - Add 'or additional infrastructure' to OpenAPI compatibility section - Reinforces UTCP's core value proposition of no wrapper tax --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index 7a6094d..9f209c5 100644 --- a/docs/index.md +++ b/docs/index.md @@ -30,7 +30,7 @@ UTCP acts as a **"manual"** that tells agents how to call your tools directly: ## OpenAPI Compatibility -UTCP extends OpenAPI for AI agents while maintaining full backward compatibility. Where OpenAPI describes APIs for human developers, UTCP adds agent-focused enhancements: `tags` for categorization, `average_response_size` for resource planning, multi-protocol support (CLI, gRPC, WebSocket), and direct execution instructions. Existing OpenAPI specs can be automatically converted to UTCP manuals without requiring API changes. +UTCP extends OpenAPI for AI agents while maintaining full backward compatibility. Where OpenAPI describes APIs for human developers, UTCP adds agent-focused enhancements: `tags` for categorization, `average_response_size` for resource planning, multi-protocol support (CLI, gRPC, WebSocket), and direct execution instructions. Existing OpenAPI specs can be automatically converted to UTCP manuals without requiring API changes or additional infrastructure. ## Quick Start (5 Minutes) From a3bf9c6d85de33b44c933fabf4d0f320e8f2b8db Mon Sep 17 00:00:00 2001 From: Razvan Radulescu <43811028+h3xxit@users.noreply.github.com> Date: Mon, 8 Sep 2025 13:31:18 +0200 Subject: [PATCH 4/4] Update index.md --- docs/index.md | 43 ++++++++++++++++++++++++++++++++----------- 1 file changed, 32 insertions(+), 11 deletions(-) diff --git a/docs/index.md b/docs/index.md index 9f209c5..9f0da6a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -48,14 +48,10 @@ npm install @utcp/core @utcp/http ### 2. Expose Your First Tool -**Option A: From existing OpenAPI spec** -```python -from utcp_http.openapi_converter import OpenApiConverter +**Option A: Discovery via existing OpenAPI spec** + +**Generate OpenAPI endpoint**: `GET http://api.github.com/openapi.json` -converter = OpenApiConverter.from_url("https://api.example.com/openapi.json") -manual = converter.convert() -# Your OpenAPI spec is now a UTCP manual with agent-friendly metadata -``` **Option B: Add a discovery endpoint to your existing API** @@ -85,25 +81,50 @@ manual = converter.convert() "var_name": "appid", "location": "query" } - } - }] } ``` ### 3. Call Your Tool -**Configure UTCP client**: +**Option A: Configure UTCP client**: ```json { "manual_call_templates": [{ "name": "weather_api", "call_template_type": "http", - "url": "http://localhost:8000/utcp", + "url": "http://localhost:8000/utcp", // Or http://api.github.com/openapi.json, the openapi spec gets converted automatically "http_method": "GET" }] } ``` +**Option B: Convert OpenAPI spec to UTCP manual manually** + +```python +async def convert_api(): + async with aiohttp.ClientSession() as session: + async with session.get("https://api.github.com/openapi.json") as response: + openapi_spec = await response.json() + + converter = OpenApiConverter(openapi_spec) + manual = converter.convert() + + print(f"Generated {len(manual.tools)} tools from GitHub API!") + return manual +``` + +Then save that to a text file and load it with the text configuration: +```json +{ + "manual_call_templates": [{ + "name": "github_manual", + "call_template_type": "text", + "file_path": "./github_manual.json", + }] +} +``` + + **Call the tool**: 1. Initialize UTCP client with configuration 2. Discover tools from weather API