plazbot-cli 0.4.1 → 0.5.0

package/dist/commands/agent/tools.js

@@ -3,14 +3,247 @@ import { Agent } from 'plazbot';
 import inquirer from 'inquirer';
 import { getStoredCredentials } from '../../utils/credentials.js';
 import { logger } from '../../utils/logger.js';
-import { addExamples } from '../../utils/help.js';
+import { addExamples, addNotes } from '../../utils/help.js';
+import { describeAgentLoadError } from '../../utils/agent-errors.js';
 import { createSpinner, createTable, theme, section, kvPair, statusBadge } from '../../utils/ui.js';
+import { jsonOption, isJsonMode, printJson, fail, CliError } from '../../utils/output.js';
+import { confirmAction, requireInteractive } from '../../utils/confirm.js';
+// ---------------------------------------------------------------------------
+// Shared tool definitions (wizard.ts reuses these prompts).
+// Action values match the front (SectionUIEdition.tsx) and the engine.
+// ---------------------------------------------------------------------------
+// Same list as the agent schema the API validates (Plazbot-Back-v2/Schemas/agent.config.schema.json)
+export const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+export const ACTION_TYPES = [
+    { group: 'Contact', value: 'action.asign', label: 'Assign agent', valueHint: 'agent user ID or email' },
+    { group: 'Contact', value: 'action.unassign', label: 'Unassign agent' },
+    { group: 'Contact', value: 'action.stage', label: 'Set stage', valueHint: 'stage ID' },
+    { group: 'Contact', value: 'action.stage.remove', label: 'Remove stage' },
+    { group: 'Contact', value: 'action.segmentation', label: 'Set segmentation', valueHint: 'segmentation ID' },
+    { group: 'Contact', value: 'action.segmentation.remove', label: 'Remove segmentation' },
+    { group: 'Contact', value: 'action.tag', label: 'Add tag', valueHint: 'tag ID' },
+    { group: 'Contact', value: 'action.tag.remove', label: 'Remove tag', valueHint: 'tag ID' },
+    { group: 'Contact', value: 'action.solved', label: 'Mark chat as resolved' },
+    { group: 'Contact', value: 'action.agentShutDown', label: 'Hand off to human agent (turns the AI agent off)' },
+    { group: 'Contact', value: 'action.secuence', label: 'Assign sequence', valueHint: 'sequence ID' },
+    { group: 'Contact', value: 'action.worker', label: 'Run worker', valueHint: 'worker ID' },
+    { group: 'Events', value: 'action.event.add', label: 'Schedule event' },
+    { group: 'Events', value: 'action.event.update', label: 'Reschedule event' },
+    { group: 'Events', value: 'action.event.delete', label: 'Delete event' },
+    { group: 'Events', value: 'action.event.list', label: 'List events' },
+    { group: 'Events', value: 'action.event.confirm', label: 'Confirm event' },
+    { group: 'Events', value: 'action.event.cancel', label: 'Cancel event' },
+    { group: 'Files', value: 'action.send.image', label: 'Send image', valueHint: 'image URL' },
+    { group: 'Files', value: 'action.send.file', label: 'Send file', valueHint: 'file URL' },
+];
+export function actionLabel(type) {
+    return ACTION_TYPES.find(a => a.value === type)?.label || type;
+}
+const FIELD_TYPES = ['string', 'number', 'integer', 'boolean', 'date', 'datetime', 'email', 'phone'];
+const required = (label) => (v) => (v && v.trim().length > 0) || `${label} is required`;
+function validateUrl(v) {
+    try {
+        const u = new URL(v.trim());
+        return (u.protocol === 'http:' || u.protocol === 'https:') || 'Use an http(s) URL';
+    }
+    catch {
+        return 'Enter a valid URL (e.g. https://api.example.com/orders/{{orderId}})';
+    }
+}
+async function promptRequiredFields() {
+    const fields = [];
+    const { addFields } = await inquirer.prompt([{
+            type: 'confirm', name: 'addFields',
+            message: 'Add required fields (data the agent must collect from the user first)?', default: false,
+        }]);
+    let more = addFields;
+    while (more) {
+        const field = await inquirer.prompt([
+            { type: 'input', name: 'name', message: 'Field name (e.g. orderId):', validate: required('Field name') },
+            { type: 'list', name: 'type', message: 'Type:', choices: FIELD_TYPES },
+            { type: 'input', name: 'description', message: 'Description:', default: '' },
+            { type: 'input', name: 'promptHint', message: 'Hint for the AI (how to ask for it):', default: '' },
+        ]);
+        fields.push({ ...field, name: field.name.trim() });
+        ({ more } = await inquirer.prompt([{ type: 'confirm', name: 'more', message: 'Add another field?', default: false }]));
+    }
+    return fields;
+}
+async function promptHeaders() {
+    const headers = {};
+    const { addHeaders } = await inquirer.prompt([{
+            type: 'confirm', name: 'addHeaders', message: 'Add HTTP headers (e.g. Authorization)?', default: false,
+        }]);
+    if (!addHeaders)
+        return headers;
+    while (true) {
+        const { name } = await inquirer.prompt([{ type: 'input', name: 'name', message: 'Header name (leave empty to finish):' }]);
+        if (!name.trim())
+            break;
+        const { value } = await inquirer.prompt([{ type: 'input', name: 'value', message: `Value for ${name.trim()}:`, validate: required('Value') }]);
+        headers[name.trim()] = value;
+    }
+    return headers;
+}
+async function promptBodyTemplate() {
+    const { body } = await inquirer.prompt([{
+            type: 'input',
+            name: 'body',
+            message: 'JSON body template (use {{fieldName}} for required fields; leave empty for none):',
+            default: '',
+            validate: (v) => {
+                if (!v.trim())
+                    return true;
+                try {
+                    const parsed = JSON.parse(v);
+                    return (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) || 'The body must be a JSON object, e.g. {"orderId":"{{orderId}}"}';
+                }
+                catch (e) {
+                    return `Invalid JSON: ${e instanceof Error ? e.message : e}`;
+                }
+            },
+        }]);
+    return body.trim() ? JSON.parse(body) : {};
+}
+/** Interactive prompts for a new service (external API call). */
+export async function promptService() {
+    const svc = await inquirer.prompt([
+        { type: 'input', name: 'intent', message: 'Service name/intent (e.g. check_order_status):', validate: required('Name') },
+        { type: 'input', name: 'reference', message: 'When should the agent use it? (description/keywords):', default: '' },
+        { type: 'list', name: 'method', message: 'HTTP method:', choices: [...HTTP_METHODS] },
+        { type: 'input', name: 'endpoint', message: 'Endpoint URL:', validate: validateUrl },
+    ]);
+    const requiredFields = await promptRequiredFields();
+    const headers = await promptHeaders();
+    const bodyTemplate = (svc.method === 'GET' || svc.method === 'DELETE') ? {} : await promptBodyTemplate();
+    const { responseMessage } = await inquirer.prompt([
+        { type: 'input', name: 'responseMessage', message: 'Response message (optional):', default: '' },
+    ]);
+    return {
+        intent: svc.intent.trim(),
+        reference: svc.reference,
+        enabled: true,
+        method: svc.method,
+        endpoint: svc.endpoint.trim(),
+        requiredFields,
+        headers,
+        bodyTemplate,
+        responseMapping: {},
+        responseMessage,
+        responseConditions: [],
+    };
+}
+/** Interactive prompts for a new action (tag, stage, hand-off, events...). */
+export async function promptAction() {
+    const choices = [];
+    let lastGroup = '';
+    for (const a of ACTION_TYPES) {
+        if (a.group !== lastGroup) {
+            choices.push(new inquirer.Separator(theme.muted(`-- ${a.group} --`)));
+            lastGroup = a.group;
+        }
+        choices.push({ name: a.label, value: a.value });
+    }
+    const act = await inquirer.prompt([
+        { type: 'input', name: 'intent', message: 'Action name/intent (e.g. talk_to_human):', validate: required('Name') },
+        { type: 'input', name: 'reference', message: 'When should the agent use it? (description/keywords):', default: '' },
+        { type: 'list', name: 'actionType', message: 'Action type:', choices, pageSize: 14 },
+    ]);
+    const hint = ACTION_TYPES.find(a => a.value === act.actionType)?.valueHint;
+    const { actionValue } = hint
+        ? await inquirer.prompt([{ type: 'input', name: 'actionValue', message: `Value (${hint}):`, default: '' }])
+        : { actionValue: '' };
+    const requiredFields = await promptRequiredFields();
+    const { responseMessage } = await inquirer.prompt([
+        { type: 'input', name: 'responseMessage', message: 'Response message (optional):', default: '' },
+    ]);
+    return {
+        intent: act.intent.trim(),
+        reference: act.reference,
+        enabled: true,
+        requiredFields,
+        responseMessage,
+        action: [{ type: act.actionType, value: actionValue }],
+    };
+}
+// ---------------------------------------------------------------------------
+const SECRET_HEADER = /auth|token|key|secret|password|cookie/i;
+function maskHeaders(headers) {
+    const out = {};
+    for (const [k, v] of Object.entries(headers || {})) {
+        out[k] = SECRET_HEADER.test(k) ? (String(v).length > 10 ? `${String(v).slice(0, 4)}…${String(v).slice(-4)}` : '••••') : String(v);
+    }
+    return out;
+}
+function toolsAsJson(agentId, agentData) {
+    return {
+        id: agentId,
+        name: agentData.name,
+        useToolCalling: !!agentData.useToolCalling,
+        services: (agentData.services || []).map((s) => ({
+            intent: s.intent,
+            reference: s.reference || '',
+            method: s.method || 'POST',
+            endpoint: s.endpoint || '',
+            enabled: s.enabled !== false,
+            requiredFields: (s.requiredFields || []).map((f) => ({ name: f.name, type: f.type })),
+            headers: maskHeaders(s.headers),
+        })),
+        actions: (agentData.actions || []).map((a) => ({
+            intent: a.intent,
+            reference: a.reference || '',
+            enabled: a.enabled !== false,
+            actions: (a.action || []).map((ac) => ({ type: ac.type, label: actionLabel(ac.type), value: ac.value ?? '' })),
+        })),
+    };
+}
+function printTools(agentId, agentData) {
+    console.log(section('Tool Calling - ' + (agentData.name || agentId)));
+    console.log(kvPair('Status', agentData.useToolCalling ? theme.success('Enabled') : theme.error('Disabled')));
+    const services = agentData.services || [];
+    console.log(section(`Services - API calls (${services.length})`));
+    if (services.length > 0) {
+        const rows = services.map((s) => [
+            s.intent,
+            s.method || 'POST',
+            s.endpoint ? (s.endpoint.length > 45 ? s.endpoint.substring(0, 44) + '…' : s.endpoint) : '-',
+            statusBadge(s.enabled !== false),
+        ]);
+        console.log(createTable(['Intent', 'Method', 'Endpoint', 'Status'], rows));
+    }
+    else {
+        console.log(theme.muted('  No services configured'));
+    }
+    const actions = agentData.actions || [];
+    console.log(section(`Actions (${actions.length})`));
+    if (actions.length > 0) {
+        const rows = actions.map((a) => [
+            a.intent,
+            (a.action || []).map((ac) => actionLabel(ac.type)).join(', '),
+            statusBadge(a.enabled !== false),
+        ]);
+        console.log(createTable(['Intent', 'Type', 'Status'], rows));
+    }
+    else {
+        console.log(theme.muted('  No actions configured'));
+    }
+    if (!agentData.useToolCalling && (services.length > 0 || actions.length > 0)) {
+        logger.warning('Tool Calling is disabled, so the agent will not use these tools.');
+    }
+    console.log();
+}
 export const toolsCommand = new Command('tools')
