Habilidades y agentes

import { defineSkill } from 'twenty-sdk/define';

export default defineSkill({
  universalIdentifier: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
  name: 'sales-outreach',
  label: 'Sales Outreach',
  description: 'Guides the AI agent through a structured sales outreach process',
  icon: 'IconBrain',
  content: `You are a sales outreach assistant. When reaching out to a prospect:
1. Research the company and recent news
2. Identify the prospect's role and likely pain points
3. Draft a personalized message referencing specific details
4. Keep the tone professional but conversational`,
});

• name es una cadena identificadora única de la habilidad (se recomienda kebab-case).
• label es el nombre para mostrar, legible para humanos, que aparece en la interfaz de usuario.
• content contiene las instrucciones de la habilidad — este es el texto que usa el agente de IA.
• icon (opcional) establece el icono mostrado en la interfaz de usuario.
• description (opcional) proporciona contexto adicional sobre el propósito de la habilidad.

import { defineAgent } from 'twenty-sdk/define';

export default defineAgent({
  universalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  name: 'sales-assistant',
  label: 'Sales Assistant',
  description: 'Helps the sales team draft outreach emails and research prospects',
  icon: 'IconRobot',
  prompt: 'You are a helpful sales assistant. Help users with their questions and tasks.',
});

• name es una cadena identificadora única del agente (se recomienda kebab-case).
• label es el nombre para mostrar que aparece en la interfaz de usuario.
• prompt es el mensaje del sistema que define el comportamiento del agente.
• description (opcional) proporciona contexto sobre lo que hace el agente.
• icon (opcional) establece el icono mostrado en la interfaz de usuario.
• modelId (opcional) reemplaza el modelo de IA predeterminado usado por el agente.
• responseFormat (opcional) establece la estructura de salida predeterminada del agente. De forma predeterminada es { type: 'text' } para texto de formato libre. Usa { type: 'json', schema } para forzar una salida JSON estructurada. Una llamada a runAgent() o un paso de IA de un flujo de trabajo puede solicitar una estructura diferente, que tiene prioridad.
• roleUniversalIdentifier (opcional) vincula el agente a un rol que define tu aplicación. Ese rol no debe otorgar más que el rol de la aplicación, o la compilación falla; consulta Roles de agente.
• modelConfiguration (opcional) activa las herramientas nativas del modelo, como lo hace la página de configuración del agente: { webSearch: { enabled: true }, twitterSearch: { enabled: true } }. Cada herramienta solo funciona con los modelos que la admiten. Omítelo para mantenerlas desactivadas.
• isSystem (opcional, el valor predeterminado es false) oculta el agente de las listas de agentes, como los agentes que Twenty crea para los pasos de IA de flujo de trabajo. Solo cambia lo que se muestra: los agentes de una aplicación solo se pueden cambiar mediante la aplicación, independientemente de lo que indique esta marca.

import { defineAgent } from 'twenty-sdk/define';

export default defineAgent({
  universalIdentifier: 'c4d5e6f7-a8b9-0123-cdef-456789012345',
  name: 'lead-scorer',
  label: 'Lead Scorer',
  prompt: 'Score the lead and explain your reasoning.',
  responseFormat: {
    type: 'json',
    schema: {
      type: 'object',
      properties: {
        score: { type: 'number', description: 'Lead score from 0 to 100' },
        summary: { type: 'string', description: 'Short reasoning for the score' },
      },
      required: ['score', 'summary'],
      additionalProperties: false,
    },
  },
});

• El esquema es un objeto plano: el type de cada propiedad debe ser un tipo primitivo (string, number o boolean). Los objetos anidados y los arrays no son compatibles.
• description (opcional) en cada propiedad guía al modelo sobre qué debe poner allí.
• required (opcional) enumera las propiedades que el modelo siempre debe devolver.
• additionalProperties: false (opcional) prohíbe cualquier propiedad que no esté declarada en properties.

import { defineMcpServer } from 'twenty-sdk/define';

import { GITHUB_CONNECTION_PROVIDER_UNIVERSAL_IDENTIFIER } from 'src/constants/universal-identifiers';

