Help & Guides
Your guide to understanding and using the Alkimi platform.
Agents
Agents are the intelligent workhorses of the Alkimi platform, designed to transform how you interact with your data. Unlike static search tools, an Agent is a fully customizable AI entity that you configure to perform specific roles, ranging from a Socratic tutor guiding students through complex curriculum to a compliance officer verifying internal documents. Each agent is defined by its unique combination of knowledge, personality, and capabilities.
We call them "Agents" rather than just "Assistants" because they possess a higher degree of agency and capability. While an assistant might simply answer questions, an Alkimi Agent is engineered to actively process information, use tools, and reason through problems on your behalf. This choice also reflects our roadmap of constant improvement, as we continuously equip them with more automated capabilities and integrations. Grounded securely in your proprietary data, they don't just retrieve information; they understand it, apply it, and act upon it to drive your workflows forward.
Creating an Agent
When you create a new agent, you have two powerful ways to get started: using the AI Agent Builder or selecting a Template.
Create Agent
Enter a name and choose a starting point for your new agent.
Templates provide a pre-configured starting point for an agent, including its core instructions, personality, and variables.
AI Agent Builder
Describe what you need and AI will build it for you.
Browse Catalog
Explore the full catalog of all templates.
AI Agent Builder
The Agent Builder uses AI to configure your agent for you. simply describe what you want the agent to do in natural language.
AI Agent Builder
Describe what you want your agent to do, and AI will configure it for you.
The builder will analyze your request and automatically select the best template, model, and settings. It will even write the initial instructions for you.
Building Your Agent...
Our AI is analyzing your requirements and creating the perfect configuration.
Templates
Alternatively, you can browse our catalog of pre-configured templates. These cover a wide range of use cases, from education to customer support.
Template Catalog
Explore our pre-built agent templates.
Assignment Design Assistant
An innovative instructional designer that helps educators develop engaging, non-traditional assignments.
Exam Prep Assistant: Math & Logic
A specialist for exam preparation in subjects like math, logic, and computer science.
Learning Assistant
Guides students to discover answers on their own without giving them away.
Learning Assistant: Science
Helps students apply the scientific method and interpret data.
Profile
This is where you define the agent's core identity and appearance. The profile page is divided into several sections:
MA301: Division Algorithm - Profile
Settings
Manage the agent's core settings and chat features.
This message will be shown to the user when they start a new chat. Leave blank for no greeting.
Chat Features
Branding
Manage the agent's appearance for integrations.
Metadata
View the agent's read-only information.
Delete this agent
This will permanently delete the agent and all associated data.
- Settings: This is the command center for your agent's configuration.
- General: Set your agent's Name and define a Greeting Message (which can be auto-generated using AI) to welcome users.
- Chat Features: Toggle capabilities like Show Reasoning to reveal the agent's thought process, Enable Quoting for context, Enable Suggestions for follow-up questions, and the Math Keyboard for LaTeX input.
- Actions: Quickly Duplicate your agent, or use Import/Export to manage configurations as JSON files.
- Branding: Customize how your agent looks when embedded or shared. You can select a primary Theme Color, and the interface provides a real-time Preview of both the agent's and user's chat bubbles.
- Metadata: Access read-only system information, including the unique Agent ID, Creation Date, and Last Updated timestamp.
- Danger Zone: A protected area to permanently Delete the agent and all of its associated history and data. Warning: This action is irreversible.
Importing & Exporting Agents
The platform allows you to serialize your agent into a portable JSON format. This is perfect for:
- Backups: Saving snapshots of your agent's configuration.
- Sharing: Sending an agent template to a colleague.
- Versioning: Keeping track of different prompt iterations.
Configuration File
Included in export- Identity: Name, Greeting Message, Branding
- Brain: Model Selection, Context Budget, Full Instructions
- Behavior: Reasoning Settings, Tool Configurations
Environment Data
Excluded for security- Knowledge: Links to specific document collections
- Access: User permissions and member roles
- History: Past chat conversations and stats
How to Use
Exporting
Go to your agent's Profile tab. Click the Export button in the top right to download the JSON file.
Importing
Use "Import from File" when creating a new agent, or click Import on an existing agent's profile to overwrite settings.
Model Selection
Here you select the underlying Large Language Model (LLM) that powers your agent. Different models have different strengths, capabilities (like image understanding), and credit costs.
Assistant - Model
Choosing the Right Model
Select the underlying Large Language Model (LLM) that powers your agent. Different models have varying strengths, context windows, and capabilities (like image understanding). Learn more about credit costs.
Model
Select the underlying Large Language Model (LLM) that powers your agent.
Settings
Context Budget
Sets the max credits for model operations per message. Higher values allow more complex interactions.
Model Details
Gemini 2.5 Pro
Google - Gemini 2.5 Pro is Google's state-of-the-art AI model designed for advanced reasoning, coding, mathematics, and scientific tasks. It employs "thinking" capabilities, enabling it to reason through responses with enhanced accuracy and nuanced context handling.
Capabilities
Credit Cost per Message
- Model Selection: Choose from a variety of models (e.g., Gemini, Claude, GPT) categorized by tier (Free, Basic, Standard, Premium). Look for these icons in the list:
- Image: Indicates multimodal support (the model can "see" images and documents).
- Brain: Indicates reasoning support (the model can "think" through complex problems). It is either optional (transparent) or forced (opaque).
- Context Budget: Set the maximum "size" of each message in credits. This budget covers model-related costs including input context (history, knowledge, web content), reasoning, and output generation, but excludes separate tool operation costs.
It cannot be set below the model's tier minimum (e.g., 4 for Standard), while the maximum is based on the model's max context capabilities. When switching models, the system automatically calculates the budget to maintain the same context length. - Settings: Enable features like Reasoning (controls whether the agent's thought process is generated) and File Uploads (allowing users to upload images and PDFs in chats).
Model Details
The Model Details card provides a comprehensive technical breakdown of the selected model's performance, costs, and capabilities.
Model Details
Gemini 2.5 Pro
Google - Gemini 2.5 Pro is Google's state-of-the-art AI model designed for advanced reasoning, coding, mathematics, and scientific tasks. It employs "thinking" capabilities, enabling it to reason through responses with enhanced accuracy and nuanced context handling. Gemini 2.5 Pro achieves top-tier performance on multiple benchmarks, including first-place positioning on the LMArena leaderboard, reflecting superior human-preference alignment and complex problem-solving abilities.
Capabilities
Credit Cost per Message
Benchmarks
When comparing models, values are color-coded relative to your current configuration: Green indicates a better value (e.g., higher benchmark or lower cost), Red indicates a worse value, and Yellow indicates a difference that is not directly comparable.
Capabilities
This section defines the operational limits and features of the model.
Performance Metrics
- Context: The maximum number of tokens the model can process at once. Ranges from ~8k to 2M+ tokens depending on the specific model.
- Max Output: The maximum number of tokens the model can generate in a single response. Typically 4k to 8k, with some models reaching 64k+.
- Latency: The average time to first token (response start). Lower is better.
- Throughput: Speed of generation in tokens per second (t/s). Higher is better.
- Uptime: The reliability of the model provider's API over the last 30 days.
Feature Support
- Input: Supported modalities. Values:
Text,Image,Audio,Video. - Reasoning: Whether the model supports "Chain of Thought" or hidden reasoning steps.
- Structured Output: Ability to reliably output JSON matching a specific schema.
- Function Calling: Ability to select and execute tools/functions.
- Knowledge Cutoff: The date up to which the model's training data goes.
Credit Cost per Message
Understanding the credit consumption for your agent.
- Minimum Cost: The base cost to initiate a request (usually 1 credit).
- Tier Minimum: The minimum budget required by the model's tier (Basic: 4, Standard: 12, Premium: 40).
- Max Model Cost: The absolute maximum credits the model itself can consume for a single turn, based on your Context Budget.
- Additional Tool Costs: Potential extra costs if tools (like Web Search) are used during the turn.
Benchmarks
We track key industry benchmarks to help you compare model intelligence.
| Benchmark | Category | Description |
|---|---|---|
| AIME (24/25) | Math | American Invitational Mathematics Examination. Tests advanced problem-solving. |
| GPQA | Science | Google-Proof Q&A. Expert-level biology, physics, and chemistry questions. |
| Humanity's Last Exam | Reasoning | Hardest multidisciplinary questions designed to stump current AI. |
| SimpleQA | Factuality | Measures the model's ability to answer short, factual questions correctly. |
| MMMU | Vision | Massive Multi-discipline Multimodal Understanding. Tests image reasoning. |
| MRCRv1 | Long Context | Multi-Round Context Retrieval. Tests ability to find details in long conversations. |
| FictionLiveBench | Long Context | Evaluates narrative coherence and detail retention in long stories. |
Context Budget
The context budget is a per-agent setting that controls the maximum credits available for each message. It determines both how much context your agent can access (conversation history, knowledge base content, and web results) and how it can generate its response (reasoning and final answer). Think of it as the "size" of each conversation turn.
How It Works
The context budget directly affects two key aspects of your agent's performance:
- Input Context Size: Higher budgets allow your agent to consider more conversation history, more content from your knowledge base, and more web search results when formulating its answer. This means better context awareness but higher cost per message.
- Output Generation: The budget also covers the cost of generating the agent's response, including its reasoning process and the final answer. More complex reasoning or longer responses will consume more of the budget.
- Intelligent Allocation: Our system automatically distributes your budget across different content sources (history, knowledge, URLs) based on relevance, ensuring the agent gets the most important information within your budget constraints.
Tier-Based Context Budgets
Each model tier has a minimum required context budget. This budget, set by the agent owner, acts as a maximum cost per message. The actual cost is variable based on usage (but never less than 1 credit). You must set a budget that meets the tier's minimum, and you can set it higher for more complex tasks.
- Basic Models: Require a minimum context budget of 4 credits per message.
- Standard Models: Require a minimum context budget of 12 credits per message.
- Premium Models: Require a minimum context budget of 40 credits per message.
Note: The agent configuration interface will show you the available budget options for your selected model.
Choosing the Right Budget
Consider these factors when setting your agent's context budget:
- Task Complexity: Simple queries (like "What is X?") can work with lower budgets, while complex analysis or multi-step reasoning benefits from higher budgets.
- Knowledge Base Size: If your agent needs to search through large knowledge collections, allocate more budget to ensure relevant snippets aren't truncated.
- Conversation Length: For ongoing conversations where context from previous messages is important, higher budgets help maintain continuity.
- Response Detail: If you need comprehensive, detailed answers with step-by-step reasoning, ensure the budget allows for longer outputs.
- Cost Management: Remember that every message consumes credits up to your set budget. For high-volume use cases, consider starting with a moderate budget and adjusting based on results.
You can adjust the context budget at any time from your agent's Model Selection page. We recommend experimenting with different budgets to find the sweet spot for your specific use case. For detailed information on how context budget affects billing and credit consumption, see our Billing & Pricing documentation.
Instructions (Prompt Engineering)
The instructions are the set of instructions your agent follows. Effective prompt engineering is key to building a great agent. While you can write the entire prompt manually in the "Raw" editor, we recommend using the Context Studio, which provides a structured and intuitive way to build and manage your agent's instructions.
MA301: Division Algorithm - Instructions
AI Generated Configuration
The 'Learning Assistant: Math & Logic' template is a perfect match for helping someone learn number theory proofs. Its default settings are adopted directly.
You are an instructional aide for an {{class}} class. Your knowledge is limited to prerequisite mathematics and the provided course lecture notes. The current section is {{section_or_chapter}}.
Your primary goal is to guide students to the solution without providing the direct answer. Be encouraging, but always provide honest, precise feedback.
- Ask Probing Questions: Instead of giving information, ask questions to understand the student's thought process. Ex: "Which definitions from the notes seem relevant here?"
- Give Accurate, Constructive Feedback: Analyze the student's work carefully. If their reasoning is flawed, gently point it out.
- Stay on Topic: If a student uses a concept or theorem not covered in the notes up to {{section_or_chapter}}, gently steer them back.
- Mimic the Notes: Your formatting, process, notation, and terminology should closely match the style used in the lecture notes.
Note: Every new agent starts with a preloaded, general-purpose prompt, so it works out of the box. For more specific use cases, you can select from a library of templates (e.g., "Learning Assistant," "Customer Support Agent," or "HR Onboarding Assistant") or use the Context Studio for deeper customization.
The Context Studio
The Studio is designed to give you fine-grained control over your agent's behavior while providing a real-time preview of how your instructions will be formatted.
Building Blocks
Persona
"You are an instructional aide for a {{class}} class."
Tone of Voice
Sections (Structured List)
Guiding Principles:
- Ask probing questions instead of giving answers.
- Give accurate, constructive feedback.
Variables (System)
The {{class}} variable is automatically available.
Live Preview
Persona: You are an instructional aide for a MA301 class.
Tone: Encouraging, Direct, Thorough
Guiding Principles:
- Ask probing questions instead of giving answers.
- Give accurate, constructive feedback.
- Persona: This is the agent's core identity. A good persona is concise and sets the stage for all other instructions (e.g., "You are a helpful and witty customer support agent for a software company.").
- Tone of Voice: Select from a list of predefined tones to quickly shape your agent's personality and response style.
- Sections: These are the building blocks of your prompt. You can add, remove, and reorder sections to structure the agent's instructions. There are two types:
- Freeform: A simple text area where you can write paragraphs of instructions.
- Structured List: A hierarchical list editor that helps you organize complex rules or protocols into a clear, nested format.
- Add from Library: To speed up prompt creation, you can add pre-written, reusable sections from the library, covering common use cases like constraining the agent to its knowledge base or defining an escalation protocol.
- Variables: Use system variables (like
{{agent_name}}) or define your own custom variables (like{{course_name}}) to make your prompts dynamic and reusable. - Live Preview: As you build your prompt in the Studio, a live preview on the right shows you exactly what the final system prompt will look like, including how variables are resolved.
Best Practices for Prompting:
- Be Specific: Clearly define the agent's role, the task it should perform, and any constraints. Instead of "Summarize text," try "Summarize the following text into three bullet points, focusing on the key financial outcomes."
- Provide Examples: Use the structured prompt editor to give few-shot examples of desired input and output. This is one of the most effective ways to guide the model's behavior.
- Define the Persona: Tell the agent how to behave. For example:
"You are a helpful assistant. Your tone should be friendly and professional."
Knowledge
Connect your agent to one or more knowledge collections. This grounds the agent in your specific data, enabling it to answer questions based on the documents you've provided. An agent can access multiple collections simultaneously. See Context Limit & Cost below for more details on how connected collections affect performance.
MA301: Division Algorithm - Knowledge
Manage Knowledge Access
Select the knowledge collections this agent should have access to. The agent will use the information within the selected collections to answer user questions.
Context Limit
570 / 10,485Knowledge Collections
Context Limit & Cost
Each language model has a maximum "context window," which is the total amount of information it can consider at one time. The agent's Knowledge page displays a Context Limit bar that helps you visualize how much of the selected model's capacity is being used by the connected collections.
It's important to understand how this relates to your agent's Context Budget: the context window is the model's maximum capacity, while the context budget is how much of that capacity you're allocating per message (measured in credits). Even if your knowledge collections fit within the model's context window, the actual amount of knowledge used per message is controlled by your context budget and our intelligent allocation system.
The thresholds for Optimal, High, and Critical usage are not fixed; they are dynamically calculated based on the specific language model your agent is using. The calculation considers two key factors: the model's total context window size and its performance on industry-standard benchmarks that measure how well it can recall information from large amounts of text. This ensures the guidance is tailored to your model's capabilities.
Note: The context limit bar is an estimate based on the number of snippets (chunks of text) from your knowledge collections. It is not a direct measure of tokens. As a rough guide, 10 snippets are approximately equivalent to one standard A4 page of text.
- Optimal: The ideal range for reliable and fast responses.
- High: The model could potentially overlook some details.
- Critical: Increased risk of slow responses, hallucinations, or missing key data.
Exceeding the context limit will lead to poor performance, as the agent cannot consider all the information at once. Choosing a more focused Retrieval Strategy or using a model with a larger effective context window are effective ways to manage this.
Examples
The following examples show how the context limit is calculated for different types of models. The thresholds are based on the model's context window size and its performance on long-context recall benchmarks.
Balanced Model
Example: Anthropic Claude Sonnet 4
Max Capacity: 4k snippets
High-Capacity Model
Example: Google Gemini 2.5 Pro
Max Capacity: 10.5k snippets
Tools
Extend your agent's capabilities beyond its core knowledge by enabling tools. Using these tools will consume credits from your account; for a detailed breakdown, please see our Billing & Pricing documentation.
Note: All tools are disabled by default and must be explicitly enabled for each agent.
- Web Search: Allows the agent to perform real-time web searches. This tool can be configured in three ways:
- Implicit: The agent decides for itself when a web search is needed to answer a user's query.
- Explicit: The agent will only perform a web search when the user explicitly invokes it using `@web` in their message.
- Disabled: The agent cannot perform web searches.
- Web Browse: Enables the agent to "read" the content of a specific webpage you provide in a link.
- File Uploads: Allow your agent to receive and analyze files and images directly from users in the chat. When enabled from the agent's main settings page, users can upload documents, and the agent can read their content to answer questions or perform tasks. This feature is currently only supported on Gemini models. The maximum size and number of files that can be uploaded is determined by your agent's Context Budget. Supported formats include images (PNG, JPG, GIF, WEBP), documents (PDF, TXT, MD), and LaTeX files (.tex, .latex, etc.).
For detailed tips on how to get the most out of these tools, see the Using Tools section of the Chat documentation.
Rules
The Rules Engine is a powerful feature (currently under development) that allows you to define conditional rules to dynamically modify your agent's behavior. Based on triggers like user questions or specific conditions, you will be able to:
- Inject additional instructions on-the-fly.
- Include specific knowledge sources, overriding default search strategies.
- Force the use of a particular tool with custom instructions.
Permissions
Control who can interact with and manage your agent. Permissions are managed at both the organization level and the individual agent level. By default, all organization members have "User" access to new agents unless a different default is set.
For a deeper dive into our access control model, please see our Security Documentation.
- Default Access: You can set a default role that applies to all organization members who have not been granted explicit permissions. This can be set to "User" or "No Access".
- Explicit Permissions: You can grant specific members a role for this agent that overrides the organization default.
Agent Roles
Note: The roles listed below are the defaults provided for agents. Your organization's administrators can customize these permissions and create new roles to fit your specific needs.
Owner / Admin
Can fully configure, use, and manage permissions for a specific agent.
- Chat
- Read Settings
- Manage Settings
- Manage Permissions
- Delete Agent
Manager
Can edit the agent's settings and chat with it.
- Chat
- Read Settings
- Manage Settings
- Manage Permissions
- Delete Agent
Viewer
Can view the agent's settings and chat with it, but not make changes.
- Chat
- Read Settings
- Manage Settings
- Manage Permissions
- Delete Agent
User
Can see and interact with (chat with) a specific agent.
- Chat
- Read Settings
- Manage Settings
- Manage Permissions
- Delete Agent
Website Embed
The integrations page allows you to embed your agent as a chat widget on any website. This is perfect for customer support, website navigation, or lead generation. You have access to several settings to configure its behavior and appearance:
Setup & Appearance
- Embed Code: You can embed the agent using two methods: a simple
<iframe>tag for direct embedding, or a<script>tag for a floating chat widget. Both methods are provided for you to copy and paste. - Iframe Styling: When using the iframe method, you can customize its appearance by toggling a border, rounded corners, and a box shadow to match your site's design.
- Welcome Message: Customize the initial message the widget displays to visitors.
Performance
- Prefetching: For the fastest possible load time, you can enable aggressive prefetching, which starts loading the chat assets as soon as the page loads.
Interactive Tools
These tools create a dynamic, two-way interaction between your agent and the user on your website. When a user sends a message from your site, the agent can be given context about the page they are on and what they are looking at. In turn, when the agent responds, it can highlight elements on the page to guide the user's attention.
Note: These tools are only available when using the script-based widget embed. For security and privacy, these features are disabled by default and must be explicitly enabled in the agent's integration settings.
User Context
Spacer
Agent Action
Reading Page
Processing structure...
Highlighting
Executing command...
- Current Page Awareness: Allows the agent to see the webpage the user is currently on, providing valuable context for its responses.
- User View Mirroring: Lets the agent see what the user is interacting with, such as selected text. This helps the agent understand the user's focus without them having to explain.
- Interactive Highlighting: Grants the agent the ability to highlight elements on your webpage and scroll the user to them, making it an excellent tool for guiding users through your site.
Discord
This feature is currently under development. Soon, you'll be able to connect your agent to Discord, allowing it to interact with users in your servers.
Slack
This feature is currently under development. Soon, you'll be able to connect your agent to Slack, allowing it to interact with users in your workspace.
Teams
This feature is currently under development. Soon, you'll be able to connect your agent to Microsoft Teams, allowing it to interact with users in your organization.