-    .description('Manage agent Tool Calling tools')
-    .argument('<agentId>', 'Agent ID')
+    .description('List, add and remove the services and actions the agent can call (Tool Calling)')
+    .argument('<agentId>', 'Agent ID (e.g. age_AbcDef123)')
+    .option('--list', 'Print the current services and actions and exit (no prompts)')
+    .addOption(jsonOption('Output machine-readable JSON (implies --list)'))
     .option('--dev', 'Use development environment', false)
     .action(async (agentId, options) => {
     try {
+        const listOnly = !!options.list || isJsonMode();
+        if (!listOnly) {
+            requireInteractive('The tools menu', `List tools without prompts: plazbot agent tools ${agentId} --list --json`);
+        }
         const credentials = await getStoredCredentials();
         const agent = new Agent({
             workspaceId: credentials.workspace,
@@ -20,136 +253,136 @@ export const toolsCommand = new Command('tools')
         });
         const spinner = createSpinner('Loading agent...');
         spinner.start();
-        const _res = await agent.getAgentById({ id: agentId });
-        const agentData = _res.agent || _res.data || _res;
-        spinner.stop();
-        console.log(section('Tool Calling - ' + (agentData.name || agentId)));
-        console.log(kvPair('Status', agentData.useToolCalling ? theme.success('Enabled') : theme.error('Disabled')));
-        // Servicios
-        const services = agentData.services || [];
-        if (services.length > 0) {
-            console.log(section('Services (API calls)'));
-            const rows = services.map((s) => [
-                s.intent,
-                s.method || 'POST',
-                s.endpoint ? s.endpoint.substring(0, 40) + '...' : 'N/A',
-                statusBadge(s.enabled !== false),
-            ]);
-            console.log(createTable(['Intent', 'Method', 'Endpoint', 'Status'], rows));
-        }
-        else {
-            console.log(theme.muted('\n  No services configured'));
+        let agentData;
+        try {
+            const _res = await agent.getAgentById({ id: agentId });
+            agentData = _res.agent || _res.data || _res;
+            spinner.stop();
         }
-        // Acciones
-        const actions = agentData.actions || [];
-        if (actions.length > 0) {
-            console.log(section('Actions'));
-            const rows = actions.map((a) => [
-                a.intent,
-                (a.action || []).map((ac) => ac.type).join(', '),
-                statusBadge(a.enabled !== false),
-            ]);
-            console.log(createTable(['Intent', 'Type', 'Status'], rows));
+        catch (loadErr) {
+            spinner.stop();
+            throw new CliError(describeAgentLoadError(loadErr, agentId, credentials, { dev: options.dev }), 'agent_not_found');
         }
-        else {
-            console.log(theme.muted('\n  No actions configured'));
-        }
-        // Menu de opciones
-        console.log();
-        const { action } = await inquirer.prompt([{
-                type: 'list',
-                name: 'action',
-                message: 'What would you like to do?',
-                choices: [
-                    { name: 'Add service (API call)', value: 'add-service' },
-                    { name: 'Add action', value: 'add-action' },
-                    { name: agentData.useToolCalling ? 'Disable Tool Calling' : 'Enable Tool Calling', value: 'toggle' },
-                    { name: 'Exit', value: 'exit' },
-                ],
-            }]);
-        if (action === 'exit')
-            return;
-        if (action === 'toggle') {
-            const toggleSpinner = createSpinner('Updating...');
-            toggleSpinner.start();
-            const { id: _i1, _id: _o1, ...updatedConfig } = { ...agentData, useToolCalling: !agentData.useToolCalling };
-            await agent.updateAgent(agentId, updatedConfig);
-            toggleSpinner.succeed(`Tool Calling ${!agentData.useToolCalling ? 'enabled' : 'disabled'}`);
+        if (listOnly) {
+            if (isJsonMode())
+                printJson(toolsAsJson(agentId, agentData));
+            else
+                printTools(agentId, agentData);
             return;
         }
-        if (action === 'add-service') {
-            const svc = await inquirer.prompt([
-                { type: 'input', name: 'intent', message: 'Service name/intent:', validate: (v) => v.length > 0 || 'Required' },
-                { type: 'input', name: 'reference', message: 'Keywords:', default: '' },
-                { type: 'list', name: 'method', message: 'HTTP method:', choices: ['GET', 'POST'] },
-                { type: 'input', name: 'endpoint', message: 'Endpoint URL:', validate: (v) => v.length > 0 || 'Required' },
-                { type: 'input', name: 'responseMessage', message: 'Response message:', default: '' },
-            ]);
-            const newService = {
-                intent: svc.intent,
-                reference: svc.reference,
-                enabled: true,
-                method: svc.method,
-                endpoint: svc.endpoint,
-                requiredFields: [],
-                headers: {},
-                bodyTemplate: {},
-                responseMapping: {},
-                responseMessage: svc.responseMessage,
-                responseConditions: [],
-            };
-            const updatedServices = [...services, newService];
-            const { id: _i2, _id: _o2, ...updatedConfig } = { ...agentData, services: updatedServices, useToolCalling: true };
-            const updateSpinner = createSpinner('Saving service...');
-            updateSpinner.start();
-            await agent.updateAgent(agentId, updatedConfig);
-            updateSpinner.succeed(`Service "${svc.intent}" added`);
-        }
-        if (action === 'add-action') {
-            const act = await inquirer.prompt([
-                { type: 'input', name: 'intent', message: 'Action name/intent:', validate: (v) => v.length > 0 || 'Required' },
-                { type: 'input', name: 'reference', message: 'Keywords:', default: '' },
-                {
-                    type: 'list', name: 'actionType', message: 'Action type:',
+        const save = async (patch, text, done) => {
+            const s = createSpinner(text);
+            s.start();
+            const { id: _i, _id: _o, ...payload } = { ...agentData, ...patch };
+            await agent.updateAgent(agentId, payload);
+            agentData = { ...agentData, ...patch };
+            s.succeed(done);
+        };
+        // Adding a tool while Tool Calling is off: ask, never enable silently.
+        const resolveToolCalling = async () => {
+            if (agentData.useToolCalling)
+                return true;
+            const { enable } = await inquirer.prompt([{
+                    type: 'confirm', name: 'enable', default: true,
+                    message: 'Tool Calling is disabled for this agent. Enable it so the agent can use this tool?',
+                }]);
+            return enable;
+        };
+        printTools(agentId, agentData);
+        while (true) {
+            const services = agentData.services || [];
+            const actions = agentData.actions || [];
+            const { action } = await inquirer.prompt([{
+                    type: 'list',
+                    name: 'action',
+                    message: 'What would you like to do?',
                     choices: [
-                        { name: 'Schedule event', value: 'action.event.add' },
-                        { name: 'Update event (reschedule)', value: 'action.event.update' },
-                        { name: 'List events', value: 'action.event.list' },
-                        { name: 'Delete event (cancel)', value: 'action.event.delete' },
-                        { name: 'Add tag', value: 'action.tag' },
-                        { name: 'Change stage', value: 'action.stage' },
-                        { name: 'Hand off to human agent', value: 'action.agentShutDown' },
-                        { name: 'Mark as resolved', value: 'action.solved' },
-                        { name: 'Assign agent', value: 'action.asign' },
-                        { name: 'Segmentation', value: 'action.segmentation' },
+                        { name: 'List services and actions', value: 'list' },
+                        { name: 'Add service (API call)', value: 'add-service' },
+                        { name: 'Add action', value: 'add-action' },
+                        { name: 'Remove service', value: 'remove-service', disabled: services.length === 0 ? 'none configured' : false },
+                        { name: 'Remove action', value: 'remove-action', disabled: actions.length === 0 ? 'none configured' : false },
+                        { name: agentData.useToolCalling ? 'Disable Tool Calling' : 'Enable Tool Calling', value: 'toggle' },
+                        { name: 'Exit', value: 'exit' },
                     ],
-                },
-                { type: 'input', name: 'actionValue', message: 'Value (optional):', default: '' },
-                { type: 'input', name: 'responseMessage', message: 'Response message:', default: '' },
-            ]);
-            const newAction = {
-                intent: act.intent,
-                reference: act.reference,
-                enabled: true,
-                requiredFields: [],
-                responseMessage: act.responseMessage,
-                action: [{ type: act.actionType, value: act.actionValue }],
-            };
-            const updatedActions = [...actions, newAction];
-            const { id: _i3, _id: _o3, ...updatedConfig } = { ...agentData, actions: updatedActions, useToolCalling: true };
-            const updateSpinner = createSpinner('Saving action...');
-            updateSpinner.start();
-            await agent.updateAgent(agentId, updatedConfig);
-            updateSpinner.succeed(`Action "${act.intent}" added`);
+                }]);
+            if (action === 'exit')
+                return;
+            if (action === 'list') {
+                printTools(agentId, agentData);
+                continue;
+            }
+            if (action === 'toggle') {
+                const next = !agentData.useToolCalling;
+                await save({ useToolCalling: next }, 'Updating Tool Calling...', `Tool Calling ${next ? 'enabled' : 'disabled'}`);
+                continue;
+            }
+            if (action === 'add-service' || action === 'add-action') {
+                const isService = action === 'add-service';
+                const item = isService ? await promptService() : await promptAction();
+                const list = isService ? services : actions;
+                if (list.some((x) => x.intent === item.intent)) {
+                    logger.warning(`A ${isService ? 'service' : 'action'} named "${item.intent}" already exists. Nothing was saved.`);
+                    continue;
+                }
+                const enableTc = await resolveToolCalling();
+                const patch = isService
+                    ? { services: [...services, item] }
+                    : { actions: [...actions, item] };
+                const turningOn = enableTc && !agentData.useToolCalling;
+                if (turningOn)
+                    patch.useToolCalling = true;
+                await save(patch, `Saving ${isService ? 'service' : 'action'}...`, `${isService ? 'Service' : 'Action'} "${item.intent}" added`);
+                if (turningOn)
+                    logger.success('Tool Calling was enabled for this agent.');
+                if (!agentData.useToolCalling)
+                    logger.warning('Tool Calling is still disabled: the agent will not use this tool until you enable it.');
+                continue;
+            }
+            if (action === 'remove-service' || action === 'remove-action') {
+                const isService = action === 'remove-service';
+                const list = isService ? services : actions;
+                const { selected } = await inquirer.prompt([{
+                        type: 'checkbox',
+                        name: 'selected',
+                        message: `Select the ${isService ? 'services' : 'actions'} to remove:`,
+                        choices: list.map((x, i) => ({
+                            name: isService
+                                ? `${x.intent} ${theme.muted(`${x.method || 'POST'} ${x.endpoint || ''}`)}`
+                                : `${x.intent} ${theme.muted((x.action || []).map((ac) => actionLabel(ac.type)).join(', '))}`,
+                            value: i,
+                        })),
+                    }]);
+                if (!selected.length) {
+                    logger.dim('Nothing selected.');
+                    continue;
+                }
+                const names = selected.map((i) => list[i].intent).join(', ');
+                const ok = await confirmAction(`Remove ${selected.length} ${isService ? 'service(s)' : 'action(s)'}: ${names}?`, {});
+                if (!ok) {
+                    logger.dim('Aborted.');
+                    continue;
+                }
+                const remaining = list.filter((_, i) => !selected.includes(i));
+                await save(isService ? { services: remaining } : { actions: remaining }, 'Removing...', `Removed ${selected.length} ${isService ? 'service(s)' : 'action(s)'}`);
+                continue;
+            }
         }
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : 'Unknown error';
-        logger.error(message);
-        process.exit(1);
+        fail(error);
     }
 });
 addExamples(toolsCommand, [
-    { description: 'View services/actions and add new ones interactively',
-        command: 'plazbot agent tools agt_AbcDef123' },
+    { description: 'Open the interactive menu to list, add or remove tools',
+        command: 'plazbot agent tools age_AbcDef123' },
+    { description: 'Print the configured services and actions',
+        command: 'plazbot agent tools age_AbcDef123 --list' },
+    { description: 'Export services and actions as JSON (secret headers masked)',
+        command: 'plazbot agent tools age_AbcDef123 --list --json' },
+]);
+addNotes(toolsCommand, [
+    'Services support GET, POST, PUT, PATCH and DELETE, with optional headers and a JSON body template (POST, PUT, PATCH).',
+    'Adding a tool while Tool Calling is disabled asks before enabling it.',
+    'For bulk edits, export the agent, edit services/actions in the JSON and run plazbot agent update.',
 ]);

package/dist/commands/agent/update.js

@@ -1,53 +1,94 @@
 import { Command } from 'commander';
-import { Agent } from 'plazbot';
 import { getStoredCredentials } from '../../utils/credentials.js';
 import { logger } from '../../utils/logger.js';
-import { addExamples } from '../../utils/help.js';
+import { addExamples, addNotes } from '../../utils/help.js';
+import { createApiClient } from '../../utils/api.js';
+import { jsonOption, isJsonMode, printJson, fail, CliError } from '../../utils/output.js';
+import { patchAgent } from '../../utils/agent-patch.js';
 import fs from 'fs/promises';
 export const updateCommand = new Command('update')
-    .description('Update an existing agent in Plazbot')
+    .description('Update an existing agent: only the fields present in the JSON file are changed')
     .argument('<agentId>', 'Agent ID to update')
-    .argument('<configPath>', 'Path to the agent JSON configuration file')
+    .argument('<configPath>', 'Path to a JSON file with the fields to change')
+    .option('--replace', 'Replace the whole agent with the file (fields not in the file are removed)', false)
+    .addOption(jsonOption('Print the result as JSON ({"id","updated","fields"})'))
     .option('--dev', 'Use development environment', false)
     .action(async (agentId, configPath, options) => {
     try {
-        // Obtener credenciales guardadas
         const credentials = await getStoredCredentials();
         // Leer archivo de configuración del agente
-        let agentConfig;
+        let fileContent;
         try {
-            const fileContent = await fs.readFile(configPath, 'utf-8');
-            agentConfig = JSON.parse(fileContent);
+            fileContent = await fs.readFile(configPath, 'utf-8');
         }
         catch (error) {
             const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-            throw new Error(`Error reading configuration file: ${errorMessage}`);
-        }
-        // Crear instancia del agente con las credenciales guardadas
-        const agent = new Agent({
-            workspaceId: credentials.workspace,
-            apiKey: credentials.apiKey,
-            zone: credentials.zone,
-            ...(options.dev && { customUrl: "http://localhost:5090" })
-        });
-        logger.dim('Updating agent...');
-        // Actualizar el agente
-        const result = await agent.updateAgent(agentId, agentConfig);
+            throw new CliError(`Could not read the config file: ${errorMessage}`, 'file_not_readable');
+        }
+        let fileConfig;
+        try {
+            fileConfig = JSON.parse(fileContent);
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : 'Unknown error';
+            throw new CliError(`The config file is not valid JSON: ${errorMessage}`, 'invalid_json');
+        }
+        if (!fileConfig || typeof fileConfig !== 'object' || Array.isArray(fileConfig)) {
+            throw new CliError('The config file must contain a JSON object.', 'invalid_config');
+        }
+        const fields = Object.keys(fileConfig);
+        if (fields.length === 0) {
+            throw new CliError('The config file has no fields to update.', 'empty_config', 'Add the fields to change, e.g. {"question": "Hi!"}.');
+        }
+        const target = { apiKey: credentials.apiKey, workspace: credentials.workspace, zone: credentials.zone, dev: options.dev };
+        if (options.replace) {
+            // Reemplazo completo: el archivo se envia tal cual a /api/agent/update
+            logger.dim('Replacing agent...');
+            const api = createApiClient(target);
+            const { data, status } = await api.post('/api/agent/update', fileConfig, {
+                headers: { 'x-agent-id': agentId },
+                validateStatus: () => true,
+            });
+            if (!data?.success) {
+                // Errores de schema que devuelve la API (uno por campo)
+                const errors = (Array.isArray(data?.errors) ? data.errors : [])
+                    .map((err) => (typeof err === 'string' ? err : JSON.stringify(err)));
+                const base = data?.message || `Agent update failed${status ? ` (HTTP ${status})` : ''}.`;
+                const message = errors.length
+                    ? `${base.replace(/\.?$/, ':')}\n${errors.map((e, i) => `    ${i + 1}. ${e}`).join('\n')}`
+                    : base;
+                throw new CliError(message, 'update_failed', `Check the file with: plazbot agent validate ${configPath}`);
+            }
+        }
+        else {
+            // Solo los campos del archivo (POST /api/agent/patch)
+            logger.dim(`Updating fields: ${fields.join(', ')}`);
+            await patchAgent(target, agentId, fileConfig);
+        }
+        if (isJsonMode()) {
+            printJson({ id: agentId, updated: true, fields, replaced: Boolean(options.replace) });
+            return;
+        }
         logger.success('Agent updated successfully');
-        logger.info(`Message: ${result.message}`);
         if (options.dev) {
             logger.warning('Environment: development');
         }
     }
     catch (error) {
-        const message = error instanceof Error ? error.message : 'Unknown error while updating the agent';
-        logger.error(message);
-        process.exit(1);
+        fail(error);
     }
 });
 addExamples(updateCommand, [
-    { description: 'Push a new configuration to the agent',
-        command: 'plazbot agent update agt_AbcDef123 ./agent.json' },
-    { description: 'Tip: export → edit → update workflow',
-        command: 'plazbot agent export agt_AbcDef123 -o agent.json && plazbot agent update agt_AbcDef123 ./agent.json' },
+    { description: 'Change only the fields in the file (e.g. {"question": "Hi!"})',
+        command: 'plazbot agent update age_AbcDef123 ./changes.json' },
+    { description: 'Export, edit and update workflow',
+        command: 'plazbot agent export age_AbcDef123 -o agent.json && plazbot agent update age_AbcDef123 ./agent.json' },
+    { description: 'Replace the whole agent with the file',
+        command: 'plazbot agent update age_AbcDef123 ./agent.json --replace' },
+    { description: 'Update and get a JSON result (scripts)',
+        command: 'plazbot agent update age_AbcDef123 ./changes.json --json' },
+]);
+addNotes(updateCommand, [
+    'Without --replace, only the fields in the file change; each top-level field replaces the stored one (e.g. "services" replaces the whole list).',
+    'With --replace, fields missing from the file are removed from the agent.',
 ]);