{ "openapi": "3.1.0", "info": { "title": "Osmosis Agent Improvement API", "description": "Improve agentic improvements by learning from past interactions", "version": "1.0.0" }, "security": [ { "ApiKeyAuth": [] } ], "paths": { "/": { "get": { "summary": "Health Check", "description": "Simple health check endpoint.", "operationId": "health_check__get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/enhance_task": { "post": { "tags": [ "agent" ], "summary": "Process Agent Input", "description": "Process agent input, enhance it with relevant past knowledge.\n\nThis endpoint:\n1. Processes the agent's input\n2. Searches for relevant past knowledge\n3. Enhances the response with recommendations\n\nArgs:\n input_data: Agent's input and context with tenant ID (use your API key as the tenant_id)\n agent_type: Optional agent type override\n\nReturns:\n Enhanced response with recommendations\n\nRaises:\n HTTPException: If processing fails", "operationId": "process_agent_input_enhance_task_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentInput", "description": "Agent input data including the query text and context" }, "examples": { "default": { "summary": "Default example", "description": "Use your API key as the tenant_id", "value": { "tenant_id": "YOUR_API_KEY", "input_text": "what is my top trending product selling right now" } } } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnhancedResponse" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/store_knowledge": { "post": { "tags": [ "knowledge" ], "summary": "Store Knowledge", "description": "Store and process agent interaction knowledge asynchronously.\n\nThis endpoint accepts knowledge about agent interactions and queues it for background\nprocessing. The processing pipeline analyzes the interaction, generates insights,\nand stores them for future use.\n\nArgs:\n knowledge: Details about the agent interaction including:\n - tenant_id: Tenant identifier for organization/project\n - query: The user's original query/request\n - turns: List of interaction turns between user and agent\n - success: Whether the interaction achieved the user's goal\n - agent_type: Type of agent that handled the interaction\n - timestamp: When the interaction occurred (ISO format)\n background_tasks: FastAPI background tasks handler for async processing\n\nReturns:\n Dict containing:\n - status: \"accepted\"\n - message: Processing acknowledgement\n - tenant_id: The tenant ID from the request\n\nNotes:\n - Each turn should capture the key decision points and context\n - The memory field helps track the agent's understanding\n - Success should reflect whether the user's goal was achieved\n - Timestamp should be in ISO 8601 format\n - Agent type helps categorize different interaction patterns\n\nRaises:\n HTTPException(500): If there is an error queueing the knowledge", "operationId": "store_knowledge_store_knowledge_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgentKnowledgeUpload", "description": "Agent interaction knowledge to store" }, "examples": { "browser_agent_example": { "summary": "Example of a browser agent interaction", "description": "A successful interaction where a browser agent helps find and purchase a product", "value": { "tenant_id": "webarena", "query": "Find and purchase a red Nike running shoe in size 10", "turns": [ { "turn": 1, "inputs": "On shopping website homepage. Need to search for red Nike running shoes.", "decision": "{'action_type': 'click', 'element_name': 'search_bar', 'text': ['Nike red running shoes'], 'element_role': 'searchbox', 'coords': [120, 35], 'url': 'https://shop.example.com'}", "result": "click [120, 35] where [120, 35] is searchbox 'Search products...' followed by typing 'Nike red running shoes'", "memory": "User wants red Nike running shoes. Starting search from homepage." }, { "turn": 2, "inputs": "Search results show multiple Nike running shoes. Need to select size 10 in red.", "decision": "{'action_type': 'click', 'element_name': 'product_link', 'text': ['Nike Air Zoom Pegasus - Red'], 'element_role': 'link', 'coords': [250, 320], 'url': 'https://shop.example.com/products/nike-air-zoom-pegasus?color=red&size=10'}", "result": "click [250, 320] where [250, 320] is link 'Nike Air Zoom Pegasus - Red' in size 10 with 4.8/5 stars (2,453 reviews)", "memory": "Selected Pegasus model in red, size 10 based on positive reviews and exact match to requirements" } ], "success": "true", "agent_type": "browser", "timestamp": "2024-03-14T10:30:00Z", "metadata": { "browser_type": "chrome", "site": "shopping_admin", "interaction_duration_seconds": 120, "user_satisfaction_score": 0.95 } } } } } }, "required": true }, "responses": { "202": { "description": "Successful Response", "content": { "application/json": { "schema": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Response Store Knowledge Store Knowledge Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/delete_by_intent": { "post": { "tags": [ "knowledge" ], "summary": "Delete By Intent", "description": "Delete documents from the knowledge store based on intent similarity.\n\nThis endpoint:\n1. Takes an intent and tenant_id\n2. Searches for documents with similar intent using the default similarity threshold\n3. Deletes matching documents\n4. Returns the count of deleted documents\n\nArgs:\n tenant_id: The tenant identifier\n intent: The intent to match against\n similarity_threshold: Optional threshold for similarity matching\n\nReturns:\n Dict containing:\n - deleted_count: Number of documents deleted\n - status: Operation status message\n\nRaises:\n HTTPException: If deletion fails", "operationId": "delete_by_intent_delete_by_intent_post", "parameters": [ { "name": "tenant_id", "in": "query", "required": true, "schema": { "type": "string", "title": "Tenant Id" } }, { "name": "intent", "in": "query", "required": true, "schema": { "type": "string", "title": "Intent" } }, { "name": "similarity_threshold", "in": "query", "required": false, "schema": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "description": "Optional similarity threshold for matching documents", "default": 0.5, "title": "Similarity Threshold" }, "description": "Optional similarity threshold for matching documents" } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "title": "Response Delete By Intent Delete By Intent Post" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/knowledge_status/{job_id}": { "get": { "tags": [ "knowledge" ], "summary": "Knowledge Status", "description": "Get the status of a knowledge upload job.\n\nArgs:\n job_id: The job ID for the knowledge upload, passed as path parameter", "operationId": "knowledge_status_knowledge_status__job_id__get", "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "title": "Job Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { "type": "object", "title": "Response Knowledge Status Knowledge Status Job Id Get" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key" } }, "schemas": { "AgentInput": { "properties": { "tenant_id": { "type": "string", "title": "Tenant Id", "description": "Unique identifier that corresponds to a dedicated recommendation collection, enabling sub-tenancy isolation for different agentic workflows" }, "input_text": { "type": "string", "title": "Input Text", "description": "The agent's input/query" }, "context": { "additionalProperties": { "type": "string" }, "type": "object", "title": "Context", "description": "Additional context about the agent's current state" }, "agent_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Type", "description": "Type of agent making the request" } }, "type": "object", "required": [ "tenant_id", "input_text" ], "title": "AgentInput", "description": "Represents an input from an agent that needs to be processed." }, "AgentKnowledgeUpload": { "properties": { "tenant_id": { "type": "string", "title": "Tenant Id", "description": "Unique identifier for the tenant/user" }, "query": { "type": "string", "title": "Query", "description": "The original user query or instruction" }, "turns": { "items": { "$ref": "#/components/schemas/AgentTurn" }, "type": "array", "title": "Turns", "description": "The sequence of agent turns" }, "success": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Success", "description": "Whether the agent completed its task successfully" }, "agent_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Agent Type", "description": "Type of agent (e.g., 'browser', 'voice')" }, "timestamp": { "type": "string", "format": "date-time", "title": "Timestamp" }, "metadata": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Metadata" } }, "type": "object", "required": [ "tenant_id", "query", "turns" ], "title": "AgentKnowledgeUpload", "description": "Represents uploaded knowledge about agent interactions." }, "AgentTurn": { "properties": { "turn": { "type": "integer", "title": "Turn", "description": "The turn number in the interaction" }, "inputs": { "type": "string", "title": "Inputs", "description": "The flattened input the agent sees" }, "decision": { "type": "string", "title": "Decision", "description": "The output/action of the agent" }, "memory": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Memory", "description": "What the agent remembers from this turn" }, "result": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Result", "description": "The result of the action" } }, "type": "object", "required": [ "turn", "inputs", "decision" ], "title": "AgentTurn", "description": "Represents a single turn in an agent's interaction." }, "EnhancedResponse": { "properties": { "response": { "type": "string", "title": "Response", "description": "The processed response" }, "metadata": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "title": "Metadata" } }, "type": "object", "required": [ "response" ], "title": "EnhancedResponse", "description": "Response enhanced with relevant past knowledge." }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } }, "tags": [ { "name": "agent", "description": "Operations for enhancing agent interactions and decisions" }, { "name": "knowledge", "description": "Operations for managing the knowledge base" } ] }