export default defineMcpServer({
  universalIdentifier: '0b6c4f7e-3d5a-4a8e-9a0d-6f1e2c3b4a01',
  name: 'github',
  label: 'GitHub',
  url: 'https://api.githubcopilot.com/mcp/',
  connectionProvider: {
    universalIdentifier: GITHUB_CONNECTION_PROVIDER_UNIVERSAL_IDENTIFIER,
  },
});

• name está en snake_case (letras minúsculas, dígitos y guiones bajos, comienza con una letra y tiene como máximo 32 caracteres) y es único en el espacio de trabajo. Sirve de prefijo para los nombres de las herramientas del servidor.
• url debe ser una URL HTTP o HTTPS.
• connectionProvider (opcional) hace referencia a un proveedor de conexión declarado por la misma aplicación. Las llamadas envían el token de acceso de esa conexión como un token Bearer. Omítelo para un servidor público.
• La URL no puede cambiar en una versión posterior mientras haya un proveedor de conexión vinculado, por lo que los tokens nunca se envían a otro host.
• Los espacios de trabajo pueden desactivar el servidor; una versión posterior de la aplicación conserva esa elección.
• Requiere "engines": { "twenty": ">=2.53.0" }.

import { runAgent } from 'twenty-sdk/logic-function';

const { threadId, runId, status, result, error, success } = await runAgent({
  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  input: 'Enrich House Ad <recordId>: fill empty fields from its listing URL.',
});

• input es una cadena o una lista de 1 a 100 mensajes ({ role: 'user' | 'assistant', content: string }). Un mensaje de user también puede incluir archivos adjuntos (consulta más abajo). Para mantener una conversación, pasa un thread en lugar de reproducir tú mismo los turnos anteriores.
• De forma predeterminada, la llamada espera al agente, que puede leer/actualizar registros por sí mismo mediante sus propias herramientas — runAgent() se resuelve una vez que finaliza la ejecución. Pase waitForCompletion: false para que se resuelva en cuanto se inicie la ejecución: status será entonces RUNNING y result: null, y la respuesta llegará a la conversación de threadId. Una ejecución que dure más de 15 minutos también se resuelve como RUNNING.
• El agente también puede pausarse hasta que cambie un registro o haya transcurrido algún tiempo. runAgent() se resuelve entonces con success: true, status: 'SUSPENDED' y result: null; el agente continúa por sí solo más tarde, y su respuesta llega a la conversación threadId. Una llamada a un thread cuyo agente sigue esperando falla hasta que termina.
• Cada llamada se almacena con su entrada y estado, además de su respuesta y uso cuando se completa, por lo que aparece en las ejecuciones del agente. Sin un thread, una llamada obtiene una conversación propia: threadId la denomina, y una llamada posterior nunca la ve.
• Una app solo puede ejecutar sus propios agentes.
• El rol predeterminado de la app debe conceder el indicador de permiso AI; agrega SystemPermissionFlag.AI a sus permissionFlagUniversalIdentifiers (o establece canAccessAllTools: true). Sin esto, runAgent() falla con un error de permisos.
• Establece un valor generoso de timeoutSeconds en la función de lógica: las ejecuciones de agentes pueden tardar varios segundos.
• status es COMPLETED con un result distinto de nulo cuando la ejecución finaliza sin esperar; SUSPENDED con success: true y result: null mientras espera; RUNNING con success: true y result: null cuando la llamada no esperó a la ejecución; FAILED con success: false y error que contiene el motivo (por ejemplo, cuando el espacio de trabajo se quedó sin créditos de IA durante la ejecución).

import { defineApplicationRole, SystemPermissionFlag } from 'twenty-sdk/define';

export default defineApplicationRole({
  universalIdentifier: 'b648f87b-1d26-4961-b974-0908fd991061',
  label: 'Default function role',
  // runAgent() requires the AI permission flag on the app's default role.
  permissionFlagUniversalIdentifiers: [SystemPermissionFlag.AI],
});

​

Envío de archivos con un mensaje

const { result } = await runAgent({
  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  input: [
    {
      role: 'user',
      content: 'What does this error screen say?',
      attachments: [{ fileId: uploadedFileId, filename: 'error.png' }],
    },
  ],
});

• Solo los mensajes de user pueden incluir archivos adjuntos. No se pueden representar en un turno de asistente, por lo que runAgent() los rechaza allí en lugar de omitirlos.
• Como máximo, 10 archivos adjuntos por mensaje.
• El fileId debe nombrar un archivo completamente cargado en el mismo espacio de trabajo, dentro de la carpeta agent-chat. Cualquier otra cosa hace que la llamada falle en lugar de responder silenciosamente sin el archivo.

