From 7b8b548485a5949facaf497cf31abb368e36c501 Mon Sep 17 00:00:00 2001 From: Gary Date: Wed, 27 Nov 2024 22:12:29 +0800 Subject: [PATCH] feat(agent): add agent contract (#523) Because we are going to remove the app-related api This commit adds api for agent --------- Co-authored-by: droplet-bot --- app/app/v1alpha/agent.proto | 109 +++++++- app/app/v1alpha/app_public_service.proto | 89 ++++++- app/app/v1alpha/conversation.proto | 8 +- openapi/v2/service.swagger.yaml | 302 +++++++++++++++++++++-- 4 files changed, 472 insertions(+), 36 deletions(-) diff --git a/app/app/v1alpha/agent.proto b/app/app/v1alpha/agent.proto index c3653228..8feea8a8 100644 --- a/app/app/v1alpha/agent.proto +++ b/app/app/v1alpha/agent.proto @@ -4,7 +4,29 @@ package app.app.v1alpha; // Google API import "google/api/field_behavior.proto"; -import "google/protobuf/struct.proto"; +import "google/protobuf/timestamp.proto"; + +// Agent represents a agent. +message Agent { + // agent uid + string agent_uid = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; + // The agent display name. + string display_name = 2 [(google.api.field_behavior) = REQUIRED]; + // The agent description. + string description = 3 [(google.api.field_behavior) = OPTIONAL]; + // The namespace of the agent. + string namespace_uid = 4 [(google.api.field_behavior) = OUTPUT_ONLY]; + // The agent tags. + repeated string tags = 5 [(google.api.field_behavior) = OPTIONAL]; + // The agent metadata. + AIAgentAppMetadata ai_agent_metadata = 6 [(google.api.field_behavior) = OUTPUT_ONLY]; + // creator uid + string creator_uid = 7 [(google.api.field_behavior) = OUTPUT_ONLY]; + // The creation time of the agent. + google.protobuf.Timestamp create_time = 8 [(google.api.field_behavior) = OUTPUT_ONLY]; + // The last update time of the agent. + google.protobuf.Timestamp update_time = 9 [(google.api.field_behavior) = OUTPUT_ONLY]; +} // AIAgentAppMetadata represents the metadata for the AI agent app. message AIAgentAppMetadata { @@ -22,8 +44,85 @@ message AIAgentAppMetadata { // tool definitions message Tool { - // The tool name. e.g. ["preset/pipeline@v1.0.0", "preset/pipeline-2@v2.0.0"]. - string name = 1 [(google.api.field_behavior) = REQUIRED]; - // The tool config - google.protobuf.Struct config = 3 [(google.api.field_behavior) = OPTIONAL]; + // The pipeline id of the tool. e.g. "preset/xxx-search" + string pipeline_id = 1 [(google.api.field_behavior) = OPTIONAL]; + // The tool name. + optional string name = 2 [(google.api.field_behavior) = OPTIONAL]; + // The tool connection key(variable) and value(id). + map config = 3 [(google.api.field_behavior) = OPTIONAL]; +} + +// CreateAgentRequest represents a request to create a agent. +message CreateAgentRequest { + // The app's owner(namespaces). + string namespace_id = 1 [(google.api.field_behavior) = REQUIRED]; + // The agent display name. + string display_name = 2 [(google.api.field_behavior) = OPTIONAL]; + // The agent description. + string description = 3 [(google.api.field_behavior) = OPTIONAL]; + // The agent tags. + repeated string tags = 4 [(google.api.field_behavior) = OPTIONAL]; + // The agent metadata. + AIAgentAppMetadata ai_agent_app = 5 [(google.api.field_behavior) = OPTIONAL]; +} + +// CreateAgentResponse represents a response for creating a agent. +message CreateAgentResponse { + // The created agent. + Agent agent = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; +} + +// ListAgentsRequest represents a request to list agents. +message ListAgentsRequest { + // The app's owner(namespaces). + string namespace_id = 1 [(google.api.field_behavior) = REQUIRED]; +} + +// ListAgentsResponse represents a response for listing agents. +message ListAgentsResponse { + // The agents. + repeated Agent agents = 1; +} + +// UpdateAgentRequest represents a request to update a agent. +message UpdateAgentRequest { + // The app's owner(namespaces). + string namespace_id = 1 [(google.api.field_behavior) = REQUIRED]; + // The agent uid. + string agent_uid = 2 [(google.api.field_behavior) = REQUIRED]; + // The agent description. + string description = 3 [(google.api.field_behavior) = OPTIONAL]; + // The agent tags. + repeated string tags = 4 [(google.api.field_behavior) = OPTIONAL]; + // The agent metadata. + AIAgentAppMetadata ai_agent_app = 5 [(google.api.field_behavior) = OPTIONAL]; +} + +// UpdateAgentResponse represents a response for updating a agent. +message UpdateAgentResponse { + // The updated agent. + Agent agent = 1 [(google.api.field_behavior) = OUTPUT_ONLY]; +} + +// DeleteAgentRequest represents a request to delete a agent. +message DeleteAgentRequest { + // The app's owner(namespaces). + string namespace_id = 1 [(google.api.field_behavior) = REQUIRED]; + // The agent uid. + string agent_uid = 2 [(google.api.field_behavior) = REQUIRED]; +} + +// DeleteAgentResponse represents a response for deleting a agent. +message DeleteAgentResponse {} + +// ListToolsRequest represents a request to list tools. +message ListToolsRequest { + // The app's owner(namespaces). + string namespace_id = 1 [(google.api.field_behavior) = REQUIRED]; +} + +// ListToolsResponse represents a response for listing tools. +message ListToolsResponse { + // The tools. + repeated Tool tools = 1; } diff --git a/app/app/v1alpha/app_public_service.proto b/app/app/v1alpha/app_public_service.proto index 7a30cdf6..86674a36 100644 --- a/app/app/v1alpha/app_public_service.proto +++ b/app/app/v1alpha/app_public_service.proto @@ -2,6 +2,7 @@ syntax = "proto3"; package app.app.v1alpha; +import "app/app/v1alpha/agent.proto"; // App definitions import "app/app/v1alpha/app.proto"; import "app/app/v1alpha/conversation.proto"; @@ -71,7 +72,7 @@ service AppPublicService { }; } - // Update a app info + // Update an app's information // // Updates the information of an app. rpc UpdateApp(UpdateAppRequest) returns (UpdateAppResponse) { @@ -88,7 +89,7 @@ service AppPublicService { }; } - // Delete a app + // Delete an app // // Deletes an app. rpc DeleteApp(DeleteAppRequest) returns (DeleteAppResponse) { @@ -164,6 +165,68 @@ service AppPublicService { }; } + // Create an agent + // + // Creates an agent. + rpc CreateAgent(CreateAgentRequest) returns (CreateAgentResponse) { + option (google.api.http) = { + post: "/v1alpha/namespaces/{namespace_id}/agents" + body: "*" + }; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "🍎 App" + extensions: { + key: "x-stage" + value: {string_value: "alpha"} + } + }; + } + + // List all agents info + // + // Returns a paginated list of agents. + rpc ListAgents(ListAgentsRequest) returns (ListAgentsResponse) { + option (google.api.http) = {get: "/v1alpha/namespaces/{namespace_id}/agents"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "🍎 App" + extensions: { + key: "x-stage" + value: {string_value: "alpha"} + } + }; + } + + // Update an agent + // + // Updates the information of an agent. + rpc UpdateAgent(UpdateAgentRequest) returns (UpdateAgentResponse) { + option (google.api.http) = { + put: "/v1alpha/namespaces/{namespace_id}/agents/{agent_uid}" + body: "*" + }; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "🍎 App" + extensions: { + key: "x-stage" + value: {string_value: "alpha"} + } + }; + } + + // Delete an agent + // + // Deletes an agent. + rpc DeleteAgent(DeleteAgentRequest) returns (DeleteAgentResponse) { + option (google.api.http) = {delete: "/v1alpha/namespaces/{namespace_id}/agents/{agent_uid}"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "🍎 App" + extensions: { + key: "x-stage" + value: {string_value: "alpha"} + } + }; + } + // Create a chat // // Creates a chat. @@ -183,7 +246,7 @@ service AppPublicService { // List chats // - // Returns a paginated list of conversations. + // Returns a list of chats. rpc ListChats(ListChatsRequest) returns (ListChatsResponse) { option (google.api.http) = {get: "/v1alpha/namespaces/{namespace_id}/chats"}; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { @@ -290,7 +353,7 @@ service AppPublicService { // Get Playground Conversation // - // Returns the latest conversation of auth user(e.g. login user and api key user). + // Returns the latest conversation for the authenticated user (e.g., logged-in user or API key user). rpc GetPlaygroundConversation(GetPlaygroundConversationRequest) returns (GetPlaygroundConversationResponse) { option (google.api.http) = {get: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}/ai_assistant_playground/conversation"}; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { @@ -302,6 +365,20 @@ service AppPublicService { }; } + // List all tools + // + // Returns a list of tools. + rpc ListTools(ListToolsRequest) returns (ListToolsResponse) { + option (google.api.http) = {get: "/v1alpha/namespaces/{namespace_id}/tools"}; + option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { + tags: "🍎 App" + extensions: { + key: "x-stage" + value: {string_value: "alpha"} + } + }; + } + // List chat messages // // Returns a paginated list of messages. @@ -318,8 +395,8 @@ service AppPublicService { // Restart Playground Conversation // - // Creates a new conversation and uses the auth user UID as creator UID and - // auto-generates a new conversation ID on the behalf of auth user. + // Creates a new conversation using the authenticated user's UID as creator and + // auto-generates a new conversation ID on behalf of the authenticated user. rpc RestartPlaygroundConversation(RestartPlaygroundConversationRequest) returns (RestartPlaygroundConversationResponse) { option (google.api.http) = {post: "/v1alpha/namespaces/{namespace_id}/apps/{app_id}/ai_assistant_playground/restart"}; option (grpc.gateway.protoc_gen_openapiv2.options.openapiv2_operation) = { diff --git a/app/app/v1alpha/conversation.proto b/app/app/v1alpha/conversation.proto index b38fbbd6..e9fc5269 100644 --- a/app/app/v1alpha/conversation.proto +++ b/app/app/v1alpha/conversation.proto @@ -47,7 +47,7 @@ message Chat { // update time of the chat google.protobuf.Timestamp update_time = 7 [(google.api.field_behavior) = OUTPUT_ONLY]; // agent metadata - AIAgentAppMetadata ai_agent_app = 8 [(google.api.field_behavior) = OUTPUT_ONLY]; + AIAgentAppMetadata ai_agent_metadata = 8 [(google.api.field_behavior) = OUTPUT_ONLY]; // temp catalog id automatically created for ai agent app optional string temp_catalog_id = 9 [(google.api.field_behavior) = OPTIONAL]; // conversation display name @@ -197,10 +197,6 @@ message UpdateConversationRequest { optional string last_used_catalog_uid = 5 [(google.api.field_behavior) = OPTIONAL]; // last used top k(only for ai assistant app) optional uint32 last_used_top_k = 6 [(google.api.field_behavior) = OPTIONAL]; - // ai agent app metadata - AIAgentAppMetadata ai_agent_app = 7 [(google.api.field_behavior) = OPTIONAL]; - // conversation display name - string conversation_display_name = 8 [(google.api.field_behavior) = OPTIONAL]; } // UpdateConversationResponse returns the updated conversation @@ -218,7 +214,7 @@ message UpdateChatRequest { // chat display name string chat_display_name = 3 [(google.api.field_behavior) = OPTIONAL]; // ai agent app metadata - AIAgentAppMetadata ai_agent_app = 4 [(google.api.field_behavior) = OPTIONAL]; + AIAgentAppMetadata ai_agent_metadata = 4 [(google.api.field_behavior) = OPTIONAL]; } // UpdateChatResponse returns the updated chat diff --git a/openapi/v2/service.swagger.yaml b/openapi/v2/service.swagger.yaml index 92c4bc13..448150d0 100644 --- a/openapi/v2/service.swagger.yaml +++ b/openapi/v2/service.swagger.yaml @@ -105,7 +105,7 @@ paths: x-stage: alpha /v1alpha/namespaces/{namespaceId}/apps/{appId}: delete: - summary: Delete a app + summary: Delete an app description: Deletes an app. operationId: AppPublicService_DeleteApp responses: @@ -135,7 +135,7 @@ paths: - "\U0001F34E App" x-stage: alpha put: - summary: Update a app info + summary: Update an app's information description: Updates the information of an app. operationId: AppPublicService_UpdateApp responses: @@ -339,10 +339,132 @@ paths: tags: - "\U0001F34E App" x-stage: alpha + /v1alpha/namespaces/{namespaceId}/agents: + get: + summary: List all agents info + description: Returns a paginated list of agents. + operationId: AppPublicService_ListAgents + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/ListAgentsResponse' + "401": + description: Returned when the client credentials are not valid. + schema: {} + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/rpc.Status' + parameters: + - name: namespaceId + description: The app's owner(namespaces). + in: path + required: true + type: string + tags: + - "\U0001F34E App" + x-stage: alpha + post: + summary: Create an agent + description: Creates an agent. + operationId: AppPublicService_CreateAgent + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/CreateAgentResponse' + "401": + description: Returned when the client credentials are not valid. + schema: {} + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/rpc.Status' + parameters: + - name: namespaceId + description: The app's owner(namespaces). + in: path + required: true + type: string + - name: body + in: body + required: true + schema: + $ref: '#/definitions/CreateAgentBody' + tags: + - "\U0001F34E App" + x-stage: alpha + /v1alpha/namespaces/{namespaceId}/agents/{agentUid}: + delete: + summary: Delete an agent + description: Deletes an agent. + operationId: AppPublicService_DeleteAgent + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/DeleteAgentResponse' + "401": + description: Returned when the client credentials are not valid. + schema: {} + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/rpc.Status' + parameters: + - name: namespaceId + description: The app's owner(namespaces). + in: path + required: true + type: string + - name: agentUid + description: The agent uid. + in: path + required: true + type: string + tags: + - "\U0001F34E App" + x-stage: alpha + put: + summary: Update an agent + description: Updates the information of an agent. + operationId: AppPublicService_UpdateAgent + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/UpdateAgentResponse' + "401": + description: Returned when the client credentials are not valid. + schema: {} + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/rpc.Status' + parameters: + - name: namespaceId + description: The app's owner(namespaces). + in: path + required: true + type: string + - name: agentUid + description: The agent uid. + in: path + required: true + type: string + - name: body + in: body + required: true + schema: + $ref: '#/definitions/UpdateAgentBody' + tags: + - "\U0001F34E App" + x-stage: alpha /v1alpha/namespaces/{namespaceId}/chats: get: summary: List chats - description: Returns a paginated list of conversations. + description: Returns a list of chats. operationId: AppPublicService_ListChats responses: "200": @@ -681,7 +803,7 @@ paths: /v1alpha/namespaces/{namespaceId}/apps/{appId}/ai_assistant_playground/conversation: get: summary: Get Playground Conversation - description: Returns the latest conversation of auth user(e.g. login user and api key user). + description: Returns the latest conversation for the authenticated user (e.g., logged-in user or API key user). operationId: AppPublicService_GetPlaygroundConversation responses: "200": @@ -709,6 +831,32 @@ paths: tags: - "\U0001F34E App" x-stage: alpha + /v1alpha/namespaces/{namespaceId}/tools: + get: + summary: List all tools + description: Returns a list of tools. + operationId: AppPublicService_ListTools + responses: + "200": + description: A successful response. + schema: + $ref: '#/definitions/ListToolsResponse' + "401": + description: Returned when the client credentials are not valid. + schema: {} + default: + description: An unexpected error response. + schema: + $ref: '#/definitions/rpc.Status' + parameters: + - name: namespaceId + description: The app's owner(namespaces). + in: path + required: true + type: string + tags: + - "\U0001F34E App" + x-stage: alpha /v1alpha/namespaces/{namespaceId}/chats/{chatUid}/messages: get: summary: List chat messages @@ -760,8 +908,8 @@ paths: post: summary: Restart Playground Conversation description: |- - Creates a new conversation and uses the auth user UID as creator UID and - auto-generates a new conversation ID on the behalf of auth user. + Creates a new conversation using the authenticated user's UID as creator and + auto-generates a new conversation ID on behalf of the authenticated user. operationId: AppPublicService_RestartPlaygroundConversation responses: "200": @@ -5491,6 +5639,50 @@ definitions: required: - catalogUid - topK + Agent: + type: object + properties: + agentUid: + type: string + title: agent uid + readOnly: true + displayName: + type: string + description: The agent display name. + description: + type: string + description: The agent description. + namespaceUid: + type: string + description: The namespace of the agent. + readOnly: true + tags: + type: array + items: + type: string + description: The agent tags. + aiAgentMetadata: + description: The agent metadata. + readOnly: true + allOf: + - $ref: '#/definitions/AIAgentAppMetadata' + creatorUid: + type: string + title: creator uid + readOnly: true + createTime: + type: string + format: date-time + description: The creation time of the agent. + readOnly: true + updateTime: + type: string + format: date-time + description: The last update time of the agent. + readOnly: true + description: Agent represents a agent. + required: + - displayName Any: type: object properties: @@ -6604,6 +6796,34 @@ definitions: - namespaceId - appId - id + CreateAgentBody: + type: object + properties: + displayName: + type: string + description: The agent display name. + description: + type: string + description: The agent description. + tags: + type: array + items: + type: string + description: The agent tags. + aiAgentApp: + description: The agent metadata. + allOf: + - $ref: '#/definitions/AIAgentAppMetadata' + description: CreateAgentRequest represents a request to create a agent. + CreateAgentResponse: + type: object + properties: + agent: + description: The created agent. + readOnly: true + allOf: + - $ref: '#/definitions/Agent' + description: CreateAgentResponse represents a response for creating a agent. CreateAppBody: type: object properties: @@ -6852,6 +7072,9 @@ definitions: description: |- DataSpecification describes the JSON schema of component input and output. Note: This message will be renamed to TaskSpecifications in the future. + DeleteAgentResponse: + type: object + description: DeleteAgentResponse represents a response for deleting a agent. DeleteAppResponse: type: object description: DeleteAppResponse represents a response for deleting a app. @@ -7576,6 +7799,16 @@ definitions: description: URL contains the reference the link will redirect to. readOnly: true description: Link contains the information to display an reference to an external URL. + ListAgentsResponse: + type: object + properties: + agents: + type: array + items: + type: object + $ref: '#/definitions/Agent' + description: The agents. + description: ListAgentsResponse represents a response for listing agents. ListAppsResponse: type: object properties: @@ -8335,6 +8568,16 @@ definitions: format: int32 description: Total number of API token resources. description: ListTokensResponse contains a list of API tokens. + ListToolsResponse: + type: object + properties: + tools: + type: array + items: + type: object + $ref: '#/definitions/Tool' + description: The tools. + description: ListToolsResponse represents a response for listing tools. ListUserMembershipsResponse: type: object properties: @@ -9967,15 +10210,18 @@ definitions: Tool: type: object properties: + pipelineId: + type: string + title: The pipeline id of the tool. e.g. "preset/xxx-search" name: type: string - description: The tool name. e.g. ["preset/pipeline@v1.0.0", "preset/pipeline-2@v2.0.0"]. + description: The tool name. config: type: object - title: The tool config + additionalProperties: + type: string + description: The tool connection key(variable) and value(id). title: tool definitions - required: - - name Trace: type: object properties: @@ -10349,6 +10595,31 @@ definitions: UndeployUserModelAdminResponse: type: object title: UndeployUserModelAdminResponse represents a response for a undeployed model + UpdateAgentBody: + type: object + properties: + description: + type: string + description: The agent description. + tags: + type: array + items: + type: string + description: The agent tags. + aiAgentApp: + description: The agent metadata. + allOf: + - $ref: '#/definitions/AIAgentAppMetadata' + description: UpdateAgentRequest represents a request to update a agent. + UpdateAgentResponse: + type: object + properties: + agent: + description: The updated agent. + readOnly: true + allOf: + - $ref: '#/definitions/Agent' + description: UpdateAgentResponse represents a response for updating a agent. UpdateAppBody: type: object properties: @@ -10424,7 +10695,7 @@ definitions: chatDisplayName: type: string title: chat display name - aiAgentApp: + aiAgentMetadata: title: ai agent app metadata allOf: - $ref: '#/definitions/AIAgentAppMetadata' @@ -10466,13 +10737,6 @@ definitions: type: integer format: int64 title: last used top k(only for ai assistant app) - aiAgentApp: - title: ai agent app metadata - allOf: - - $ref: '#/definitions/AIAgentAppMetadata' - conversationDisplayName: - type: string - title: conversation display name title: UpdateConversationRequest is used to update a conversation UpdateConversationResponse: type: object @@ -10939,7 +11203,7 @@ definitions: format: date-time title: update time of the chat readOnly: true - aiAgentApp: + aiAgentMetadata: title: agent metadata readOnly: true allOf: