agentep

type AgentSvc interface {
	CreateAgent(ctx context.Context, req *CreateAgentRequest) (*apiresource.AgentDefinition, *apierror.APIError)
	ListAgents(ctx context.Context, req *ListAgentsRequest) (*apiresource.List[apiresource.AgentDefinition], *apierror.APIError)
	GetAgent(ctx context.Context, req *RetrieveAgentRequest) (*apiresource.AgentDefinition, *apierror.APIError)
	UpdateAgent(ctx context.Context, req *UpdateAgentRequest) (*apiresource.AgentDefinition, *apierror.APIError)
	DeleteAgent(ctx context.Context, req *DeleteAgentRequest) (*apiresource.EmptyResource, *apierror.APIError)
	UpdateAgentStatus(ctx context.Context, req *UpdateAgentStatusRequest) (*apiresource.AgentDefinition, *apierror.APIError)
}

type AgentSvcConfig struct {
	// AgentClient (required) is the agent-service gRPC client.
	AgentClient pb.AgentServiceClient
}

type ConfigInput struct {
	// Instructions that define the agent's role and how it should behave.
	//
	// Sent to the model on every turn of a run, alongside the platform guidance OpenMRP adds automatically.
	SystemPrompt field.Optional[string] `json:"system_prompt,omitzero"`
	// Intelligence and cost tier for the agent's reasoning.
	//
	// Selects how capable (and how expensive) a model the agent uses without pinning a specific model, so the agent keeps working as the underlying model catalog changes.
	//
	// - `frontier`: the most capable and most expensive; multi-step planning, ambiguous work, tool-heavy workflows.
	// - `high`: normal planning, synthesis, and customer-facing reasoning.
	// - `balanced`: research, summarization, classification, structured extraction, and light tool use.
	// - `cheap`: simple transforms, validation, formatting, keyword lookup, and routing.
	// - `legacy`: older models kept for compatibility and regression comparison; avoid unless you specifically need them.
	Tier field.Optional[constants.ModelTier] `json:"tier,omitzero" default:"high"`
	// How much randomness the model uses when generating text.
	//
	// Lower values make the agent's output more repeatable; higher values make it more varied.
	Temperature field.Optional[float64] `json:"temperature,omitzero" validate:"omitempty,min=0,max=1"`
	// Trigger-specific configuration.
	//
	// Required contents depend on the agent's `trigger_type`; see the trigger config schema.
	TriggerConfig field.Optional[TriggerConfigInput] `json:"trigger_config,omitzero"`
	// API-endpoint tools the agent may discover and use, by slug (e.g. `create_account_group`).
	//
	// These are the tools listed by the List Tools endpoint with category `api_endpoint`. The single entry `*` grants the entire endpoint-tool catalog. Omit or leave empty to grant none.
	EndpointToolSlugs []string `json:"endpoint_tool_slugs,omitzero"`
	// Per-endpoint-tool human-review overrides, keyed by tool slug.
	//
	// Set a slug to `true` to require human approval before the agent may execute that endpoint-tool; the run pauses in `awaiting_approval` until approved via the Continue Agent Run endpoint. Slugs omitted from the map do not require review.
	EndpointToolReview field.Optional[map[string]bool] `json:"endpoint_tool_review,omitzero"`
}

type CreateAgentEndpoint struct{}

type CreateAgentRequest struct {
	// Human-readable name of the agent.
	Name string `json:"name" validate:"required,max=255"`
	// URL-friendly identifier for the agent.
	//
	// Must be unique within your account.
	Slug string `json:"slug" validate:"required,max=255"`
	// Description of what the agent does.
	Description field.Optional[string] `json:"description,omitzero"`
	// Category grouping for the agent (e.g. `order_processing`), used to organize agents in the UI.
	CategoryCode string `json:"category_code" validate:"required,max=255"`
	// How runs of this agent are initiated.
	//
	// - `scheduled`: runs on a cron schedule; `config.trigger_config.cron_schedule` is required.
	// - `event`: runs in response to platform events; at least one `config.trigger_config.event_filters` entry is required.
	// - `manual`: runs only when explicitly invoked.
	// - `chat`: runs when a user messages the agent in a conversation, and the agent's reply is posted back into that conversation.
	//
	// Whatever the trigger type, a run can always be started by hand with the Trigger Agent Run endpoint.
	TriggerType constants.AgentTriggerType `json:"trigger_type" validate:"required"`
	// Agent-level configuration controlling LLM behavior and trigger settings.
	Config ConfigInput `json:"config"`
	// Built-in tools to attach to the agent.
	Tools []ToolInput `json:"tools,omitzero"`
	// ID of the role that defines the permissions the agent operates with.
	//
	// Every API call the agent makes is authorized against this role, so it bounds what the agent can see and change. An agent created without a role cannot execute — its runs fail immediately — so attach one before triggering it.
	RoleID field.Optional[string] `json:"role_id,omitzero" validate:"omitempty,max=191"`
}

