Using the AI Assistant

NOTE

The AI Assistant is a preview feature. Contact your Hydden Customer Representative to enable it in your tenant.

Overview

The Hydden AI Assistant is an intelligent helper integrated throughout the Hydden platform. It answers questions, provides guidance, analyzes identity data, and assists with troubleshooting—all using natural language conversations.

Configure the AI Assistant

Before using the AI Assistant, configure your AI provider, create agents, and optionally set up a knowledge base.

Set Up an AI Provider

Providers connect Hydden to AI services. You must configure at least one provider before using the AI Assistant.

1. Navigate to Configuration > Assistant.
2. Select the Providers tab.
3. Click + Add Provider.
4. Configure the provider settings:

Field	Description
Name	Enter a descriptive name for the provider (e.g., "OpenAI Production").
Provider	Select the AI provider from the drop-down.
Model	Select the model to use from the available models. Models that support non-chat endpoints display an endpoint label next to the model name.
Base URL	(OpenAI only) Custom API base URL for OpenAI-compatible endpoints. Leave empty to use the default OpenAI API (https://api.openai.com/v1). Use this field to connect to Azure OpenAI Service, local proxies, or other OpenAI-compatible providers.
Input cost per 1M tokens ($)	(Optional) Enter the input token cost for usage tracking. The value appears in session cost calculations.
Output cost per 1M tokens ($)	(Optional) Enter the output token cost for usage tracking. The value appears in session cost calculations.
Credential	Select or create a credential containing your API key.

5. Click Create.

Supported Providers and Models

Provider	Models	Notes
OpenAI	GPT-5, GPT-5 Mini, GPT-4.1, GPT-4.1 Mini, GPT-4	Requires OpenAI API key
Anthropic	Claude Opus 4.1, Claude Opus 4, Claude Sonnet 4.5, Claude Sonnet 4, Claude 4.5 Haiku	Requires Anthropic API key
Google AI	Gemini 2.5 Pro, Gemini 2.5 Flash, Gemini 2.0 Pro, Gemini 2.0 Flash	Requires Google AI API key
Grok (xAI)	Grok 4.0, Grok 4 Fast Reasoning, Grok 4 Fast Non-Reasoning, Grok Code	Requires xAI API key
Ollama	Llama 3.1, Llama 3, Gemma 3	Local deployment, no API key required

Create an API Key Credential

1. Navigate to Configuration > Settings > Credentials.
2. Click + Add Credential.
3. Select Account Password as the credential type.
4. Enter a Name (e.g., "OpenAI API Key").
5. Leave Username empty or enter a placeholder.
6. For Password, paste your API key from the provider.
7. Click Create.

Set Up an Agent

Agents are configured AI assistants with specific instructions and tools. Create agents for different use cases.

1. Navigate to Configuration > Assistant.
2. Select the Agents tab.
3. Click + Add Agent.
4. Configure the agent settings:

Field	Description
Name	Descriptive name (e.g., "Identity Analyst Agent").
Description	Describe what this agent does.
Provider	Select your configured AI provider.
Agent Type	Select the agent mode. Agentic (chat + tools) enables interactive conversations with tool execution (default). Completion (code autocomplete) optimizes the agent for inline code suggestions.
Embeddings	(Optional) Select a knowledge base collection.
Skills	(Optional) Add one or more skills the agent can invoke as tools. Skills are reusable task units with their own tools and embeddings. See Set Up Skills.
Parallel Tool Calls	Enable to allow concurrent tool execution.
System Prompt	Instructions that define the agent's behavior.

5. In the System Prompt editor, enter the agent instructions.
6. Click Create.

Example System Prompts

Identity Posture Agent:

# Identity Security Assistant
You are an identity security expert that helps users analyze their organization's identity posture.

Your capabilities include:
- Querying identity data to find users, accounts, and access
- Identifying security risks like dormant accounts or excessive privileges
- Generating compliance reports
- Recommending remediation actions

Always explain your reasoning and provide actionable recommendations.

Code Completion Agent:

# Sandboxed Python Code Assistant
You assist users by writing and debugging sandboxed Python scripts for Universal Collectors.

You have access to:
- Hydden module documentation (hydn, sql, rest, ldap, csv, json, xml)
- Example collection scripts
- Schema definitions

Provide complete, working code examples with comments explaining each section.

Set Up Skills

Skills are reusable AI task units. Each skill contains a name, description, and prompt instructions — plus an optional ZIP archive of supporting files. Agents call skills on demand, which keeps their own configuration simple.

1. Navigate to Configuration > Assistant.
2. Select the Skills tab.
3. Click + Add Skill.
4. Configure the skill:

Field	Description
Name	A short identifier for the skill (e.g., risk-analyzer). Use lowercase letters, numbers, and hyphens only. Names must not start or end with a hyphen. Maximum 64 characters. Agents use this name to call the skill.
Description	Explain what the skill does. Agents use this to decide when to invoke the skill. A description is required for the skill to be available to agents.
Prompt	Full instructions that guide the skill's behavior when it runs.
Resources	(Optional) A ZIP archive of supporting files — scripts, reference data, or asset files — that the prompt can reference. Upload a ZIP using Upload ZIP.
Additional Frontmatter	(Optional) Extra YAML fields to include in the exported SKILL.md frontmatter, beyond the name and description that are managed above. Use this to embed metadata such as compatibility, license, or version for consumers of the exported skill.

5. Click Create.

Import a Skill from ZIP

You can import a complete skill from a ZIP archive directly from the Skills list.

1. On the Skills tab, click Import Skill.
2. Select a .zip file.
3. If the ZIP contains a SKILL.md file, its frontmatter fields populate the skill automatically. The name and description fields fill their respective fields. Any extra frontmatter fields (e.g., compatibility, license) appear in Additional Frontmatter. The body text fills the Prompt field.
4. Review and click Save.

How Skills Work with Agents

Skills use progressive disclosure so agents only load what they need:

1. Discovery — When an agent starts a session, the names and descriptions of all assigned skills appear in the agent's context. The agent uses these to decide which skill fits the task.
2. Activation — When the agent picks a skill, it calls activate_skill to load the skill's full prompt instructions.
3. Resource access — If the skill has a resource archive, the agent can call read_skill_file to load individual files from the ZIP as needed.

This model keeps session context lean. Skills without a description are excluded — the agent cannot discover them.

To assign skills to an agent, add skill names to the Skills field when creating or editing an agent.

Duplicate a Skill

To create a variation of an existing skill:

1. Select the skill from the list.
2. Click the Duplicate icon.
3. Edit the copy and click Save.

Set Up a Knowledge Base

Knowledge base collections provide additional context to AI agents through semantic search.

1. Navigate to Configuration > Assistant.
2. Select the Knowledge Base tab.
3. Click + Add Collection.
4. Configure the collection:

Field	Description
Name	Descriptive name (e.g., "Internal App Documentation").
Description	Describe what this collection contains.
Provider	Select the embedding provider for vector search.
Default Top K	(Optional) Number of results to return per query. Default: 3.
Default Alpha	(Optional) Balance between semantic and keyword search. Values range from 0.0 (keyword only) to 1.0 (semantic only). Default: 0.7.
Default Min Score	(Optional) Minimum relevance score threshold. Results below this score are excluded. Default: no threshold.

5. Click Create.

Hybrid Search

Knowledge base queries use hybrid search, which combines semantic (vector) search with full-text keyword (BM25) search. The Alpha parameter controls the balance:

Alpha Value	Behavior
1.0	Pure semantic search — best for conceptual queries
0.7 (default)	Weighted toward semantic with keyword boost — best for general use
0.2	Weighted toward keyword — best for exact term matching

Semantic search finds conceptually similar content even when wording differs. Keyword search finds exact term matches. The hybrid approach improves recall for both types of queries.

Add Documents to a Collection

After creating a collection, add documents:

1. Select the collection from the list.
2. Click + Add Document.
3. Upload or paste the document content.
4. Specify the document type (Text, JSON, Markdown, PDF, CSV).
5. Click Create.

The AI Assistant uses these documents to provide context-aware responses about your specific systems.

Configure Legacy Prompts

Legacy prompts provide compatibility with external integrations like Slack.

1. Navigate to Configuration > Assistant.
2. Select the Legacy Prompts tab.
3. Configure tokens and prompts for legacy integrations.

---

Access the AI Assistant

The AI Assistant is available throughout the Hydden platform.

Global AI Assistant

Access from anywhere using the chat icon in the bottom right corner of any supported page.

Use for:

• General questions about the platform
• Identity data queries
• Documentation searches
• Learning how features work

Contextual Help

The AI Assistant provides context-aware help within specific modules:

Location	Available Assistance
Identity Posture Dashboard	Query identity data, generate reports, analyze risks
Global Search	Build complex queries, understand results
Data Sources	Troubleshoot collection issues, understand configurations
Universal Collector	Script writing, mapping assistance, schema analysis

For detailed instructions on using the AI Assistant with Universal Collector customization, see AI Assistant for Universal Collector.

---

Use the AI Assistant

Start a Conversation

1. Click the chat icon in the bottom right corner.
2. Type your question in the input field.
3. Press Enter or click Send.
4. Review the response and ask follow-up questions.

Write Effective Prompts

Be Specific:

• Bad: "Tell me about users"
• Good: "Show me users who have admin access but haven't logged in for 90 days"

Provide Context:

• Bad: "How do I fix this?"
• Good: "I'm getting a connection error when testing my SQL collector for the HR database. The error says 'connection refused on port 1433'"

Use Natural Language:

• "Which contractors still have access after their contract ended?"
• "Show me all privileged accounts in financial systems"

Multi-Turn Conversations

The AI maintains context across multiple exchanges:

You: "Show me users with admin access"
AI: [Returns list of 47 admin users]

You: "Which of those haven't logged in recently?"
AI: [Filters to 12 users based on previous context]

You: "Create an access review for their managers"
AI: [Generates review assignments]

---

Query Identity Data

Ask questions about your identity data in plain English.

Example Queries

Finding Privileged Access:

"Who has admin access to production systems?"
"Show me all users in the Domain Admins group"
"List service accounts with elevated privileges"

Identifying Risk:

"Show me accounts that haven't been used in 6 months but still have active access"
"Find users with access to both finance and IT systems"
"Which contractor accounts are past their end date?"

Compliance Questions:

"Generate a SOX compliance report for Q4"
"Show me evidence of quarterly access reviews"
"List all privileged accounts and their last login dates"

Generate Reports

Request reports using natural language:

You: "Create a report of all privileged accounts for the SOX audit"

AI: I've generated your SOX privileged access report:

    Report Summary:
    - Total Privileged Accounts: 89
    - Active (logged in < 30 days): 67
    - Inactive (30-90 days): 15
    - Dormant (> 90 days): 7

    Would you like me to:
    - Export to Excel?
    - Schedule this report monthly?
    - Add additional details?

---

View Session Data

Review AI Assistant interactions for audit and troubleshooting.

1. Navigate to Configuration > Assistant.
2. Select the Sessions tab.
3. View the list of AI sessions with:
   • Session timestamp
   • Agent used
   • User who started the session
   • Session cost (calculated from provider token pricing)
4. Click a session row and select the Actions icon.
5. View session details including:
   • Full conversation history
   • Tools invoked
   • Provider and model used
   • Total session cost

---

Best Practices

Getting Good Results

1. Start broad, then refine - Begin with general questions and narrow down.
2. Provide relevant context - Include system names, error messages, and requirements.
3. Ask for explanations - Request reasoning for recommendations.
4. Confirm understanding - Verify the AI understood your question before acting.

Security Considerations

• Do not share passwords or sensitive credentials in chat.
• Review AI suggestions before implementing changes.
• Use the AI within the platform; avoid copying sensitive data externally.
• All AI interactions are logged for audit purposes.

Understanding Limitations

The AI Assistant CAN:

• Answer questions about your identity data
• Suggest configurations and mappings
• Generate scripts and code
• Explain concepts and features
• Help troubleshoot errors
• Create reports and summaries

The AI Assistant CANNOT:

• Access data it doesn't have permission to see
• Make changes without your approval (for sensitive operations)
• Access systems outside of Hydden
• Replace security expertise for complex decisions

---

Troubleshooting

AI Assistant Not Available

If the chat icon does not appear:

• Verify the AI Assistant feature is enabled for your tenant.
• Check that an AI provider is configured.
• Confirm your user role has permission to use the AI Assistant.

AI Responses Are Not Helpful

If responses lack context or relevance:

• Ensure you have an agent configured with an appropriate system prompt.
• Add a knowledge base collection with relevant documentation.
• Provide more specific context in your prompts.
• Rephrase your question with more detail.

Provider Connection Errors

If you receive connection errors:

• Verify your API key credential is correct and not expired.
• Check that the provider service is available.
• Review the provider's rate limits and usage quotas.
• Try a different model or provider.

Session Errors

If sessions fail to save or resume:

• Check your network connection.
• Refresh the page and try again.
• Review session logs for error details.
• Contact support if the issue persists.

---

Related Topics

• AI Assistant Overview
• AI Assistant for Universal Collector
• Configure the Universal Data Source