1. Getting Started 

Applies to:   All Users    

What is Kernaro Assist? 

Kernaro Assist is a desktop add-in for Enterprise Architect (EA) that brings AI-powered assistance directly into your modeling environment. You can: 

• Chat with AI — Ask questions about your EA model, get explanations, and receive guidance 

• Run Intelligent Agents — Automate tasks like generating documentation, reviewing models, or creating elements 

• Edit Models with AI — Let the AI create, modify, or organize EA elements and diagrams for you 

Prerequisites 

Requirement	Details
Enterprise Architect	Sparx Systems Enterprise Architect must be installed
Kernaro Assist Add-in	The Assist add-in must be installed and enabled in EA
Activation	Either a Hub connection (OIDC login) or a local license file
Network (Hub mode)	Network connectivity to your Kernaro AI Hub server
Assist Access (Hub mode)	Your Hub administrator must have granted you Assist access

Two Ways to Use Assist 

Mode	Description	Best For
Hub-Connected	Log in through Kernaro AI Hub. Your role determines which features are available. Shared agents from your team are accessible.	Teams and organizations with centralized management
Standard License	Use a local license file. Full access on local repositories. No Hub connection required.	Individual users or offline environments

2. Connecting to Kernaro AI Hub 

Applies to:   All Users    

How to Connect 

1. Open Enterprise Architect and load your EA model (repository). 

2. The Kernaro Assist add-in will detect the Hub-connected configuration and display a login window inside EA. 

3. Enter your Hub credentials (username and password) in the login page. 

4. Kernaro AI Hub verifies your identity and checks that you have Assist access. 

5. Once authenticated, the Assist panel becomes active. Your available features depend on your assigned role (see Section 3). 

Tip: Automatic login 
After your first successful login, Assist stores a secure token so you won’t need to log in again until the token expires or is revoked by your administrator. 

Cannot connect? 
If you see an error when trying to connect, check: 
• Your Hub server is reachable (check network/VPN) 
• Your administrator has granted you Assist access 
• Your account is active in Hub 
• There are available Assist seats on your organization’s license 

3. Understanding Your Role 

Applies to:   All Users    

When connected to Hub, your administrator assigns you one of three roles. Your role determines which features you can access in Assist. 

Role Comparison 

Feature	Admin	Write	Read-Only
Connect to Hub	✓	✓	✓
Chat with AI (ask questions)	✓	✓	✓
Chat modes (Plan / Ask-to-Edit / Auto-Edit)	✓ All modes	✓ All modes	✗ No modes
Use shared agents	✓ All agents	✓ Assigned only	✗
Write tools (create/edit elements)	✓	✓	✗
Create agents	✓	✗	✗
Publish agents to Hub	✓	✗	✗
Manage MCP servers	✓	✗	✗
Settings	Full access	Full access	Default model only

How do I know my role? 
Your role is displayed as a badge in the Assist panel header after you connect. If you need a different role, contact your Hub administrator. 

What Each Role Means 

Admin 

Full control over all Assist features. You can create and publish AI agents, manage MCP tool servers, configure settings, and use all chat modes. You can also manage agents and users in the Hub Admin UI. 

Regular (Write) 

You can use the AI to both read and modify your EA model. You have access to all chat modes and can run shared agents that your administrator has assigned to you. However, you cannot create new agents or manage MCP servers — those are admin-only capabilities. 

Regular (Read-Only) 

You can chat with the AI to ask questions about your model, get explanations, and analyze elements. The AI will never modify your model. Edit modes, agents, write tools, and MCP servers are not available to you. 

4. Using AI Chat 

Applies to:   All Users    

The AI Chat is the primary way to interact with Kernaro Assist. You type messages in natural language and the AI responds with answers, analysis, or actions on your EA model. 

How to Start a Chat 

6. Open Enterprise Architect with your model loaded. 

7. Navigate to the Assist Chat panel (accessible from the Kernaro menu or the Executions window). 

8. Type your question or request in the chat input box at the bottom. 

