AI Chat is Catalio’s built-in conversational interface. Open it from any page and speak naturally with an AI assistant that has full access to your requirements catalog, personas, journeys, initiatives, and more. The assistant can read existing records, create new ones, navigate to specific pages, and even pre-fill forms for you to review before saving.
Conversations
Each exchange with the AI happens inside a Conversation — a persistent thread that stores the complete message history. Conversations are private to you and scoped to your organization.
Key properties of a conversation:
| Field | Description |
|---|---|
title |
Auto-generated name based on message content (nil until generated) |
initiative_id |
Optional link to a specific initiative, scoping the conversation |
message_count |
Total messages exchanged (aggregated) |
needs_title |
True when the conversation has messages but no name yet |
Auto-Generated Titles
When you start a conversation, its title is blank. After the first back-and-forth exchange, Catalio automatically generates a descriptive name from the conversation content in the background. You might see “User Authentication Requirements Discussion” or “Payment Processing Journey Review” appear in your conversation history within a few minutes.
Linking to an Initiative
When you open the chat from inside an initiative, the conversation is linked to that initiative via initiative_id. This gives the AI context about the initiative’s scope, strategic intent, and connected entities — so it asks fewer setup questions and gives more relevant answers.
Messages
Every message has a source that indicates who sent it:
:user— messages you type into the chat interface:agent— responses from the AI assistant:system— internal boundary markers used by the conversation compaction engine (not visible in the UI)
AI responses stream in real-time: the complete flag is false while chunks are arriving and flips to true when the response finishes. If something goes wrong, error_message and error_occurred_at record what happened so you can retry.
The status_text field shows what the AI is currently doing while it works — for example, “Looking that up…” or “Searching requirements…”. This gives you live progress without waiting for the full response.
Interactive Blocks
Sometimes the AI needs a specific answer before it can proceed. Instead of asking a free-form question, it presents a clickable interactive block stored in interactive_blocks. There are three types:
choice— pick one option from a list (radio-style)multi_select— pick multiple options (checkbox-style)confirmation— yes or no decision
Click your answer directly in the chat panel — the AI reads your selection and continues without you needing to type a reply.
Tools the AI Can Invoke
The AI is not limited to conversation. During a response it can call tools that take action in Catalio on your behalf. All tool calls are visible in the UI so you always know what the AI did.
manage_entity
Creates, updates, or connects entities in your catalog. Supports all scopeable types:
requirement,persona,journey,jtbdpolicy,process,capability,componentuse_case,application
Example triggers: “Create a requirement for single sign-on”, “Update the checkout persona’s description”, “Connect this requirement to the Payment initiative”
manage_initiative
Creates or updates Initiatives. Fields include name, description, strategic intent, scope summary, process domains, start date, and target date.
Example triggers: “Create a new initiative for the Q3 onboarding project”, “Update the initiative target date to September”
navigate_to_page
Navigates your browser to a specific page inside Catalio. The AI validates the destination against an allowlist before navigating — external URLs and admin paths are rejected.
Example triggers: “Show me the requirements list”, “Take me to the checkout journey”, “Go to initiative settings”
propose_form_create
Pre-fills a creation form with suggested values, then waits for you to review and save. The AI never creates records without your approval on this path.
Example triggers: “Help me create a new requirement”, “Draft a persona for finance managers”
propose_form_edits
Pre-fills an edit form with proposed changes, then navigates you to the form to review before saving. You can accept, adjust, or iterate in chat before committing.
Example triggers: “Change the title of this requirement”, “Update the priority to high”, “Rename the checkout journey”
request_user_input
Presents an interactive question block (described above) when the AI needs structured input to continue.
Multi-Tenant Isolation
Every conversation and message is scoped to your organization via organization_id. You can only see conversations you own. Organization admins can read and manage all conversations in their org. Background jobs that generate titles and AI responses always operate within your tenant boundary.
Best Practices
Be specific about what you want. “Create a requirement for exporting user data as CSV, high priority, for the Finance persona” produces a better first draft than “add a data export requirement.”
Use initiative context. Open the chat from inside an initiative when your work is scoped to that initiative. The AI will use its context to fill in fields you’d otherwise need to describe.
Iterate in chat before saving. When the AI pre-fills a form, review the values in the chat first. Say “change the description to…” and the form updates live. Save only when the draft looks right.
Retry on errors. If the AI response shows an error banner, use the retry button. Transient LLM failures are common and usually resolve on a second attempt.
Ask questions freely. The AI can list records, explain fields, compare options, and walk through workflows. Use it as a research assistant, not just a form-filling shortcut.
Relationships at a Glance
| Entity | Relationship |
|---|---|
| Initiatives | A conversation can be scoped to one initiative |
| Requirements | Created or updated via manage_entity |
| Journeys | Created or updated via manage_entity |
| AI Skills | Determine the system prompt and behavior for each conversation |
Next Steps
- Explore AI Skills to understand how the AI selects its expertise for each message
- Learn about Document Extraction to see how uploaded files generate Change Proposals for human review
- See how Change Proposals provide the human-in-the-loop review workflow for AI-generated suggestions
Support
If conversations stop responding or errors persist after retrying, check the LLM provider configuration at Settings > LLM Providers. The AI uses the provider configured for your organization.