AI Context
Teach Agents how your business works. Define your metrics, terminology, and preferences to tailor every answer to your organization.
Getting started
Before you add your context, gather the necessary information and navigate to the right place.
Find AI Context
Agents, including Global and Specialized Agents, use two layers of context: Organization and Project.
Access both from Project Settings > AI Controls.
What to gather before you start
Your business model, such as B2B, B2C, or marketplace.
Your North Star metric and how you define it.
Your fiscal year start date, if it isn't January.
Your key customer segments and how to identify them.
Event names for key actions, such as signup and purchase.
Property names that define segments, such as plan type and ARR.
Test or internal user identifiers to exclude.
Any deprecated events to avoid.
Understanding AI context
Context changes how Agents answer questions.
A user asks:
Show me our activation rate
I'll create a chart showing user activation. I'll define activated users as those who completed any event after signing up...
I'll show activation rate using your definition: users who triggered first_project_created within 7 days of signup, excluding @test.com emails...
Two levels of context
Applies to all projects. Use for company-wide standards.
Business model and KPI definitions.
Standard terminology.
Global filters, such as excluding test users.
Fiscal calendar rules.
Applies to one project. Use for product-specific details.
Product-specific events and funnels.
Metrics unique to this product.
Product-specific segments.
Overrides for org defaults when needed.
At runtime, Agents combine both context sources. Project context overrides organization context when they conflict.
What to write
Amplitude can't infer the following:
Business model: "B2B SaaS, annual subscriptions"
Key segments: "Enterprise = ARR > $50K"
Metric definitions: "Activation = first project within 7 days"
Date rules: "Fiscal year starts April 1"
Exclusions: "Filter out @test.com emails"
Amplitude understands the following:
Your event catalog and properties.
Top events by volume.
Official dashboards.
Saved cohort definitions.
Existing chart configurations.
Reference your existing cohorts and dashboards by name in any context you provide. For example:
Use the 'Power Users' cohort when asked about engaged users.
Amplitude includes their definitions by default.
Write good context
Structure your context with markdown so it's easy for Agents to parse.
## Use headings to separate sections.
- Use bullets for lists of items.
`backticks` Wrap event and property names.
**bold** Highlight key terms.
Business Overview: Your model and North Star metric.
Key Metrics: Activation, engagement, and retention definitions.
Segments: Customer tiers mapped to properties.
Do/Don't Rules: Defaults, filters, and things to avoid.
Date Rules: Fiscal year, week start, and default ranges.
Keep it under 10,000 characters. That's the limit for both org and project context. Focus on the 20% of information that covers 80% of questions your team asks.
Industry templates
Start with a template for your industry and customize it. These are complete examples you can copy and adapt.
Copy this template, replace the event and property names with your own, and adjust the definitions to match your business.
## Business Overview
B2B SaaS platform with annual subscriptions.
North Star: Monthly Active Workspaces (MAW)
## Key Metrics
- **Activation**: User triggers `workspace_created` within 7 days of `signup_completed`
- **Engaged**: 3+ sessions in last 7 days with at least one `feature_used` event
- **Expansion-ready**: `seat_utilization` > 80%
## Segments
- Enterprise: `plan_tier` = "enterprise" OR `arr` > 50000
- Mid-Market: `arr` between 10000 and 50000
- SMB: `plan_tier` in ("starter", "growth")
- Trial: `subscription_status` = "trial"
## Rules
DO:
- Default to last 30 days for time ranges
- Exclude `email` contains "@test.com" or `is_internal` = true
- Use `mrr_change` event for revenue analysis
DON'T:
- Include `environment` = "staging" or "development"
- Use deprecated: `old_signup`, `legacy_workspace_created`
## Date Rules
- Fiscal year starts February 1
- "This quarter" = current fiscal quarter
- Week starts Monday
Examples
See what makes AI Context effective and what pitfalls to avoid.
Be specific
## Key Metrics
- **Activation**: User triggers `project_created` event
within 7 days of `signup_completed`
- **Engaged User**: 3+ sessions in the last 7 days
- **Churned**: No activity for 30+ days
Help users understand activation and engagement.
Show relevant metrics when asked about user behavior.
Make sure to use appropriate time ranges.
Be concise
## Segments
- Enterprise: `plan_tier` = "enterprise"
- SMB: `plan_tier` = "starter" OR "growth"
- Trial: `subscription_status` = "trial"
## Filters
- Exclude: `email` contains "@test.com"
- Exclude: `is_internal` = true
When analyzing our customer base, it's important to
understand that we have several different types of
customers. Enterprise customers are our largest accounts
- they typically have the enterprise plan tier. Small
and medium businesses (SMBs) are customers who use our
starter or growth plans. We also have trial users who
are evaluating the product.
Include business context
## Business Model
B2B SaaS, annual subscriptions.
North Star: Monthly Active Workspaces (MAW)
## Fiscal Calendar
- FY starts April 1
- "This quarter" = current fiscal quarter
- Week starts Monday
We are a software company that sells to businesses.
Our product helps teams collaborate better.
We care about growth and revenue.
Use explicit do/don't rules
## Rules
DO:
- Default to last 30 days for time ranges
- Group by `platform` when comparing mobile vs web
- Use `Total Revenue` event for revenue metrics
DON'T:
- Include events where `environment` = "staging"
- Use deprecated events: `old_signup`, `legacy_purchase`
Be helpful and show relevant data.
Use appropriate filters when needed.
Be careful with sensitive information.
Define your terminology
## Terminology
- "Conversion" = `checkout_completed` event
- "Signup" = `account_created` (not `user_registered`)
- "Active" = user with 1+ events in last 7 days
## Naming Conventions
Events: snake_case (`button_clicked`)
Properties: camelCase (`userId`, `planType`)
Use the correct terminology for our company.
Use exact event names and correct casing.
Properties follow our naming conventions.
Best practices
Use exact event and property names with correct casing.
Be specific: "exclude email contains @test.com".
Put universal rules at the org level, and put overrides at the project level.
Test changes by asking questions before saving.
Keep a backup in your wiki or version control.
List events or properties. Amplitude already knows these.
Write vague instructions like "be helpful" or "use appropriate filters".
Create conflicting rules between org and project context.
Add edge-case rules that apply only to rare situations.
Make large changes without testing first.
Maintain context over time
Keep the following in mind to help maintain context.
Assign owners: Analytics lead for org context. PM or analyst for each project context.
Review regularly: Quarterly, after major launches, or when Agents give unexpected answers.
Change carefully: One change at a time. Test with real questions. Keep backups.
Frequently asked questions
Was this helpful?