Custom Instruction
Custom Instructions are the persona-level rules embedded in each Agent Bill QuickSight Topic that control how Agent Bill responds to user queries. They define topic routing logic, keyword interpretation, business week alignment, and response behavior. Each Topic requires its own custom instruction tailored to the role it serves.
Routing Logic
Agent Bill persona instructions use a three-mode routing system to determine how to handle each user query:
DATA ONLY (Q Topics): For cost analysis and spending questions, the query is routed to a QuickSight Topic such as Cost Management, Container Allocation, Savings Plans Management, or Marketplace Spending. The Topic's semantic model interprets the natural language query and returns data from the underlying dataset.
ACTION/TASKS (MCP Server): For workflow actions like accepting spend cards, submitting budgets, claiming resources, or requesting reschedules, the query is routed to the MCP Server. These actions execute against the FinOps Center backend via GraphQL mutations with Cognito authentication.
COMBINED (Q Topics + MCP Server): For queries that require both data and action, such as comparing budget vs actuals and then submitting a reschedule, both the Topic and MCP Server are engaged in sequence.
Topic Routing
The custom instructions define which QuickSight Topic handles each type of query. The default topic is Cost Management, which handles all general spending and cost questions. When a user explicitly mentions containers, pods, tasks, or EKS/ECS, the query routes to Container Allocation. Marketplace-specific queries (marketplace, third party, vendor) route to Marketplace Spending, and savings plan queries route to Savings Plans Management. Agent Bill answers each question using one topic only and does not combine or cross-reference topics unless the user explicitly asks to compare.
For topics that are not available to a given role (for example, Marketplace, Savings Plans, or Credits for non-Financial Admin roles), the persona instructions redirect the user to contact their FinOps team for assistance.
Business Week Alignment
A critical component of every custom instruction is business week alignment. FinOps Center defines business weeks as Sunday through Saturday (not the default Monday-Sunday). Week 1 of each month runs from the 1st through the first Saturday. Middle weeks run Sunday through Saturday. The last week runs from the last Sunday through the last day of the month. The custom instructions include explicit month-by-month week definitions so Agent Bill uses exact date ranges rather than calculating them, which prevents off-by-one errors in weekly spend reporting.
Managing Custom Instructions via API
Custom instructions can be managed programmatically using the QuickSight API. Use DescribeTopic to retrieve the current custom instructions via the CustomInstructions.CustomInstructionsString field. Use CreateTopic or UpdateTopic to set or modify custom instructions. The instruction text has a character limit (approximately 3,200 characters), so instructions should be concise and structured. The FinOps Center automation framework handles topic creation and updates automatically, but custom instructions may need manual refinement as capabilities evolve.
Example: Topic Custom Instruction Template
The following is the current custom instruction template used across Agent Bill topics. This template covers topic routing, keyword interpretation, single topic rules, week lookup rules, business week definitions, and month-by-month date mappings.
Last updated