type DeleteAgentEndpoint struct{}

type DeleteAgentRequest struct {
	// Agent definition ID.
	AgentDefinitionID string `path:"id" validate:"required"`
}

type ListAgentsEndpoint struct{}

type ListAgentsRequest struct {
	apiresource.PaginationRequest
	// Restricts results to agents with one of the given account-level statuses.
	//
	// `inactive` also matches agents that have never been enabled for your account.
	Status []constants.AgentAccountStatus `query:"statuses"`
	// Restricts results to agents of one of the given definition types.
	DefinitionType []constants.AgentDefinitionType `query:"definition_types"`
	// Restricts results to agents with one of the given trigger types.
	TriggerType []constants.AgentTriggerType `query:"trigger_types"`
}

type RetrieveAgentEndpoint struct{}

type RetrieveAgentRequest struct {
	// ID of the agent definition to retrieve.
	AgentDefinitionID string `path:"id" validate:"required"`
}

type ToolInput struct {
	// The built-in tool to attach.
	//
	// Only OpenMRP's built-in tools are attached here. Access to API-endpoint tools (creating a customer, listing orders, and so on) is granted separately through `config.endpoint_tool_slugs`. The List Tools endpoint (`GET /v1/ai/tools`) returns both kinds, with API-endpoint tools in the `api_endpoint` category.
	Tool constants.Tool `json:"tool" validate:"required"`
	// JSON-encoded configuration for this tool instance.
	//
	// The expected structure depends on the tool (see the tool's `config_schema`).
	ConfigJSON field.Optional[string] `json:"config_json,omitzero"`
	// Display order among the agent's tools (lower values appear first).
	SortOrder field.Optional[int32] `json:"sort_order,omitzero"`
	// Whether actions from this tool require human review before they execute.
	//
	// When review is required, a call to this tool pauses the run in `awaiting_approval` and records an action in `pending_review` until someone approves or rejects it through the Continue Agent Run endpoint. Approvals are one-time, so a later call to the same tool pauses again.
	RequireReview field.Optional[bool] `json:"require_review,omitzero"`
}

type TriggerConfigInput struct {
	// Cron expression for scheduled triggers (e.g. `0 9 * * *`).
	CronSchedule field.Optional[string] `json:"cron_schedule,omitzero" validate:"omitempty,max=255"`
	// IANA timezone for the cron schedule (e.g. `America/New_York`).
	Timezone field.Optional[string] `json:"timezone,omitzero" validate:"omitempty,max=255"`
	// Event types that trigger this agent (e.g. `["email.received", "order.created"]`).
	EventFilters []string `json:"event_filters,omitzero"`
}

type UpdateAgentEndpoint struct{}

type UpdateAgentRequest struct {
	// Agent definition ID.
	AgentDefinitionID string `path:"id" validate:"required"`
	// Human-readable name of the agent.
	Name field.Optional[string] `json:"name,omitzero" validate:"omitempty,max=255"`
	// URL-friendly identifier for the agent.
	Slug field.Optional[string] `json:"slug,omitzero" validate:"omitempty,max=255"`
	// Description of what the agent does.
	//
	// Send `null` to clear the description; omit to leave it unchanged.
	Description field.Clearable[string] `json:"description,omitzero"`
	// Category grouping for the agent (e.g. `order_processing`), used to organize agents in the UI.
	CategoryCode field.Optional[string] `json:"category_code,omitzero" validate:"omitempty,max=255"`
	// How runs of this agent are initiated.
	//
	// When changing the trigger type, also provide a `config` with a `trigger_config` appropriate for the new type (a cron schedule for `scheduled`, at least one event filter for `event`).
	TriggerType field.Optional[constants.AgentTriggerType] `json:"trigger_type,omitzero"`
	// Agent-level configuration controlling LLM behavior and trigger settings.
	//
	// Replaces the stored configuration in full rather than merging into it, so send every setting you want to keep — anything you leave out is cleared.
	Config field.Optional[ConfigInput] `json:"config,omitzero"`
	// Built-in tools to attach to the agent.
	//
	// Replaces the existing tool set when provided.
	Tools field.Optional[[]ToolInput] `json:"tools,omitzero"`
	// ID of the role that defines the permissions the agent operates with.
	//
	// Send `null` to detach the role; omit to leave it unchanged. An agent with no role cannot execute, so detaching the role makes its runs fail immediately.
	RoleID field.Clearable[string] `json:"role_id,omitzero" validate:"omitempty"`
}

type UpdateAgentStatusEndpoint struct{}

type UpdateAgentStatusRequest struct {
	// Agent definition ID.
	AgentDefinitionID string `path:"id" validate:"required"`
	// Account-level status to set for the agent.
	Status constants.AgentAccountStatus `json:"status" validate:"required"`
}