9. Press Enter or click Send to submit your message. 

10. The AI processes your request and responds. Responses stream in real-time. 

What You Can Ask 

Type of Question	Example	Available To
Explain an element	“What does the OrderService class do?”	All
Analyze the model	“List all classes in the Payment package”	All
Find issues	“Are there any orphaned elements without connections?”	All
Generate documentation	“Write a summary of the User Management component”	All
Create elements	“Create a new class called PaymentGateway in the Payment package”	Write / Admin
Modify elements	“Add an attribute ‘amount’ to the Invoice class”	Write / Admin
Create diagrams	“Create a class diagram showing Order, Customer, and Product relationships”	Write / Admin

Chat Sessions 

Your conversations are organized into chat sessions. Each session keeps its conversation history so the AI remembers context from earlier messages. 

• New session: Click the “+” button to start a fresh conversation 

• Switch sessions: Click on a previous session in the session list to continue it 

• Delete sessions: Right-click a session to remove it 

Tip: Be specific 
The more specific your request, the better the AI’s response. Instead of “fix my model”, try “Add a ‘createdDate’ attribute of type DateTime to the Customer class in the CRM package.” 

5. Chat Modes: Plan, Ask-to-Edit & Auto-Edit 

Applies to:   Write    Admin    

When the AI needs to modify your EA model (create, edit, or delete elements), it follows one of three modes. You choose the mode based on how much control you want. 

Read-Only users: 
This section does not apply to you. The mode selector is hidden for Read-Only users since the AI cannot modify the model on your behalf. 

Mode 1: Plan Mode 

Aspect	Details
Safety Level	Safest — Nothing happens until you approve
How It Works	The AI creates a detailed plan of all changes, then waits for your approval before executing anything.
Best For	Complex changes where you want to review everything before it happens

Steps: 

11. You describe what you want changed (e.g., “Reorganize the Data Access layer”). 

12. The AI analyzes your model and creates a detailed plan listing every change it will make. 

13. Review the plan. You see exactly what will be created, modified, or deleted. 

14. Click Approve to execute the plan, or Reject to cancel. 

15. If approved, the AI applies all changes to your EA model. 

Mode 2: Ask-to-Edit Mode 

Aspect	Details
Safety Level	Balanced — You approve each change individually
How It Works	The AI asks for your permission before each individual edit. You approve or reject each one as it works.
Best For	When you want fine-grained control over each change

Steps: 

16. You describe what you want changed. 

17. The AI begins working and encounters a write operation (e.g., “Create element X”). 

18. An approval dialog appears showing the tool name and parameters. 

19. Click Approve to allow this specific change, or Reject to skip it. 

20. The AI continues to the next operation and asks again. This repeats for each change. 

Approval timeout: 
The approval dialog has a 30-second timeout. If you don’t respond, the operation is skipped and the AI continues. 

Mode 3: Auto-Edit Mode 

Aspect	Details
Safety Level	Fastest — AI applies all changes automatically
How It Works	The AI automatically applies all changes without asking for approval. No interruptions.
Best For	Routine tasks where you trust the AI’s output and want maximum speed

Steps: 

21. You describe what you want changed. 

22. The AI works through the request and applies all changes automatically. 

23. You see the results in the chat and in your EA model. 

Use with care: 
Auto-Edit mode makes changes without confirmation. Make sure you have a backup or version control before using this mode for large-scale changes. 

How to Switch Modes 

Use the mode selector dropdown in the chat panel (typically near the chat input). Select your preferred mode before sending your message. You can change modes between messages. 

6. Working with Agents 

Applies to:   Write    Admin    

Agents are pre-configured AI assistants designed for specific tasks. Instead of writing detailed prompts every time, you run an agent that already knows what to do. 

Read-Only users: 
Agents are not available for Read-Only users. 

Types of Agents 

Agent Type	Description	Who Can Use
Local Agents	Created by an admin on this machine. Only visible in this Assist installation.	Admin
Shared Agents	Published to Hub and assigned to you by an admin. Available across the team.	Write / Admin

