execute_agent
Execute an agent with a specific goal to activate different behavioral personas for AI assistants, enabling dynamic persona management through the DollhouseMCP server.
Instructions
Execute an agent element with a specific goal
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | The agent name to execute | |
| goal | Yes | The goal for the agent to achieve |
Implementation Reference
- src/server/tools/ElementTools.ts:220-240 (registration)Registration of the 'execute_agent' tool, including input schema, description, and handler that delegates to server.executeAgent(name, goal)
{ tool: { name: "execute_agent", description: "Execute an agent element with a specific goal", inputSchema: { type: "object", properties: { name: { type: "string", description: "The agent name to execute", }, goal: { type: "string", description: "The goal for the agent to achieve", }, }, required: ["name", "goal"], }, }, handler: (args: ExecuteAgentArgs) => server.executeAgent(args.name, args.goal) }, - TypeScript interface defining the input arguments for the execute_agent tool
interface ExecuteAgentArgs { name: string; goal: string; } - src/server/types.ts:31-31 (schema)Interface definition for the server's executeAgent method called by the tool handler
executeAgent(name: string, goal: string): Promise<any>; - getElementTools function that returns the array of element tools including execute_agent, which gets registered in ServerSetup
export function getElementTools(server: IToolHandler): Array<{ tool: ToolDefinition; handler: any }> { return [ { tool: { name: "list_elements", description: "List all available elements of a specific type", inputSchema: { type: "object", properties: { type: { type: "string", description: "The element type to list", enum: Object.values(ElementType), }, }, required: ["type"], }, }, handler: (args: ListElementsArgs) => server.listElements(args.type) }, { tool: { name: "activate_element", description: "Activate a specific element by name", inputSchema: { type: "object", properties: { name: { type: "string", description: "The element name to activate", }, type: { type: "string", description: "The element type", enum: Object.values(ElementType), }, }, required: ["name", "type"], }, }, handler: (args: ActivateElementArgs) => server.activateElement(args.name, args.type) }, { tool: { name: "get_active_elements", description: "Get information about currently active elements of a specific type", inputSchema: { type: "object", properties: { type: { type: "string", description: "The element type to check", enum: Object.values(ElementType), }, }, required: ["type"], }, }, handler: (args: GetActiveElementsArgs) => server.getActiveElements(args.type) }, { tool: { name: "deactivate_element", description: "Deactivate a specific element", inputSchema: { type: "object", properties: { name: { type: "string", description: "The element name to deactivate", }, type: { type: "string", description: "The element type", enum: Object.values(ElementType), }, }, required: ["name", "type"], }, }, handler: (args: DeactivateElementArgs) => server.deactivateElement(args.name, args.type) }, { tool: { name: "get_element_details", description: "Get detailed information about a specific element", inputSchema: { type: "object", properties: { name: { type: "string", description: "The element name to get details for", }, type: { type: "string", description: "The element type", enum: Object.values(ElementType), }, }, required: ["name", "type"], }, }, handler: (args: GetElementDetailsArgs) => server.getElementDetails(args.name, args.type) }, { tool: { name: "reload_elements", description: "Reload elements of a specific type from the filesystem", inputSchema: { type: "object", properties: { type: { type: "string", description: "The element type to reload", enum: Object.values(ElementType), }, }, required: ["type"], }, }, handler: (args: ReloadElementsArgs) => server.reloadElements(args.type) }, // Element-specific tools { tool: { name: "render_template", description: "Render a template element with provided variables", inputSchema: { type: "object", properties: { name: { type: "string", description: "The template name to render", }, variables: { type: "object", description: "Variables to use in the template", additionalProperties: true, }, }, required: ["name", "variables"], }, }, handler: (args: RenderTemplateArgs) => server.renderTemplate(args.name, args.variables) }, { tool: { name: "execute_agent", description: "Execute an agent element with a specific goal", inputSchema: { type: "object", properties: { name: { type: "string", description: "The agent name to execute", }, goal: { type: "string", description: "The goal for the agent to achieve", }, }, required: ["name", "goal"], }, }, handler: (args: ExecuteAgentArgs) => server.executeAgent(args.name, args.goal) }, // Generic element creation tool { tool: { name: "create_element", description: "Create a new element of any type", inputSchema: { type: "object", properties: { name: { type: "string", description: "The element name", }, type: { type: "string", description: "The element type", enum: Object.values(ElementType), }, description: { type: "string", description: "Element description", }, content: { type: "string", description: "Element content (required for some types)", }, metadata: { type: "object", description: "Additional metadata specific to element type", additionalProperties: true, }, }, required: ["name", "type", "description"], }, }, handler: (args: CreateElementArgs) => server.createElement(args) }, // Generic element editing tool { tool: { name: "edit_element", description: "Edit an existing element of any type", inputSchema: { type: "object", properties: { name: { type: "string", description: "The element name to edit", }, type: { type: "string", description: "The element type", enum: Object.values(ElementType), }, field: { type: "string", description: "The field to edit (e.g., 'description', 'metadata.author', 'content')", }, value: { description: "The new value for the field", oneOf: [ { type: "string" }, { type: "number" }, { type: "boolean" }, { type: "object" }, { type: "array" }, ], }, }, required: ["name", "type", "field", "value"], }, }, handler: (args: EditElementArgs) => server.editElement(args) }, // Generic element validation tool { tool: { name: "validate_element", description: "Validate an element for correctness and best practices", inputSchema: { type: "object", properties: { name: { type: "string", description: "The element name to validate", }, type: { type: "string", description: "The element type", enum: Object.values(ElementType), }, strict: { type: "boolean", description: "Whether to apply strict validation rules", default: false, }, }, required: ["name", "type"], }, }, handler: (args: ValidateElementArgs) => server.validateElement(args) }, // Generic element deletion tool { tool: { name: "delete_element", description: "Delete an element and optionally its associated data files", inputSchema: { type: "object", properties: { name: { type: "string", description: "The element name to delete", }, type: { type: "string", description: "The element type", enum: Object.values(ElementType), }, deleteData: { type: "boolean", description: "Whether to delete associated data files (if not specified, will prompt)", default: undefined, }, }, required: ["name", "type"], }, }, handler: (args: DeleteElementArgs) => server.deleteElement(args) }, ]; } - src/server/ServerSetup.ts:51-87 (registration)Registration of element tools (including execute_agent) into the ToolRegistry during server setup
private registerTools(instance: IToolHandler): void { // Register element tools (new generic tools for all element types) this.toolRegistry.registerMany(getElementTools(instance)); // Register persona export/import tools (core functionality moved to element tools) this.toolRegistry.registerMany(getPersonaExportImportTools(instance)); // Register collection tools this.toolRegistry.registerMany(getCollectionTools(instance)); // DEPRECATED: Old user tools - replaced by dollhouse_config // Comment out to remove from tool list, but keep for reference during transition // this.toolRegistry.registerMany(getUserTools(instance)); // Register auth tools this.toolRegistry.registerMany(getAuthTools(instance)); // Portfolio tools (including sync_portfolio with new safety features) this.toolRegistry.registerMany(getPortfolioTools(instance)); // DEPRECATED: Old config tools - replaced by dollhouse_config // Comment out to remove from tool list, but keep for reference during transition // this.toolRegistry.registerMany(getConfigTools(instance)); // Register new unified config and sync tools this.toolRegistry.registerMany(getConfigToolsV2(instance)); // Register build info tools this.toolRegistry.registerMany(getBuildInfoTools(instance)); // Register Enhanced Index tools (semantic search and relationships) this.toolRegistry.registerMany(getEnhancedIndexTools(instance)); // Invalidate cache since tools have changed this.toolCache.invalidateToolList(); logger.debug('ToolDiscoveryCache: Cache invalidated due to tool registration'); }