OpenAPI docs and fix a lot of issues (#47) #48
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
* 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 * Clarify OpenAPI conversion is optional - Change 'are automatically converted' to 'can be automatically converted' - More accurate description of optional conversion process * Emphasize zero infrastructure requirement - Add 'or additional infrastructure' to OpenAPI compatibility section - Reinforces UTCP's core value proposition of no wrapper tax * Update index.md --------- Co-authored-by: Razvan Radulescu <[email protected]>
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
docs/index.md
Outdated
|
|
||
| ## 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 or additional infrastructure. |
Contributor
There was a problem hiding this comment.
Mentioning gRPC here implies current support, but the Supported Protocols table below does not list gRPC; clarify status or remove gRPC to avoid confusion.
Prompt for AI agents
Address the following comment on docs/index.md at line 33:
<comment>Mentioning gRPC here implies current support, but the Supported Protocols table below does not list gRPC; clarify status or remove gRPC to avoid confusion.</comment>
<file context>
@@ -28,6 +28,10 @@ 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 or additional infrastructure.
+
## Quick Start (5 Minutes)
</file context>
Suggested change
| 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. | |
| 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, WebSocket), and direct execution instructions. Existing OpenAPI specs can be automatically converted to UTCP manuals without requiring API changes or additional infrastructure. |
| Add a discovery endpoint to your existing API: | ||
| **Option A: Discovery via existing OpenAPI spec** | ||
|
|
||
| **Generate OpenAPI endpoint**: `GET http://api.github.com/openapi.json` |
Contributor
There was a problem hiding this comment.
Use HTTPS for the GitHub OpenAPI endpoint to avoid redirects/failures and align with the later example.
Prompt for AI agents
Address the following comment on docs/index.md at line 53:
<comment>Use HTTPS for the GitHub OpenAPI endpoint to avoid redirects/failures and align with the later example.</comment>
<file context>
@@ -44,7 +48,12 @@ npm install @utcp/core @utcp/http
-Add a discovery endpoint to your existing API:
+**Option A: Discovery via existing OpenAPI spec**
+
+**Generate OpenAPI endpoint**: `GET http://api.github.com/openapi.json`
+
+
</file context>
Suggested change
| **Generate OpenAPI endpoint**: `GET http://api.github.com/openapi.json` | |
| **Generate OpenAPI endpoint**: `GET https://api.github.com/openapi.json` |
| "manual_call_templates": [{ | ||
| "name": "github_manual", | ||
| "call_template_type": "text", | ||
| "file_path": "./github_manual.json", |
Contributor
There was a problem hiding this comment.
Trailing comma makes this JSON invalid; remove the comma after the last property.
Prompt for AI agents
Address the following comment on docs/index.md at line 122:
<comment>Trailing comma makes this JSON invalid; remove the comma after the last property.</comment>
<file context>
@@ -72,25 +81,50 @@ Add a discovery endpoint to your existing API:
+ "manual_call_templates": [{
+ "name": "github_manual",
+ "call_template_type": "text",
+ "file_path": "./github_manual.json",
+ }]
+}
</file context>
Suggested change
| "file_path": "./github_manual.json", | |
| "file_path": "./github_manual.json" |
| "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 |
Contributor
There was a problem hiding this comment.
JSON example includes a // comment, which is invalid JSON and will break copy-paste usage; move the note outside the code block or remove it.
Prompt for AI agents
Address the following comment on docs/index.md at line 95:
<comment>JSON example includes a // comment, which is invalid JSON and will break copy-paste usage; move the note outside the code block or remove it.</comment>
<file context>
@@ -72,25 +81,50 @@ Add a discovery endpoint to your existing API:
"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"
}]
</file context>
Suggested change
| "url": "http://localhost:8000/utcp", // Or http://api.github.com/openapi.json, the openapi spec gets converted automatically | |
| "url": "http://localhost:8000/utcp", |
Contributor
|
fyi there seems to be a problem with some markdown code, cfr section below rendered as code inside https://www.utcp.io/ That's it! Your tool is now discoverable and callable by any UTCP client. Key Benefits
How It Worksgraph LR
A[AI Agent] -->|1. Discover| B[UTCP Manual]
B -->|2. Learn| C[Tool Definitions]
A -->|3. Call Directly| D[Your API]
D -->|4. Response| A
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary by cubic
Add OpenAPI compatibility docs that explain UTCP’s agent-focused extensions (tags, average_response_size, multi-protocol, execution hints) and its backward compatibility. Quick Start now shows how to use an OpenAPI endpoint or convert a spec to a UTCP manual, clarifies conversion is optional, and confirms no additional infrastructure is required.