// M-Files Server gRPC API 26.11. Generated from the M-Files Server IDL; do not edit.
// Documentation: https://developer.m-files.com/APIs/gRPC-API/
syntax = "proto3";

package MFiles;

import "mfiles/api/annotations.proto";

option csharp_namespace = "MFiles.Grpc";
option go_package = "github.com/M-Files/mfiles-grpc-api/go/mfiles;mfiles";
option java_multiple_files = true;
option java_package = "com.mfiles.grpc";
option objc_class_prefix = "MF_";

// Connects M-Files clients to the Aino agents of M-Files Cloud.
//
// The M-Files clients use this service for Aino features. The server forwards each request to
// the Aino agent service on behalf of the session's user and returns the agent's answer. The
// payloads are text documents in formats defined by the M-Files clients and the agent service,
// and they change with them; applications should not depend on them.
//
// - [AgentCreateSummarization](mfiles:MFiles.IRPCAgent.AgentCreateSummarization): a summary of a
//   set of objects.
// - [CreateAgentResponse](mfiles:MFiles.IRPCAgent.CreateAgentResponse): one turn with the
//   general Aino agent.
// - [CallAgentApiV2](mfiles:MFiles.IRPCAgent.CallAgentApiV2): a call to version 2 of the agent
//   service API.
//
// Prerequisites: a vault session of a user, and a vault whose subscription includes Aino; without
// it the calls fail with "Your current subscription does not include the specified feature.".
// Methods that are not available on the server fail with "Not implemented.". When the agent
// service cannot be reached, or fails, the call fails with "Aino agent request failed." (or "Aino
// Summarization failed."); the details are only in the server log.
service IRPCAgent {
	option (mfiles.api.service) = { book: "vault" level: LEVEL_STANDARD title: "Aino agents" };

	// Creates an Aino summary of a set of objects. Used by M-Files clients; the request and response
	// formats are internal to them.
	//
	// - Requires a vault session of a user and a vault where Aino summarization is available.
	// - The server checks that the caller can read every object named in the request; if not, the
	//   call fails and nothing is sent to the agent.
	// - Same operation as [CreateSummarization](mfiles:MFiles.IRPCSearch.CreateSummarization).
	rpc AgentCreateSummarization( AgentRequest ) returns ( AgentResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Sends one turn to the general Aino agent and returns its answer. Used by M-Files clients; the
	// request and response formats are internal to them.
	//
	// - Requires a vault session of a user and a vault whose subscription includes Aino.
	// - The server forwards the request as given and returns the agent's answer unchanged.
	rpc CreateAgentResponse( CreateAgentResponseRequest ) returns ( CreateAgentResponseResponse ) {
		option idempotency_level = IDEMPOTENT;
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}

	// Calls version 2 of the Aino agent service API for the session's user and returns the HTTP
	// status and body. A temporary bridge for M-Files clients that cannot call the agent service
	// directly; it will be deprecated when they can.
	//
	// - Requires a vault session of a user and a vault whose subscription includes Aino.
	// - The server fixes the API version, the subscription and the vault (the session's). The
	//   request gives only the path below the vault, the HTTP method and the body.
	// - `path` may contain only letters, digits, `.`, `_`, `~`, `-` and `/`, with no empty, `.` or
	//   `..` segments; there is no query string. `method` may be GET, POST (the default), PUT, PATCH
	//   or DELETE. Other values fail with "The parameter is incorrect.".
	// - `parameters` must be empty or a JSON object. The server adds its own member
	//   `_mfserverData` to it (information about the user and the vault that the agent service needs)
	//   and drops any member of that name, in any letter case, that the caller sent.
	// - Every HTTP answer, including error statuses, is returned as a successful call with `status`
	//   and `data`; check `status`. Only a failure to reach the agent service fails the call.
	// - Not idempotent: a call can start an agent turn.
	rpc CallAgentApiV2( AgentApiV2Request ) returns ( AgentApiV2Response ) {
		option (mfiles.api.method) = { session: SESSION_REQUIREMENT_SESSION returns_metadata_structure_version: true };
	}
}

// A request to an Aino agent.
message AgentRequest {

	// The request document, in a format internal to the M-Files clients.
	string data = 1;
}

// The answer of an Aino agent.
message AgentResponse {

	// The answer document, in a format internal to the M-Files clients.
	string data = 1;
}

// The request of CreateAgentResponse.
message CreateAgentResponseRequest {

	// The request document, in a format internal to the M-Files clients.
	AgentRequest agent_request = 1;
}

// The response of CreateAgentResponse.
message CreateAgentResponseResponse {

	// The agent's answer.
	AgentResponse agent_response = 1;
}

// The request of CallAgentApiV2.
message AgentApiV2Request {

	// The HTTP method: GET, POST, PUT, PATCH or DELETE. Empty means POST.
	string method = 1;

	// The API path below the vault, for example `conversations`. Without the API version, the vault or a query string.
	string path = 2;

	// The request body, a JSON object, or empty for an empty object.
	string parameters = 3;

	// True to let the agent service call back to the vault as the session's user. Fails with "Not implemented." on servers that do not support it.
	bool allow_delegation = 4;
}

// The response of CallAgentApiV2.
message AgentApiV2Response {

	// The HTTP status code that the agent service returned.
	int32 status = 1;

	// The response body as returned by the agent service; empty when it had none.
	string data = 2;
}