Skip to main content

​
Overview

import { AgentRegistry } from '@frontmcp/sdk';

// Access via scope
const agents = scope.agents;

// List all agents
const allAgents = agents.getAgents();

// Find by ID
const agent = agents.findById('research-agent');

// Get agents as callable tools
const agentTools = agents.getAgentsAsTools();

​
Methods

​
getAgents()

Get all agents (local + adopted). 
getAgents(includeHidden?: boolean): ReadonlyArray<AgentEntry>
ParameterTypeDefaultDescription
includeHiddenbooleanfalseInclude hidden agents
Example: 
const agents = registry.getAgents();
for (const agent of agents) {
  console.log(`Agent: ${agent.id} - ${agent.description}`);
}

​
findById()

Find an agent by its ID. 
findById(id: string): AgentEntry | undefined
Example: 
const agent = registry.findById('research-agent');
if (agent) {
  console.log(`Found: ${agent.name}`);
}

​
findByName()

Find an agent by its name. 
findByName(name: string): AgentEntry | undefined
Example: 
const agent = registry.findByName('research');

​
getVisibleAgentsFor()

Get agents visible to a specific agent. 
getVisibleAgentsFor(agentId: string): ReadonlyArray<AgentEntry>
Example: 
// Get agents that 'orchestrator' can call
const visibleAgents = registry.getVisibleAgentsFor('orchestrator');

​
getAgentsAsTools()

Get tool definitions for all agents. 
getAgentsAsTools(): ReadonlyArray<ToolDefinition>
Agents are automatically registered as tools so they can be called by other agents or the MCP client. Example: 
const agentTools = registry.getAgentsAsTools();
// Each agent becomes a callable tool with its input schema

​
getAgentToolsFor()

Get tool definitions for agents visible to a specific agent. 
getAgentToolsFor(agentId: string): ReadonlyArray<ToolDefinition>
Example: 
// Get tools available to 'coordinator' agent
const tools = registry.getAgentToolsFor('coordinator');

​
getInlineAgents()

Get only agents defined inline in this registry. 
getInlineAgents(): ReadonlyArray<AgentEntry>

​
listAllInstances()

List all agent instances (locals + adopted). 
listAllInstances(): ReadonlyArray<AgentEntry>

​
subscribe()

Subscribe to agent change events. 
subscribe(
  opts: SubscribeOptions,
  cb: (event: AgentChangeEvent) => void
): () => void
Returns: Unsubscribe function. Example: 
const unsubscribe = registry.subscribe({}, (event) => {
  console.log(`Agent ${event.kind}:`, event.entry?.id);
});

// Later
unsubscribe();

​
getCapabilities()

Get MCP capabilities for agents. 
getCapabilities(): { listChanged: boolean }

​
hasAny()

Check if any agents exist. 
hasAny(): boolean

​
adoptFromChild()

Adopt agents from a child registry. 
adoptFromChild(child: AgentRegistry, childOwner: Owner): void

​
removeChild()

Remove a child registry and clean up subscriptions. 
removeChild(child: AgentRegistry): void

​
dispose()

Dispose registry and clean up all child subscriptions. 
dispose(): void

​
Change Events

interface AgentChangeEvent {
  kind: 'added' | 'updated' | 'removed' | 'reset';
  changeScope: 'global' | 'session';
  version: number;
  snapshot: ReadonlyArray<AgentEntry>;
  entry?: AgentEntry;
  sessionId?: string;
  relatedRequestId?: string;
}

​
Indexes

IndexKeyDescription
byQualifiedIdqualifiedIdUnique identifier lookup
byIdidAgent ID lookup (unique to AgentRegistry)
byNamenameBase name lookup
byOwnerownerPathAll agents by owner

​
Agent Visibility

Agents can control which other agents they can see and call: 
@Agent({
  id: 'coordinator',
  name: 'Coordinator',
  description: 'Coordinates research tasks',
  visibleAgents: ['researcher', 'writer'], // Can only call these agents
})
class CoordinatorAgent extends AgentContext { }
Use getVisibleAgentsFor() to query visibility: 
const visible = registry.getVisibleAgentsFor('coordinator');
// Returns only 'researcher' and 'writer' agents

​
Agents as Tools

Agents are automatically registered in the parent scope’s ToolRegistry: 
@Agent({
  id: 'research',
  name: 'Research Agent',
  inputSchema: z.object({
    topic: z.string(),
    depth: z.enum(['shallow', 'deep']),
  }),
})
class ResearchAgent extends AgentContext { }

// The agent becomes callable as a tool
await client.callTool('research', {
  topic: 'AI advancements',
  depth: 'deep',
});