Agent descriptors
The backend keeps stable agent IDs separate from user-facing presentation.
export interface AgentDescriptor {
id: string;
title: string;
description: string;
order: number;
}
AgentBackend.listAgents() remains the compatibility API and returns stable
string IDs.
Backends that support display metadata expose:
listAgentDescriptors?(): Promise<AgentDescriptor[]>;
RestAgentBackend reads both values from GET /agents. The agents controller
prefers descriptors when available, sorts by order with stable response
ordering as a tiebreaker, and derives its compatibility agents list from
descriptor IDs. If a backend does not expose descriptors, the controller
creates fallback descriptors whose title is the ID and whose description is
empty.
Use descriptor title and description for selection UI. Continue using
descriptor id for:
- session creation;
- agent switching;
- session metadata;
- cache keys;
- deep links and interoperability.
Callers that only need IDs can keep using:
await controller.ensureLoaded();
Selection UI can use:
await controller.ensureDescriptorsLoaded();
Effective agent defaults
Backends may also expose a read-only plugin preview:
listAgentPlugins?(agentId: string): Promise<AgentPluginEntry[]>;
RestAgentBackend reads this from
GET /agents/{agent_id}/plugins. Each entry contains only safe plugin
identity/state fields:
- stable plugin ID and kind;
- optional class/name metadata;
- default-enabled state;
- effective active state for the agent's base configuration;
agentorimplicitsource.
Configuration values and credentials are not part of this contract.
AgentsController.ensurePluginsLoaded(agentId) caches the normalized result
per connection cache key and agent ID. Concurrent requests for the same
profile share one in-flight request. invalidateAgentsCache(cacheKey) clears
both descriptor and plugin-preview caches.
The method is optional so clients remain compatible with older or non-HTTP backends. Selection must remain usable when preview support is missing or when a preview request fails.