cmind/agents/v1/preset_agent_service.proto

Package: cmind.agents.v1

Enums

ToolServerKind

Value	Number	Description
TOOL_SERVER_KIND_UNSPECIFIED	0
TOOL_SERVER_KIND_RAG	1
TOOL_SERVER_KIND_MCP	2

PresetAgentAvailability

Stable public readiness state. Raw operator conditions and dependency names are intentionally not exposed by the manager API.

Value	Number	Description
PRESET_AGENT_AVAILABILITY_UNSPECIFIED	0
PRESET_AGENT_AVAILABILITY_RECONCILING	1
PRESET_AGENT_AVAILABILITY_READY	2
PRESET_AGENT_AVAILABILITY_UNAVAILABLE	3

HookKind

Value	Number	Description
HOOK_KIND_UNSPECIFIED	0
HOOK_KIND_MODEL	1

JudgeProtocol

Value	Number	Description
JUDGE_PROTOCOL_UNSPECIFIED	0
JUDGE_PROTOCOL_GPT_OSS_SAFEGUARD	1

ReasoningEffort

Value	Number	Description
REASONING_EFFORT_UNSPECIFIED	0
REASONING_EFFORT_LOW	1
REASONING_EFFORT_MEDIUM	2
REASONING_EFFORT_HIGH	3

PresetAgentAccessFilter

Which access the list is filtered by. A closed enum rather than a relation string, so a caller cannot ask the list to filter by an arbitrary FGA relation.

Value	Number	Description
PRESET_AGENT_ACCESS_FILTER_UNSPECIFIED	0	Treated as INVOCABLE, which is what the list has always returned.
PRESET_AGENT_ACCESS_FILTER_INVOCABLE	1	Agents the caller may use.
PRESET_AGENT_ACCESS_FILTER_MANAGEABLE	2	Agents the caller may administer — the management surface's list. It includes an agent held only through a delegated grant, which is how a member who is not a tenant admin finds the agent they were granted.

Messages

ToolServerRef

Reference to a registered tool server the agent may use — a RAG deployment or an external MCP server, whole-server granularity. Never an inline tool definition or credentials. A per-tool narrowing field can be added later.

Field	Type	Number	Description
kind	ToolServerKind	1	Shape (kind set, name non-empty) is validated by the create and update handlers.
name	string	2	RAG deployment id or external MCP server name

LockedParams

Params the agent pins on every invocation; callers cannot override them. Enforcement happens at invocation in the model-gateway.

Field	Type	Number	Description
temperature	optional double	1
topP	optional double	2
maxOutputTokens	optional int64	3

ModelJudge

Field	Type	Number	Description
modelId	string	1	Public model id; may name a model alias.
judgeProtocol	JudgeProtocol	2
instructions	string	3
reasoningEffort	optional ReasoningEffort	4	Absent means low at invocation; create and update preserve absence.

OutputGuardrail

Output guardrails always keep intermediate output private for the whole request.

Field	Type	Number	Description
kind	HookKind	1
model	ModelJudge	2
blockMessage	string	3	Empty uses the gateway's default replacement message.

PresetAgentHooks

Guardrails run in order and stop after the first block or error.

Field	Type	Number	Description
outputGuardrails	repeated OutputGuardrail	1

PresetAgent

Field	Type	Number	Description
name	string	1	Agent id — what callers put in the model field on /v1/responses. Shares one namespace with model publicModelIds; create rejects collisions. DNS-1123 subdomain shape (no "/"), matching manager-go and K8s validation.
displayName	string	2
baseModel	string	3	publicModelId of the model the agent runs on. Required on create. May name a model alias; the agent then follows the alias when it repoints.
instructions	string	4	System prompt injected on every invocation; callers cannot override it.
toolServers	repeated ToolServerRef	5
lockedParams	LockedParams	6
sharing	cmind.modelmanager.v1.Sharing	7	Mutated by UpdatePresetAgent; this service has no separate sharing RPC
tenantId	string	8	Owning tenant; empty means platform-owned.
availability	PresetAgentAvailability	9
description	string	10	Short human-facing summary of what the agent does. Distinct from instructions (the system prompt), which is machine-directed: this field is for people. May be empty.
hooks	PresetAgentHooks	11

CreatePresetAgentRequest

Field	Type	Number	Description
presetAgent	PresetAgent	1
tenantId	string	2	Tenant that owns the agent

CreatePresetAgentResponse

Field	Type	Number	Description
presetAgent	PresetAgent	1

CreatePlatformPresetAgentRequest

Field	Type	Number	Description
presetAgent	PresetAgent	1

CreatePlatformPresetAgentResponse

Field	Type	Number	Description
presetAgent	PresetAgent	1

GetPresetAgentRequest

Field	Type	Number	Description
name	string	1

GetPresetAgentResponse

Field	Type	Number	Description
presetAgent	PresetAgent	1

ToolServerList

Wraps the repeated refs so PresetAgentUpdate can distinguish absent (unchanged) from present with no values (clear).

Field	Type	Number	Description
values	repeated ToolServerRef	1

PresetAgentUpdate

The fields UpdatePresetAgent can change. An absent field leaves the stored value unchanged; a present field replaces the stored value whole, so a present-but-empty value clears it. Exception: base_model is required and cannot be cleared. Fields not carried here (name, tenant_id) are immutable.

Field	Type	Number	Description
displayName	optional string	1
instructions	optional string	2
baseModel	optional string	3	publicModelId; may name a model alias.
toolServers	ToolServerList	4
lockedParams	LockedParams	5
sharing	cmind.modelmanager.v1.Sharing	6
description	optional string	7	Mirrors PresetAgent.description; an absent field leaves the stored value unchanged, a present field replaces it (empty clears).
hooks	PresetAgentHooks	8	Absent preserves hooks; a present message replaces them, including clearing.