Running a Shared Agent 

24. Open the Agents panel in Assist. 

25. Browse the list of available agents. You’ll see agents that have been assigned to you. 

26. Select an agent and review its description to understand what it does. 

27. Click Run to execute the agent on your current model. 

28. The agent processes your model and produces results (which may include creating or modifying elements, depending on the agent and your permissions). 

Creating Agents (Admin Only) 

Applies to:   Admin    

Admins can create custom agents using the Agent Wizard: 

29. Click Create Agent in the Agents panel. 

30. Step 1 — Details: Enter the agent name, description, and AI prompt template. Select the LLM model to use. 

31. Step 2 — Tools & Configuration: Choose which tools the agent can use (e.g., element creation, diagram tools, script execution). 

32. Step 3 — Event Bindings: Optionally bind the agent to EA events (e.g., “run this agent whenever a new element is created”). 

33. Click Save to create the agent. 

Event-Agent Bindings 

Agents can be triggered automatically by EA events: 

• OnPostNewElement — Runs when a new element is created 

• OnPreDeleteElement — Runs before an element is deleted 

• And other EA lifecycle events 

Event bindings have a priority (which agent runs first) and optional conditions (only run for specific element types). 

7. Publishing Agents to Hub 

Applies to:   Admin    

Once you’ve created and tested an agent locally, you can publish it to Hub so other users on your team can use it. 

How to Publish 

34. Open the Agents panel and select the agent you want to publish. 

35. Click the Sync to Hub button (visible only for Admin users). 

36. Assist uploads the agent definition (name, prompt, tools, configuration) to Hub. 

37. The agent now appears in the Hub Admin UI under Published Agents. 

Assigning the Agent to Users 

38. Open the Hub Admin UI in your web browser. 

39. Navigate to Published Agents. 

40. Click on your published agent to open its details. 

41. Click Assign Users and select which users should have access. 

42. Only users with Write or Admin access can be assigned. Read-Only users are not eligible. 

43. Assigned users will see the agent in their Assist on the next sync cycle. 

Managing Published Agents 

Action	Who Can Do It	Effect
Enable / Disable agent	Any admin	Disabled agents are hidden from all users until re-enabled
Assign users	Owner only (the admin who published)	Selected users can see and run the agent
Update agent	Owner	Re-publish to update the Hub copy; users get the update on next sync
Delete agent	Owner	Removes the agent from Hub; no longer available to assigned users

8. Managing MCP Servers 

Applies to:   Admin    

MCP (Model Context Protocol) servers provide additional tools that the AI can use. Admins can add external MCP servers to extend Assist’s capabilities beyond the built-in EA tools. 

What Are MCP Servers? 

MCP servers are external tool providers that follow the Model Context Protocol. They can provide tools for: 

• Custom code generation 

• External API integration 

• Specialized model validation 

• Document generation 

• And more 

Adding an MCP Server 

44. Open the Settings panel in Assist. 

45. Navigate to the MCP Servers (or Tools) tab. 

46. Click Add MCP Server. 

47. Enter the server details: name, connection type (stdio or HTTP), command/URL, and any authentication credentials. 

48. Click Save. Assist will discover the tools provided by the server. 

49. The new tools become available to the AI in chat and agent execution. 

Note: 
Write users can use tools from MCP servers configured by an admin (via shared agents in chat), but they cannot add, edit, or delete MCP server configurations themselves. 

9. Settings & Configuration 

Applies to:   All Users    

Settings Access by Role 

Setting	Admin	Write	Read-Only
Default Chat Model	✓	✓	✓
LLM Model Configuration (add/edit providers)	✓	✓	✗
MCP Server Configuration	✓	✗	✗
Workspace Settings	✓	✓	✗
Python Execution Settings	✓	✓	✗
Logging Settings	✓	✓	✗

Selecting a Default Chat Model 

All users can choose which AI model to use for chat conversations: 

