Lists the organization's own AI agents (custom agents and personalizations of MB Suite's system agents), alphabetically by functional name, paginated by cursor (limit up to 200). Each item brings its type (custom), the functional name and the resolved human name, description, category, channel (in_app; whatsapp_crm talks to CRM leads; social answers on social networks), avatar, provider and model, access mode, whether it replaces a system agent, how many knowledge entries it has and who created it (created_by and created_by_name); use ai.agents.get for its full configuration. MB Suite's built-in system agents are listed by ai.system_agents.list; unsaved drafts are not listed. An agent restricted to some roles or members is only listed to them and to owners and admins, so a page can bring fewer than limit while has_more is true: follow next_cursor. Filter with channel. Any member can read. Module: Organization (organizations), even though the id starts with ai.; any valid credential can read it.
Alcance
organizations:read
Permiso
Ver el módulo
Tool del MCP
ai_agents_listEn la superficie completa; en la compacta, mb_execute_operation con id: "ai.agents.list".
Costo declarado: hasta 402 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).
Parámetros
limitintegerqueryopcional
How many items this page brings at most (see the maximum and the default in the schema).
Por defecto: 50
cursorstringqueryopcional
The next_cursor of the previous page, exactly as it came (only for the same list and filters); without it, the first page.
channelenumqueryopcional
Only agents of this channel (in_app when the agent has none).
Returns an organization agent with its configuration: model, temperature, voice, context sources, execution config, quick prompts, access control and its knowledge entries (title, type, file name, size, processing status and content_external, true when the entry's text is stored apart from the agent because it did not fit in its record; never the extracted file text nor storage paths). The instructions (system_prompt) and the content of the knowledge entries (content, and the summary of file entries) are returned only in the MB Suite app, to MIA and to an API key with the special permission live_ai_agents, which also gets the full text of the entries stored apart: with any other API key or connected app, system_prompt and each content are null and there is no summary. 404 ai_agent_not_found if the id does not exist in this organization, is a system agent or a draft, or the agent is restricted to roles or members that do not include the caller. Any member can read. Module: Organization (organizations), even though the id starts with ai.; any valid credential can read it.
Alcance
organizations:read
Permiso
Ver el módulo
Tool del MCP
ai_agents_getEn la superficie completa; en la compacta, mb_execute_operation con id: "ai.agents.get".
Costo declarado: hasta 2 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).
Parámetros
agent_idstringrutarequerido
The agent id (from ai.agents.list).
Respuesta
idstring
typestring
custom: an agent of the organization; a personalization or a duplicate of an MB Suite system agent is custom too (see based_on_system_id). MB Suite's own agents are listed by ai.system_agents.list.
namestring
resolved_namestring
display_namestring | null
descriptionstring
categorystring | null
channelstring | null
in_app (assists the team in the app), whatsapp_crm (talks to CRM leads) or social (answers on social networks); null means in_app (an agent saved before channels existed).
avatarstring | null
iconstring
colorstring
providerstring
modelstring
model_overridestring | null
based_on_system_idstring | null
replaces_system_agentboolean
agent_scopeenum
Valores: parent, child
scope_org_idsarray<string>
access_modeenum
Valores: all, roles, members
knowledge_countnumber
created_bystring | null
The user id of who created it.
created_by_namestring | null
Their name, as the team shows it (null when unknown).
created_atnumber
updated_atnumber
system_promptstring | null
The agent's instructions. null for API keys and connected apps: the instructions are shown only in the app and to MIA.
Creates a custom AI agent in the organization: name (the functional role, up to 100 characters), system_prompt (its instructions, up to 10,000 characters), and optionally display_name (a human name; without it the name follows the face), description, avatar (a gallery id g01 to g40, a cast face token sys:<system_agent_key>, or an image uploaded to this workspace), icon and color, category, channel (in_app by default; whatsapp_crm talks to CRM leads and forces the ventas category, social answers on social networks and forces contenido_social), provider (mia, gemini, openai or anthropic) and model_override (without it the provider's default model is used), temperature (0 to 2), voice (auto, female, male or off), context_sources, execution_config (mode conversational or executor, auto_apply, enabled_entities among tasks, posts, campaigns and contacts), quick_prompts (up to 10), knowledge_entries (text entries: id, title, content, created_at, updated_at; knowledge files are uploaded from the screen) and who can use it (access_mode all, roles or members, with allowed_roles or allowed_member_ids). Unsent fields take the agent builder's defaults (temperature 0.2, the current view as context, conversational: it proposes and executes nothing). To personalize one of MB Suite's system agents pass based_on_system_id (a key from ai.system_agents.list; outside the app an unknown or unavailable one is 400 ai_agent_system_unknown) and replaces_system_agent true: there is one personalization per system agent (409 ai_agent_personalization_exists). With based_on_system_id and an empty system_prompt, the new agent starts with that system agent's instructions (they are copied into it). Without knowledge_entries, it also starts with that system agent's text knowledge entries (copied as new entries and indexed like any new agent; never its files nor the long texts stored apart, like MIA's help center). A workspace agent that works for one Account uses agent_scope child and scope_org_ids with that Account (400 ai_agent_scope_invalid if it is not an Account of this workspace). Creating an agent does not put it to work: it works when a position of the CRM or Social Inbox AI Team takes it as its agent (the position's ai_agent_id; channel whatsapp_crm for the CRM, social for the Social Inbox), set when the position is created or updated, or in the app. Members who are not viewers can create; API keys and connected apps cannot (no credential writes organization settings), except an API key with the create_ai_agents special permission through ai.agents.create_with_key. Returns agent_id and the agent. Module: Organization (organizations), even though the id starts with ai.; it is not available to API keys or OAuth tokens (none can be given write access to organizations).
Alcance
organizations:write
Permiso
Editar en el módulo
Tool del MCP
ai_agents_createEn la superficie completa; en la compacta, mb_execute_operation con id: "ai.agents.create".
Costo declarado: hasta 4 lecturas y 1 escrituras por llamada (cuentan en el cupo diario).
Parámetros
namestringcuerporequerido
The agent's functional name (what it does: «Analista de pauta»), up to 100 characters.
system_promptstringcuerporequerido
Its instructions (up to 10000 characters).
display_namestring | nullcuerpoopcional
Its human name, up to 40 characters; null or absent: the name of its face.
descriptionstringcuerpoopcional
What it does, up to 500 characters.
Por defecto: ""
voiceenumcuerpoopcional
Its voice: auto (follows its face), female, male or off.
Valores: auto, female, male, off
providerenumcuerpoopcional
The AI provider: gemini, openai, anthropic, or mia (MB Suite picks the model by tier).
Valores: gemini, openai, anthropic, mia
modelstringcuerpoopcional
The model id (mia:flash, mia:standard, mia:pro, or a provider's model the agent builder offers).
model_overridestring | nullcuerpoopcional
A model id that replaces model for this agent; null removes it.
temperaturenumbercuerpoopcional
How creative its answers are, 0 (precise) to 2.
Por defecto: 0.2
iconstringcuerpoopcional
Its icon: a Material Design icon name (mdiCreation…).
Por defecto: "mdiCreation"
colorstringcuerpoopcional
Its color in the app (violet, cyan…).
Por defecto: "violet"
context_sourcesarray<string>cuerpoopcional
What it reads to answer (up to 20): current_view, tasks, social_posts, media_plans, contacts, seo_items, seo_audit, seo_rankings, datasources, org_documents.
Por defecto: ["current_view"]
execution_configobjectcuerpoopcional
Whether it only talks or also acts, and on what.
Por defecto: {"mode":"conversational","auto_apply":false,"enabled_entities":[]}
quick_promptsarray<object>cuerpoopcional
Up to 10 shortcuts shown in the chat.
Por defecto: []
knowledge_entriesarray<object>cuerpoopcional
Its knowledge (up to 50 entries of text or files) that it searches when answering.
Por defecto: []
agent_scopeenumcuerpoopcional
parent: an agent of the workspace; child: one of an Account (with scope_org_ids).
Valores: parent, child
scope_org_idsarray<string>cuerpoopcional
For a child agent: the Account it belongs to (one id, from platform.orgs.list).
categoryenum | nullcuerpoopcional
Its team in the app: ventas, paid_media, contenido_social, seo, email_mkt, datos_reportes, clientes_ops, directorio or general (a whatsapp_crm agent is always ventas and a social one contenido_social).
Valores: ventas, paid_media, contenido_social, seo, email_mkt, seo_email, datos_reportes, clientes_ops, directorio, general
channelenum | nullcuerpoopcional
Who it talks to: in_app (the team in the app), whatsapp_crm (CRM leads) or social (social networks).
Valores: in_app, whatsapp_crm, social
based_on_system_idstringcuerpoopcional
The key of the MB Suite system agent it starts from (ai.system_agents.list).
replaces_system_agentbooleancuerpoopcional
With based_on_system_id: it replaces that system agent in the organization (one personalization per system agent).
avatarstring | nullcuerpoopcional
Its face: a gallery id (g01 to g40), a face of the cast (sys:<key>) or an image uploaded in the app; never an external URL.
access_modeenumcuerpoopcional
Who can use it: all, roles (allowed_roles) or members (allowed_member_ids).
Valores: all, roles, members
allowed_rolesarray<enum>cuerpoopcional
With access_mode roles: the roles that can use it.
Valores: owner, admin, member, viewer
allowed_member_idsarray<string>cuerpoopcional
With access_mode members: the user ids that can use it (members.members.list).
Create an AI agent with a key that has the create_ai_agents permission
ai.agents.create_with_key
EscrituraDesde 2026-11-01
Creates a custom AI agent in the organization like ai.agents.create (the same fields and rules): name (the functional role, up to 100 characters), system_prompt (its instructions, up to 10,000 characters), and optionally display_name (a human name; without it the name follows the face), description, avatar (a gallery id g01 to g40, a cast face token sys:<system_agent_key>, or an image uploaded to this workspace), icon and color, category, channel (in_app by default; whatsapp_crm talks to CRM leads and forces the ventas category, social answers on social networks and forces contenido_social), provider (mia, gemini, openai or anthropic) and model_override (without it the provider's default model is used), temperature (0 to 2), voice (auto, female, male or off), context_sources, execution_config (mode conversational or executor, auto_apply, enabled_entities among tasks, posts, campaigns and contacts), quick_prompts (up to 10), knowledge_entries (text entries: id, title, content, created_at, updated_at; knowledge files are uploaded from the screen) and who can use it (access_mode all, roles or members, with allowed_roles or allowed_member_ids). Only for an API key with the special permission create_ai_agents (an owner or admin gives it on the key), over REST or the MCP, in its own organization and in the accounts the key reaches: for any other credential this operation does not exist (404), and that permission is what authorizes writing agents (no key can have organizations:write). Always with a preview: first call with dry_run=true to get the agent that would be created, the MB Suite system agent it starts from or replaces, whether it takes that agent's instructions (based_on_system_id with an empty system_prompt) and its text knowledge (without knowledge_entries), and how many knowledge entries will be indexed with AI, plus a confirm_token, then call again with the token; the preview checks everything the creation checks. The key confirms its own preview: whoever gives the permission approves in advance what the key creates. A text knowledge entry from 200 characters is indexed with AI in the background, like in the app (it shows embedding_status processing until it is ready), with the AI credits of the person behind the key: without credits the agent is created anyway and the entry stays with embedding_status error and embedding_error ai_credits_exhausted (ai_personal_limit or payment_required); knowledge files are uploaded in the app. A personalization (replaces_system_agent true) is one per system agent (409 ai_agent_personalization_exists) and based_on_system_id must be a key from ai.system_agents.list (400 ai_agent_system_unknown). The person behind the key must be able to edit agents (a viewer cannot: 403 ai_agent_editor_required). Creating an agent does not put it to work: it works when a position of the CRM or Social Inbox AI Team takes it as its agent (the position's ai_agent_id; channel whatsapp_crm for the CRM, social for the Social Inbox), set when the position is created or updated, or in the app. The creation goes to the audit log with the permission. To see or edit the instructions of the new agent the key also needs live_ai_agents (ai.agents.get, ai.agents.update_live). Returns agent_id and the agent. Module: Organization (organizations), even though the id starts with ai.; an API key needs its special permission create_ai_agents.
Pide confirmación: primero dry_run: true (vista previa y confirm_token, que vale 10 minutos y una sola vez), después el mismo cuerpo con confirm_token. En unas pocas, solo con ciertos datos: la descripción dice cuándo. Por qué y cómo: Vista previa y confirmación.
Alcance
organizations:write
Permiso
Editar en el módulo
Tool del MCP
ai_agents_create_with_keyEn la superficie completa; en la compacta, mb_execute_operation con id: "ai.agents.create_with_key".
Costo declarado: hasta 23 lecturas y 66 escrituras por llamada (cuentan en el cupo diario). Toca una plataforma externa (ai): cuenta en el cupo de operaciones externas.
Parámetros
namestringcuerporequerido
The agent's functional name (what it does: «Analista de pauta»), up to 100 characters.
system_promptstringcuerporequerido
Its instructions (up to 10000 characters).
display_namestring | nullcuerpoopcional
Its human name, up to 40 characters; null or absent: the name of its face.
descriptionstringcuerpoopcional
What it does, up to 500 characters.
Por defecto: ""
voiceenumcuerpoopcional
Its voice: auto (follows its face), female, male or off.
Valores: auto, female, male, off
providerenumcuerpoopcional
The AI provider: gemini, openai, anthropic, or mia (MB Suite picks the model by tier).
Valores: gemini, openai, anthropic, mia
modelstringcuerpoopcional
The model id (mia:flash, mia:standard, mia:pro, or a provider's model the agent builder offers).
model_overridestring | nullcuerpoopcional
A model id that replaces model for this agent; null removes it.
temperaturenumbercuerpoopcional
How creative its answers are, 0 (precise) to 2.
Por defecto: 0.2
iconstringcuerpoopcional
Its icon: a Material Design icon name (mdiCreation…).
Por defecto: "mdiCreation"
colorstringcuerpoopcional
Its color in the app (violet, cyan…).
Por defecto: "violet"
context_sourcesarray<string>cuerpoopcional
What it reads to answer (up to 20): current_view, tasks, social_posts, media_plans, contacts, seo_items, seo_audit, seo_rankings, datasources, org_documents.
Por defecto: ["current_view"]
execution_configobjectcuerpoopcional
Whether it only talks or also acts, and on what.
Por defecto: {"mode":"conversational","auto_apply":false,"enabled_entities":[]}
quick_promptsarray<object>cuerpoopcional
Up to 10 shortcuts shown in the chat.
Por defecto: []
knowledge_entriesarray<object>cuerpoopcional
Its knowledge (up to 50 entries of text or files) that it searches when answering.
Por defecto: []
agent_scopeenumcuerpoopcional
parent: an agent of the workspace; child: one of an Account (with scope_org_ids).
Valores: parent, child
scope_org_idsarray<string>cuerpoopcional
For a child agent: the Account it belongs to (one id, from platform.orgs.list).
categoryenum | nullcuerpoopcional
Its team in the app: ventas, paid_media, contenido_social, seo, email_mkt, datos_reportes, clientes_ops, directorio or general (a whatsapp_crm agent is always ventas and a social one contenido_social).
Valores: ventas, paid_media, contenido_social, seo, email_mkt, seo_email, datos_reportes, clientes_ops, directorio, general
channelenum | nullcuerpoopcional
Who it talks to: in_app (the team in the app), whatsapp_crm (CRM leads) or social (social networks).
Valores: in_app, whatsapp_crm, social
based_on_system_idstringcuerpoopcional
The key of the MB Suite system agent it starts from (ai.system_agents.list).
replaces_system_agentbooleancuerpoopcional
With based_on_system_id: it replaces that system agent in the organization (one personalization per system agent).
avatarstring | nullcuerpoopcional
Its face: a gallery id (g01 to g40), a face of the cast (sys:<key>) or an image uploaded in the app; never an external URL.
access_modeenumcuerpoopcional
Who can use it: all, roles (allowed_roles) or members (allowed_member_ids).
Valores: all, roles, members
allowed_rolesarray<enum>cuerpoopcional
With access_mode roles: the roles that can use it.
Valores: owner, admin, member, viewer
allowed_member_idsarray<string>cuerpoopcional
With access_mode members: the user ids that can use it (members.members.list).
Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.En la práctica esta operación no se simula (toca otra plataforma): responde 409 sandbox_external_unavailable.
PATCH/v1/ai/agents/{agent_id}
Update an AI agent
ai.agents.update
EscrituraIdempotenteDesde 2026-11-01
Updates one or more fields of an organization agent inside updates (the same fields as ai.agents.create, all optional; only what is sent changes). knowledge_entries replaces the whole list: send every entry, the ones you keep and the ones you add (entries keep their file data by id); an uploaded or indexed entry cannot be removed from here (409 ai_agent_knowledge_removal_not_allowed: it is removed from the screen). The link to a system agent cannot change. Members who are not viewers can edit; an agent restricted to some roles or members only by them and by owners and admins (403 ai_agent_access_denied). An agent that works in a seat of the CRM or Social Inbox AI Team attends leads or customers live: from outside the screen it cannot be changed (409 ai_agent_in_live_seat, the seats in details), except by MIA with the person's click on its card; an API key with the live_ai_agents special permission uses ai.agents.update_live instead. Outside the screen, a text knowledge entry whose content changes is indexed again with AI in the background with the caller's AI credits: without credits the agent is saved anyway and the entry stays with embedding_status error and embedding_error ai_credits_exhausted (ai_personal_limit or payment_required). The dry run says which fields change and the live seats where it works. 404 ai_agent_not_found. Returns the updated agent. Module: Organization (organizations), even though the id starts with ai.; it is not available to API keys or OAuth tokens (none can be given write access to organizations).
Alcance
organizations:write
Permiso
Editar en el módulo
Tool del MCP
ai_agents_updateEn la superficie completa; en la compacta, mb_execute_operation con id: "ai.agents.update".
Costo declarado: hasta 20 lecturas y 7 escrituras por llamada (cuentan en el cupo diario).
Parámetros
agent_idstringrutarequerido
The agent id (from ai.agents.list).
updatesobjectcuerporequerido
What changes: only the fields sent (the link to a system agent does not change).
Update an AI agent, also one working live, with a key allowed to
ai.agents.update_live
EscrituraIdempotenteDesde 2026-11-01
Updates an organization agent like ai.agents.update (the same updates object and rules), including one that works in a seat of the CRM or Social Inbox AI Team and handles leads or customers live. Only for an API key with the special permission live_ai_agents (an owner or admin gives it on the key), over REST or the MCP, in its own organization and in the accounts the key reaches: for any other credential this operation does not exist (404), and that permission is what authorizes writing agents (no key can have organizations:write). Always with a preview: first call with dry_run=true to get the agent, the fields that change, its live seats and how many knowledge entries will be indexed again, plus a confirm_token, then call again with the token. The key confirms its own preview: whoever gives the permission approves those changes in advance. A text knowledge entry whose content changes is indexed again with AI in the background, like in the app (an entry stored apart is sent with its full text, as ai.agents.get returns it with this permission; an empty one is left unchanged), with the AI credits of the person behind the key: without credits the agent is saved anyway and the entry stays with embedding_status error and embedding_error ai_credits_exhausted (ai_personal_limit or payment_required). The change applies from the agent's next turn; the live seats go to the audit log. The person behind the key must be able to edit the agent (403 ai_agent_access_denied). 404 ai_agent_not_found. Returns the updated agent. Module: Organization (organizations), even though the id starts with ai.; an API key needs its special permission live_ai_agents.
Pide confirmación: primero dry_run: true (vista previa y confirm_token, que vale 10 minutos y una sola vez), después el mismo cuerpo con confirm_token. En unas pocas, solo con ciertos datos: la descripción dice cuándo. Por qué y cómo: Vista previa y confirmación.
Alcance
organizations:write
Permiso
Editar en el módulo
Tool del MCP
ai_agents_update_liveEn la superficie completa; en la compacta, mb_execute_operation con id: "ai.agents.update_live".
Costo declarado: hasta 73 lecturas y 66 escrituras por llamada (cuentan en el cupo diario). Toca una plataforma externa (ai): cuenta en el cupo de operaciones externas.
Parámetros
agent_idstringrutarequerido
The agent id (from ai.agents.list).
updatesobjectcuerporequerido
What changes: only the fields sent (the link to a system agent does not change).
Con una API key de prueba el pedido va siempre a tu organización de práctica: datos de ejemplo que puedes reiniciar.En la práctica esta operación no se simula (toca otra plataforma): responde 409 sandbox_external_unavailable.
DELETE/v1/ai/agents/{agent_id}
Delete an AI agent
ai.agents.delete
IrreversibleDesde 2026-11-01
Deletes an organization agent. It goes to the 30-day trash with its configuration and knowledge (its indexed fragments and uploaded files stay in place until the trash item is purged or expires), and owners and admins can restore it from Settings, Trash (platform.trash.restore). Deleting a personalization brings back the original system agent. System agents cannot be deleted (400 ai_agent_system_not_deletable). Members who are not viewers can delete; an agent restricted to some roles or members only by them and by owners and admins (403 ai_agent_access_denied). An agent that works in a seat of the CRM or Social Inbox AI Team cannot be deleted from outside the screen (409 ai_agent_in_live_seat). Outside the screen it requires a dry run and a confirm_token. 404 ai_agent_not_found. Module: Organization (organizations), even though the id starts with ai.; it is not available to API keys or OAuth tokens (none can be given write access to organizations).
Con una API key, este DELETE se ejecuta directo: el registro queda 30 días en la papelera y la respuesta trae su trash_item_id. Con un token OAuth, y por el MCP, pide dry_run → confirm_token.
Alcance
organizations:writey «Permitir eliminar» (organizations:delete en OAuth)
Permiso
Editar en el módulo
Tool del MCP
ai_agents_deleteEn la superficie completa; en la compacta, mb_execute_operation con id: "ai.agents.delete".
Costo declarado: hasta 4 lecturas y 1 escrituras por llamada (cuentan en el cupo diario).
Parámetros
agent_idstringrutarequerido
The agent id (from ai.agents.list).
Respuesta
oktrue
trash_item_idstring
The trash item this deletion left: the item_id of platform.trash.restore (POST /trash/{item_id}/restore). Missing if nothing went to the trash.
trash_item_idsarray<string>
Only when the deletion left more than one copy: all of them, the first being trash_item_id.
trash_expires_atnumber
When the copy leaves the trash for good (epoch ms): 30 days after the deletion.
Lists MB Suite's built-in AI agents available to the organization (the ones ai.agents.list leaves out), in the order of the AI team: key (what based_on_system_id takes to personalize or duplicate one), functional name and the human name the team shows, description, channel (in_app assists the team in the app; whatsapp_crm talks to CRM leads; social answers on social networks), category, provider and model, default_for (the CRM AI team position types that use it as their brain when the position has no agent of its own) and personalized, true when the organization has its own version that replaces it, with personalized_by, that agent's id (null when the caller cannot see it). Never their instructions nor their knowledge: they are MB Suite's. Filter with channel. Not paginated (a few dozen). Any member can read. Module: Organization (organizations), even though the id starts with ai.; any valid credential can read it.
Alcance
organizations:read
Permiso
Ver el módulo
Tool del MCP
ai_system_agents_listEn la superficie completa; en la compacta, mb_execute_operation con id: "ai.system_agents.list".
Costo declarado: hasta 140 lecturas y 0 escrituras por llamada (cuentan en el cupo diario).
Parámetros
channelenumqueryopcional
Only the system agents of this channel: in_app (assist the team in the app), whatsapp_crm (talk to CRM leads) or social (answer on social networks).