UpdatePresetAgentRequest

Field	Type	Number	Description
name	string	1
update	PresetAgentUpdate	2

UpdatePresetAgentResponse

Field	Type	Number	Description
presetAgent	PresetAgent	1

DeletePresetAgentRequest

Field	Type	Number	Description
name	string	1

DeletePresetAgentResponse

ListPresetAgentsRequest

Field	Type	Number	Description
access	PresetAgentAccessFilter	1	A value outside the enum is rejected with InvalidArgument rather than defaulted, because answering a different question than the caller asked is worse than failing.

PresetAgentSummary

List view for preset agents

Field	Type	Number	Description
name	string	1
displayName	string	2
baseModel	string	3
shareToAll	bool	4
tenantId	string	5	Owning tenant
availability	PresetAgentAvailability	6

ListPresetAgentsResponse

Field	Type	Number	Description
presetAgents	repeated PresetAgentSummary	1

ListPresetAgentPermissionsRequest

Field	Type	Number	Description
name	string	1
subjectType	optional cmind.permissions.v1.SubjectType	2
role	optional cmind.permissions.v1.DeploymentRole	3

ListPresetAgentPermissionsResponse

Field	Type	Number	Description
permissions	repeated cmind.permissions.v1.DeploymentPermission	1

AddPresetAgentPermissionRequest

Field	Type	Number	Description
name	string	1
subject	cmind.permissions.v1.Subject	2
role	cmind.permissions.v1.DeploymentRole	3

AddPresetAgentPermissionResponse

RemovePresetAgentPermissionRequest

Field	Type	Number	Description
name	string	1
subject	cmind.permissions.v1.Subject	2
role	cmind.permissions.v1.DeploymentRole	3

RemovePresetAgentPermissionResponse

GetPresetAgentMcpOAuthMetadataRequest

Field	Type	Number	Description
agentName	string	1
serverName	string	2

GetPresetAgentMcpOAuthMetadataResponse

Field	Type	Number	Description
oauth	ExternalMcpOAuthConfig	1
redirectUri	string	2
metadataVersion	string	3
serverDisplayName	string	4	Human-readable name of the service the caller is connecting to.

ExchangePresetAgentMcpOAuthTokenRequest

Exactly one grant: authorization code or refresh token. The endpoint and client credentials are resolved from the currently pinned MCP resource.

Field	Type	Number	Description
agentName	string	1
serverName	string	2
code	string	3
codeVerifier	string	4
redirectUri	string	5
refreshToken	string	6
metadataVersion	string	7

ExchangePresetAgentMcpOAuthTokenResponse

Field	Type	Number	Description
accessToken	string	1
tokenType	string	2
expiresIn	int64	3
refreshToken	string	4
scope	string	5

Services

PresetAgentService

In FGA, preset agents use the dedicated preset_agent type.

CreatePresetAgent

POST /cmind.agents.v1.PresetAgentService/CreatePresetAgent

Creates a preset agent owned by a tenant

Request: CreatePresetAgentRequest

Response: CreatePresetAgentResponse

CreatePlatformPresetAgent

POST /cmind.agents.v1.PresetAgentService/CreatePlatformPresetAgent

Creates a preset agent owned by the platform

Request: CreatePlatformPresetAgentRequest

Response: CreatePlatformPresetAgentResponse

GetPresetAgent

GET /cmind.agents.v1.PresetAgentService/GetPresetAgent

Request: GetPresetAgentRequest

Response: GetPresetAgentResponse

UpdatePresetAgent

POST /cmind.agents.v1.PresetAgentService/UpdatePresetAgent

Request: UpdatePresetAgentRequest

Response: UpdatePresetAgentResponse

DeletePresetAgent

POST /cmind.agents.v1.PresetAgentService/DeletePresetAgent

Request: DeletePresetAgentRequest

Response: DeletePresetAgentResponse

ListPresetAgents

GET /cmind.agents.v1.PresetAgentService/ListPresetAgents

The handler returns every agent the caller holds the requested access on; see ListPresetAgentsRequest.access

Request: ListPresetAgentsRequest

Response: ListPresetAgentsResponse

ListPresetAgentPermissions

GET /cmind.agents.v1.PresetAgentService/ListPresetAgentPermissions

Request: ListPresetAgentPermissionsRequest

Response: ListPresetAgentPermissionsResponse

AddPresetAgentPermission

POST /cmind.agents.v1.PresetAgentService/AddPresetAgentPermission

Request: AddPresetAgentPermissionRequest

Response: AddPresetAgentPermissionResponse

RemovePresetAgentPermission

POST /cmind.agents.v1.PresetAgentService/RemovePresetAgentPermission

Request: RemovePresetAgentPermissionRequest

Response: RemovePresetAgentPermissionResponse

GetPresetAgentMcpOAuthMetadata

POST /cmind.agents.v1.PresetAgentService/GetPresetAgentMcpOAuthMetadata

Returns OAuth bootstrap metadata for an MCP server pinned by this ready agent. The caller needs access to the agent, not a direct server grant.

Request: GetPresetAgentMcpOAuthMetadataRequest

Response: GetPresetAgentMcpOAuthMetadataResponse

ExchangePresetAgentMcpOAuthToken

POST /cmind.agents.v1.PresetAgentService/ExchangePresetAgentMcpOAuthToken

Exchanges or refreshes a caller-owned OAuth token for an MCP server pinned by this ready agent. The agent and server are re-read for every exchange.

Request: ExchangePresetAgentMcpOAuthTokenRequest

Response: ExchangePresetAgentMcpOAuthTokenResponse