50. Open Settings from the Kernaro menu. 

51. Go to the Chat Agent tab. 

52. Select your preferred model from the dropdown (e.g., GPT-4, Claude, Azure OpenAI). 

53. Click Save. New chat sessions will use this model. 

10. Using Standard License Mode (No Hub) 

Applies to:   License Mode    

If your organization does not use Kernaro AI Hub, you can use Kernaro Assist with a local license file. 

How License Mode Works 

Repository Type	Access Level	What You Can Do
Local EA Repository  (e.g., .eap, .eapx, .qea files)	Full Access	All features available: chat, all modes, agents, tools, settings
Shared / Cloud Repository  (e.g., SQL Server, PostgreSQL)	Read-Only	Chat and analysis only. Write tools are not available. AI cannot modify the model.

Key Differences from Hub Mode 

• No role restrictions — You have full access on local repositories (no admin/write/read-only roles) 

• No shared agents — Agent sharing requires Hub. You can only use agents you create locally. 

• No Sync button — Publishing agents to Hub is not available 

• Shared repos are read-only — When you connect to a shared database repository, write operations are blocked for safety 

Activating with a license file: 
Place the license file in the configured location and restart Enterprise Architect. Assist will detect the license and activate automatically. 

11. Frequently Asked Questions 

General 

Q: How do I know which role I have? 

Your role is displayed as a badge in the Assist panel header after you connect to Hub. You can also check by going to Settings — if you can see all tabs, you’re Admin or Write. If you only see the default model selector, you’re Read-Only. 

Q: Can I change my own role? 

No. Roles are assigned by your Hub administrator. Contact your administrator if you need a different access level. 

Q: What happens if my access is revoked while I’m using Assist? 

Your current session will continue until the next time Assist checks with Hub (within a few minutes). After that, you’ll be prompted to re-authenticate, and if your access has been removed, you’ll receive an access denied message. 

Chat & AI 

Q: Can the AI see my entire EA model? 

The AI can access the elements, diagrams, packages, and relationships in your current repository through the built-in tools. It reads data on-demand as needed to answer your questions. 

Q: Is my data sent to external servers? 

Chat messages are processed by the configured LLM provider (e.g., OpenAI, Anthropic, Azure OpenAI). Your model data is sent to the LLM as part of the conversation context. Consult your administrator about which LLM provider is configured and their data handling policies. 

Q: Can I undo changes made by the AI? 

Enterprise Architect has its own undo functionality for some operations. For important models, we recommend using EA’s baseline or version control features before making large AI-driven changes. Using Plan mode lets you review all changes before they are applied. 

Agents 

Q: I’m a Write user. Why can’t I see the “Create Agent” button? 

Agent creation is an Admin-only feature. Write users can run shared agents assigned to them, but cannot create new ones. Contact your administrator if you need a custom agent. 

Q: How often do shared agents sync from Hub? 

Assist syncs with Hub at regular intervals. When an admin publishes or updates an agent and assigns it to you, you’ll receive the latest version on the next sync cycle. You can also manually trigger a sync by reopening the Agents panel. 

Troubleshooting 

Q: I get “ADMIN_ROLE_REQUIRED” when trying to create an agent or MCP server. 

This means you are logged in as a Write or Read-Only user. Agent creation and MCP server management require Admin access. Contact your Hub administrator. 

Q: I get “assist_access_denied” when connecting. 

Your Hub administrator has not granted you Assist access, or your access was revoked. Contact your administrator to request access. 

Q: I get “ASSIST_SEAT_LIMIT_EXCEEDED” when connecting. 

Your organization has used all available Assist seats on the license. Contact your administrator to either free up a seat or upgrade the license. 

Q: Chat is working but the AI can’t modify my model. 

This happens when: 

• You are a Read-Only user (write tools are not available) 

• You are in License mode connected to a shared repository (write tools are stripped for safety) 

• The mode selector is not set to a write mode (Plan, Ask-to-Edit, or Auto-Edit)