AI Chat & Assistants

Relevant source files

The following files were used as context for generating this wiki page:

• packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/constants/chat-system-prompts.const.ts
• packages/twenty-server/src/engine/api/mcp/utils/build-mcp-server-instructions.util.ts
• packages/twenty-codex-plugin/AGENTS.md
• packages/twenty-codex-plugin/skills/develop-app/SKILL.md
• packages/twenty-apps/internal/twenty-partners/src/skills/twenty-lead-intro-call-summary/SKILL.md
• packages/twenty-server/src/engine/metadata-modules/ai/ai.exception.ts
• packages/twenty-front/src/modules/ai/components/AiChatTab.tsx

The AI Chat & Assistants system within Twenty provides an integrated conversational interface designed to manage CRM data, automate workflows, and assist developers in building and managing Twenty applications. It operates through a coordinated "Plan → Skill → Learn → Execute" loop, utilizing a combination of specialized skills (documentation/instructions) and executable tools.

This system spans from user-facing chat interfaces that handle standard CRM operations—such as record retrieval, analytics, and task management—to developer-focused agents that assist in scaffolding apps and modifying metadata.

Sources: packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/constants/chat-system-prompts.const.ts:3-13, packages/twenty-codex-plugin/AGENTS.md:7-14

Core Operational Logic: Plan-Skill-Learn-Execute

The AI assistant follows a strict four-step operational cycle for non-trivial tasks to ensure accuracy and prevent tool-call failures.

1. Plan: Identify user needs and determine the task domain (e.g., workflows, data, or metadata).
2. Skill: Load relevant documentation via load_skills to obtain correct schemas and patterns.
3. Learn: Discover specific tool schemas using learn_tools before execution.
4. Execute: Call execute_tool to perform the action based on the learned knowledge.

Sources: packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/constants/chat-system-prompts.const.ts:5-13

The Execution Flow

This diagram illustrates how the assistant transitions from a user request to actual execution.

The flow ensures that "Skills" (knowledge) are loaded before "Tools" (execution) are called.
Sources: packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/constants/chat-system-prompts.const.ts:31-35, packages/twenty-server/src/engine/api/mcp/utils/build-mcp-server-instructions.util.ts:30-34

Tooling and Skills Architecture

The system differentiates between Skills, which provide instructions and patterns, and Tools, which provide execution capabilities.

Categories of AI Tools

Tools are constructed with a specific grammar for CRM operations and extended for specialized logic.

Category	Tool Pattern / Grammar	Purpose
CRUD (Read)	find_many_{objects}, find_one_{object}, group_by_{objects}	Retrieval and analytics on CRM data.
CRUD (Write)	create_one_{object}, upsert_many_{objects}, delete_one_{object}	Modifying records. upsert_many is preferred for efficiency.
Metadata	get_object_metadata, create_field_metadata	Modifying the CRM schema itself.
Workflow	create_complete_workflow, activate_workflow_version	Automating processes within the CRM.
Action	http_request, send_email, code_interpreter	Performing side effects or external communication.

Sources: packages/twenty-server/src/engine/api/mcp/utils/build-mcp-server-instructions.util.ts:16-28

Critical Execution Rules

• Database vs HTTP: Database tools must be used for all internal CRM operations. http_request is strictly for third-party APIs.
• Destructive Operations: Tools like delete_one require the assistant to first count matching records and then wait for explicit user confirmation.
• Data Efficiency: Assistants are instructed to apply filters and use a default limit of 10 records to conserve context tokens.
• Record References: AI responses must use the exact format [[record:objectName:recordId:displayName]] for tool-returned records to ensure clickable links in the UI.

Sources: packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/constants/chat-system-prompts.const.ts:37-64, packages/twenty-server/src/engine/api/mcp/utils/build-mcp-server-instructions.util.ts:43-55

Specialized Developer Skills (Codex Plugin)

The Twenty Codex plugin provides targeted agents for the application development lifecycle.

Each skill owns specific task guidance and reference documentation.
Sources: packages/twenty-codex-plugin/AGENTS.md:16-24

Develop App Workflow

The develop-app skill emphasizes using the CLI for entity generation to maintain metadata integrity.

• Entity Creation: Uses yarn twenty dev:add to generate UUIDs and boilerplate.
• One-shot Sync: Synchronizes changes via yarn twenty dev --once. Watch mode is explicitly forbidden due to resource leakage.
• Validation: Enforces yarn twenty dev:typecheck and yarn lint after edits.

Sources: packages/twenty-codex-plugin/skills/develop-app/SKILL.md:46-64, packages/twenty-codex-plugin/AGENTS.md:28-30

Implementation Call Summarization

Specialized skills like twenty-lead-intro-call-summary utilize AI to extract structured data from messy ASR transcripts. This process transforms conversational audio into a "Deal One-Pager" used for partner matching and implementation scoping.

Summarization Process

1. Extract Facts: Identifies current CRM tools, pain points, and requirements.
2. Identify Complexity: Maps technical needs (Self-host vs Cloud, RLS, custom objects) to implementation complexity.
3. Partner Tiering: Determines if a deal needs an implementation partner based on scope and region.

Sources: packages/twenty-apps/internal/twenty-partners/src/skills/twenty-lead-intro-call-summary/SKILL.md:26-55

Error Handling and Constraints

The system includes specific exceptions and behavioral blocks to manage current limitations.

• AiException: A specialized exception class used for AI-related server-side errors.
• Dashboard Limitation: Assistants are currently instructed that AI-assisted dashboard building is a "coming soon" feature and should redirect users to creating views or running grouped analytics.
• Multi-metric Analytics: If a user requests multiple metrics, the assistant must run parallel group_by calls and merge the results manually.

Sources: packages/twenty-server/src/engine/metadata-modules/ai/ai.exception.ts:1, packages/twenty-server/src/engine/metadata-modules/ai/ai-chat/constants/chat-system-prompts.const.ts:25-29, packages/twenty-server/src/engine/api/mcp/utils/build-mcp-server-instructions.util.ts:49

The AI Chat & Assistants system serves as a bridge between the complex CRM metadata layer and the end-user, utilizing structured tool discovery and domain-specific skills to provide accurate, context-aware automation.