​

Solicitar un resultado estructurado

const { result } = await runAgent({
  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  input: `Score this lead: ${JSON.stringify(lead)}`,
  responseFormat: {
    type: 'json',
    schema: {
      type: 'object',
      properties: {
        score: { type: 'number', description: 'Lead score from 0 to 100' },
      },
      required: ['score'],
    },
  },
});

​

Continuar una conversación

const { result, threadId } = await runAgent({
  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  input: 'What was the last touchpoint?',
  additionalInstructions: 'Answer in Slack markdown.',
  thread: { key: `${channelId}:${threadTs}`, title: 'Acme renewal' },
});

• Las claves están limitadas a tu aplicación y agente, por lo que dos aplicaciones nunca comparten una conversación. Solo los tokens de acceso de la aplicación pueden pasar un thread.
• input solo puede contener mensajes de user: la conversación ya contiene las respuestas del agente.
• Las additionalInstructions se proporcionan al modelo solo para esta llamada y no se almacenan, lo que es adecuado para instrucciones por solicitud, como reglas de formato o una fecha límite. También funcionan sin un thread.
• Cada ejecución se almacena como un turno con su estado, incluidas las que fallaron. Su uso se almacena cuando el agente regresa, incluso si se quedó sin créditos. Una ejecución fallida no forma parte de la conversación, por lo que la siguiente llamada no la ve.
• Las llamadas en el mismo hilo se ejecutan de una en una: una segunda llamada espera a que termine la primera, por lo que cada una ve los turnos anteriores a ella.
• Cuando los turnos se ejecutan como miembros diferentes (consulta más abajo), cada uno solo ve el texto de los turnos de los demás, nunca los resultados de sus herramientas, ya que se leyeron con los permisos de otra persona.

​

Ejecución en nombre de un miembro del espacio de trabajo

const { result } = await runAgent({
  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  input: 'How many open opportunities do we have?',
  runAsWorkspaceMemberId: '20202020-0687-4c41-b707-ed1bfca972a7',
});

• Un token sin usuario asociado puede designar a cualquier miembro. Una función lógica se ejecuta con uno, y lo mismo ocurre con los tokens generados mediante client_credentials o a partir de una clave de API.
• Un token emitido en nombre de un usuario, como el que recibe un componente de interfaz, solo puede designar al miembro propio de ese usuario.

​

Siguiendo una conversación

import {
  isAgentChatTurnEndEvent,
  listConversationMessages,
  streamConversation,
} from 'twenty-sdk/logic-function';

const conversation = {
  agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
  threadKey: `${channelId}:${threadTs}`,
};
const abortController = new AbortController();
let maxCatchupSeq: number | undefined;

// subscribe before reading the history, so nothing streamed in between is lost
for await (const event of streamConversation({
  ...conversation,
  signal: abortController.signal,
})) {
  if (event.type === 'keepalive' && maxCatchupSeq === undefined) {
    const { messages, streamCatchup } =
      await listConversationMessages(conversation);

    showMessages(messages);
    for (const chunk of streamCatchup.chunks) showChunk(chunk);
    maxCatchupSeq = streamCatchup.maxSeq;
  }

  if (
    event.type === 'stream-chunk' &&
    (event.seq ?? 0) > (maxCatchupSeq ?? 0)
  ) {
    // an AI SDK UIMessageChunk, such as { type: 'text-delta', delta }
    showChunk(event.chunk);
  }

  // the reply's save, or why it stopped, such as credits-exhausted
  if (isAgentChatTurnEndEvent(event)) {
    abortController.abort();
  }
}

