1 Open the AI Assist tab
Either edit an existing system, or click Create New System
The AI Assist tab is part of the System Definition Editor — it's available on every system, including brand-new ones. From the Systems list at /systems:
- To create from scratch with AI: click + Create New System. The editor opens at
/system-editor/new. Skip to the AI Assist tab without filling anything else. - To edit an existing system: click any system in the list. The editor opens with that system loaded.
Across the top of the editor you'll see a horizontal row of tabs. AI Assist is the new one, marked with a lightning-bolt icon.
Every system has its own AI Assist tab and its own chat history. Switching to another system gives you that system's chats — they don't bleed across.
2 Pick the agent
System Definition Assistant is auto-selected
At the top of the AI Assist panel you'll see two pickers — an Agent and a Chat history picker. The platform auto-selects the right agent for systems work; you almost never need to change it.
| Picker | What it controls |
|---|---|
| Agent | Which AI agent answers. The platform picks System Definition Assistant automatically; admins can publish other systems-aware agents and they appear here. |
| Chat history | Previous conversations with this system. — Start new chat — starts a fresh session. Older sessions are listed by their first prompt as a title. |
| Refresh / Delete | Refresh reloads the agent list. Delete next to the chat picker removes the currently selected chat from history. |
3 Describe what you want
Type a description, hit Send
The bottom of the panel has a single-line composer labelled "Describe the system you want…". The agent works for both create (no system loaded yet) and edit (an existing system is open) modes — it figures out which from context.
Good prompts include:
- The connector type if you know it: REST, SCIM, LDAP, ServiceNow, Azure, ODBC, "internal".
- The object types you want — users, groups, tickets, contacts.
- The auth model — OAuth client credentials, basic, API key, bearer.
- Any specific scopes / permissions the API needs.
The more concrete the prompt, the less back-and-forth. Naming the connector type and the operations you need usually produces a usable draft on the first try.
4 Watch the live stream
Tool cards, rationale, and a streaming reply
The agent doesn't just write YAML — it calls a set of system-authoring tools as it works. You'll see each tool invocation surface in the chat as a small card: when the tool is called, what arguments it received, and whether it succeeded.
Common tool calls you'll see:
| Tool | What the agent is doing |
|---|---|
systems.list_connector_types | Looking up which connector types are available in your tenant. |
systems.get_reference | Fetching a reference example for a known system (e.g. azure_ad, salesforce) to use as a template. |
systems.suggest_schema | Generating a draft schema for an object type based on the connector. |
systems.validate | Running the draft through the schema validator before returning. Catches missing required fields, malformed paths, etc. |
systems.compare | (Edit mode) showing what's changed between current and proposed YAML. |
If the stream is going somewhere unhelpful, click Cancel to abort. You can also Retry the last prompt — useful if the model got distracted by an irrelevant tool call.
5 Review the system card
The structured preview at the bottom of the reply
When the agent finishes, the assistant message ends with a system card — a structured summary of the YAML it generated. The card is your read of what's about to land in the editor.
📦 entraid_user_provisioning
What to check on the card:
- Name matches what you asked for and follows your tenant's slug conventions.
- Connector type is the one you wanted (REST vs SCIM vs Internal).
- Object types chips list every object the agent included. Missing one? Just ask in chat.
- Validated chip — green ✓ validated means the agent ran
systems.validatebefore returning. If it's missing or red, the YAML may have schema issues. - Preview YAML — click to expand the full text inline before you commit to loading it.
6 Load into editor & save
The first valid system auto-loads to the YAML editor
By default, the moment the agent emits a complete, parseable YAML block, the editor switches to the YAML Editor tab and the new content is dropped in. The form is marked dirty — nothing is persisted yet.
It only places the YAML into the editor. The system isn't actually changed in the platform until you press Save System. Closing the tab discards the AI's draft.
Use Load into editor to re-apply
If you've manually edited the YAML and want to start over from the AI's draft, click 📥 Load into editor on the system card. It reloads the original generated YAML in one click. You can do this any number of times — the chat keeps the draft.
Switch to YAML Editor → review → Save System
The cleanest review workflow:
- Stay on YAML Editor after auto-apply.
- Read top to bottom. Pay particular attention to
connection.base_url, any${secret://…}placeholders, and command paths. - Replace placeholders with real env-var or Vault references.
- Optionally jump to the Connection tab and click Test Connection first.
- Press Ctrl+S or click Save System.
The agent uses ${secret://...} placeholders for credentials, but always double-check there's no plaintext secret hiding in the YAML before you save.
7 Edit an existing system
Ask for changes — the agent receives the current YAML
Open any saved system, switch to AI Assist, and just describe the change you want. Behind the scenes the assistant gets your current YAML embedded in the prompt, so it knows exactly what it's editing.
Examples:
- "Add a search_tickets command that takes a query string and returns the 50 newest results."
- "Switch the auth from API key to OAuth2 client credentials with the
tickets.readscope." - "Add a new object type contract with create / update / list commands."
- "Change the rate limit to 50 requests per second per user."
The reply includes the complete updated YAML — not a patch. The editor swaps it in wholesale; your existing fields that weren't touched are preserved.
If the result isn't quite right, just keep chatting — "make the parameter optional", "use POST instead of GET". Each turn returns a fresh, complete draft.
8 Resume a previous chat
Chats are remembered per system
Every chat is saved automatically in your browser, scoped to the system you were editing. Closing the tab, navigating to another system, or refreshing the page won't lose work — the next time you open AI Assist on this same system, the chat picker shows your previous sessions, titled by their first prompt.
- The chat picker hides itself when there are no prior chats — only one click to start your first conversation.
- Up to 20 sessions per system are kept; oldest are pruned automatically.
- Click Delete next to the picker to remove the currently loaded session.
- Start fresh anytime via — Start new chat — in the picker.
Sessions are stored in localStorage on the browser you're using. They don't sync across devices and aren't visible to other users — even on the same system. If two admins iterate on the same connector they each have their own chat.
9 Tips, safety, and limits
Get the most out of the assistant
| Tip | Why |
|---|---|
| Always review the YAML before Save | Auto-apply is convenient, not a commitment. Read at minimum the connection block and any commands that mutate data. |
| Keep prompts focused | "Add one command" beats "make this system better". Smaller asks → smaller, easier-to-review diffs. |
| Test the connection after big changes | The agent can't actually call your API. Run Test Connection on the Connection tab before relying on the new YAML. |
| Use Insert Example as a fallback | If the assistant misunderstands, switch to the YAML Editor's Insert Example dropdown for a known-good template you can edit by hand. |
| Cancel runaway streams | If the agent fixates on a tool that isn't producing useful data, hit Cancel and rephrase the prompt. |
The conversation goes to the AI service. Use ${secret://path} placeholders or environment variables in your prompt — the agent understands them and will keep them as placeholders.
Limits worth knowing
- Auto-apply happens once. If you want to re-load the AI's draft after manual edits, use the Load into editor button on the system card.
- The assistant doesn't auto-save. Every persistence step is an explicit click on Save System.
- It can't run your API. The agent generates definitions; testing is on you (Connection → Test Connection, or the Test System modal).
- It works inside the editor only. There's no "Generate from prompt" entry point on the systems list yet — open or create a system first.
From now on, "create a connector" can be a one-sentence prompt followed by a YAML review. The grunt work of remembering the schema, command shapes, and auth blocks is the assistant's problem.