• Los eventos son propios del chat: stream-chunk lleva un SDK UIMessageChunk y un seq, y notificaciones como message-persisted (un mensaje fue guardado: un miembro, o la respuesta, que lleva su ejecución turnId), credits-exhausted (la respuesta se detuvo cuando el espacio de trabajo corrió sin créditos), queue-updated o stream-error decir cuando para leer la historia de nuevo. Un keepalive viene una vez conectado, luego cada pocos segundos: lee la historia en la primera, ya que lo que pasó antes de está ahí.
• Para convertir chunks en mensajes como lo hace el chat, pipéalos en readUIMessageStream() del paquete ai.
• listConversationMessages() devuelve { mensajes, streamCatchup }: los mensajes guardados como AI SDK UIMessages, a medida que el chat los construye, y las porciones de una respuesta todavía fluyendo. Muestra esos trozos y luego omite trozos vivos cuyos seq es como máximo streamCatchup.maxSeq, ya que los repiten.
• runAgent() devuelve runId, el giro que abre la llamada: los mensajes de esa ejecución llevan como metadata.turnId. Una ejecución que espera en turnos posteriores de la conversación.
• El stream permanece abierto hasta que abortes su señal o romper, y arroja si la conexión cae: stream de nuevo para reanudar.
• Una aplicación sólo lee sus propias conversaciones. Turna un miembro abierto en otro lugar, como en el chat, muestra solo su texto en la historia, viva y en la siguiente carrera del agente : vive, sus otros trozos llegan como trozos message-metadata, así que seq permanece recolectado. Turna tu aplicación se ha ejecutado como un miembro (ver arriba) permanecen entera cuando lee por sí mismo.
• Requiere "engines": { "twenty": ">=2.56.0" }.

import { ai } from 'twenty-sdk/logic-function';

const { success, text, error } = await ai.generate({
  instructions: 'You qualify inbound leads for a B2B CRM.',
  input: `Is ${companyName} a good fit? Answer in one sentence.`,
});

• input es una cadena o una lista de mensajes { role: 'user' | 'assistant', content } .
• instructions (opcional) añade las instrucciones del sistema de llamada.
• modelId (opcional) elige el modelo. Sin ella, la llamada utiliza el modelo predeterminado del espacio de trabajo .
• responseFormat (opcional) funciona como en runAgent(). Con { type: 'json', schema }, el esquema se incluye en la propia solicitud al modelo, por lo que una respuesta JSON requiere una solicitud (más pasos de herramientas cuando un scope concede herramientas).
• scope (opcional) permite a la llamada utilizar la base de datos, como se describe a continuación.

• text es la respuesta de un texto, y null para una respuesta JSON.
• object es el resultado de una respuesta JSON, y null de otra manera.
• error explica una ejecución fallida, cuando success es false. Una ejecución que falla resuelve esta manera en lugar de lanzarla; una llamada que no puede iniciar una ejecución, tal como una con entrada no válida, lanza.
• runId identifica la ejecución registrada, con su modelo, uso y créditos.
• usage es { inputTokens, outputTokens }: lo que gastó la ejecución, incluyendo los pasos que terminaron antes de un fallo.

const { object } = await ai.generate({
  input: `Find the open opportunities of ${companyName} and rate their risk.`,
  responseFormat: {
    type: 'json',
    schema: {
      type: 'object',
      properties: { risk: { type: 'string' } },
      required: ['risk'],
    },
  },
  scope: {
    objectPermissions: [
      { objectUniversalIdentifier: OPPORTUNITY_UID, canReadObjectRecords: true },
    ],
  },
});

const abortController = new AbortController();

const { text } = await ai.generate({
  input: `Draft a follow-up email to ${companyName}.`,
  onChunk: (chunk) => {
    // an AI SDK UIMessageChunk, such as { type: 'text-delta', delta }
  },
  signal: abortController.signal,
});

• La llamada sigue la ejecución a través de la misma suscripción que streamConversation(): se suscribe primero, espera hasta que la suscripción esté en vivo, luego comienza la ejecución, por lo que no pierde ningún chunk.
• Los trozos son los propios del chat: póngalos en readUIMessageStream() desde el paquete ai para construir el mensaje.
• signal aborta la llamada: rechaza con el error de aborto y cierra la transmisión . La ejecución en sí misma continúa, y se registra como de costumbre.
• Una vez que el stream está vivo, un fallo solo detiene los pedazos: la llamada todavía se resuelve con el resultado de la ejecución. que se facturan de cualquier manera. La llamada se rechaza cuando la suscripción falla antes de activarse, por lo que la ejecución nunca comienza, o cuando onChunk genera una excepción.
• Una aplicación sólo sigue sus propias ejecuciones, así que onChunk necesita un token de aplicación.
• Requiere "engines": { "twenty": ">=2.56.0" }.