Persona Instructions Guide

How Agent Bill's persona instruction system works — routing logic, topic assignments, template structure, and API management.

Agent Bill uses a persona instruction system to deliver role-specific AI assistance within FinOps Center. Each persona instruction is a structured text block embedded in a QuickSight Topic that controls how Agent Bill responds to a specific user role. The instructions define the agent's identity, data scope, query routing logic, available topics, and business context. This page documents the structure, routing logic, per-role configuration, and management of persona instructions.

How Persona Instructions Work

Persona instructions sit within QuickSight Topics and are delivered to Agent Bill through the Amazon Quick Suite architecture chain: Dataset (with RLS) → Topic (with persona instructions) → Space (topics + MCP actions) → Chat Agent → Embedded in FinOps Center. When a user opens Agent Bill in the FinOps Center application, the system identifies their role via Cognito authentication, routes them to their dedicated QuickSight Chat Agent (via fixedAgentArn), and the agent loads the persona instruction associated with that role's topic.

Query Routing Logic

Every persona instruction defines how Agent Bill classifies and routes incoming user queries into one of three categories:

• DATA ONLY (Q Topics) — Cost queries, spending analysis, usage reports, and any question that can be answered from the QuickSight dataset. Agent Bill queries the semantic model directly. Examples: "What was my EC2 spend last week?", "Show me container costs by pod."

• ACTION/TASKS (MCP Server) — Workflow actions that modify data in FinOps Center via the MCP server backend. These are routed to Quick Spaces actions rather than dataset queries. Examples: "Accept my spend card for week 2", "Submit my budget for approval", "Claim this resource for my workload."

• COMBINED (Data + Action) — Queries that require both data retrieval and a workflow action. For example, "Show me my budget vs actuals and submit a reschedule request" combines a data query with an MCP action.

Topic Routing

For DATA ONLY queries, persona instructions also define which QuickSight Topic to route to. There are 4 topics available in Agent Bill 2.0, and not all roles have access to all topics:

• Cost Management (default topic) — The primary topic for all roles. Handles general spending, budget, and cost allocation queries. All personas default to this topic unless a more specific topic applies.

• Container Allocation — Routes container-specific queries (EKS, ECS, pods, tasks, Kubernetes). Triggered when the user mentions container, pod, task, EKS, ECS, or k8s keywords. Available to Financial Admins, Department Managers, Portfolio Managers, Product Owners, and Cloud Engineers.

• Marketplace Spending — Vendor-specific cost filtering and marketplace analytics. Currently available to Financial Admins only. When other roles ask about marketplace spending, the persona instruction redirects them to contact the FinOps team.

• Savings Plans Management — Savings plan coverage, savings amounts, and effective cost analysis. Currently available to Financial Admins only. Other roles are redirected to the FinOps team for savings plan inquiries.

Instruction Template Structure

Each persona instruction follows a consistent template structure. The total instruction must stay within approximately 3,200 characters (the QuickSight topic custom instruction limit). The template sections are:

1. Agent Identity

Opens with "You are Agent Bill, an AI assistant helping [Role Name] manage cloud spending for their assigned [Scope]..." This establishes the agent's name, the user's role, and the organizational scope (e.g., product, portfolio, department, or business unit). The identity section also lists the user's primary responsibilities so Agent Bill understands what tasks the user performs in FinOps Center.

2. Data Scope

Defines the cost hierarchy terminology that applies to this role. Uses the FinOps Center budget hierarchy: Business Unit = Element 1 (E1), Department = Element 2 (E2), Portfolio = Element 3 (E3), Product = Element 4 (E4). The data scope tells Agent Bill which level of the hierarchy this user operates at, and what cost allocation model applies (Budget → Account Allocation % → Workload → Resources).

3. Query Classification Rules

Explicit rules for how to classify each incoming query as DATA ONLY, ACTION/TASKS, or COMBINED. This section defines keywords and patterns that trigger each routing path. For roles with MCP actions (Product Owners, Cloud Engineers), this section is more detailed because those roles can both query data and perform workflow actions.

4. Topic Routing Rules

Specifies the default topic (Cost Management for all roles) and when to route to specialized topics. For example, container-related keywords (pod, task, EKS, ECS, Kubernetes, k8s) trigger routing to the Container Allocation topic. Also defines unavailable topics for the role — when a user asks about a topic they don't have access to (e.g., Marketplace or Savings Plans for non-admin roles), Agent Bill responds with a redirect message: "For [topic] inquiries, please contact your FinOps team."

5. Cost Metric Definitions

Defines the key cost fields Agent Bill should use when answering queries: "cost" (combined claimed + shared cost), "net_cost" (after discounts), discount columns (distributor, private_rate, bundled, edp, spp), and credit visibility rules. Credits are only visible to Financial Admin personas — other roles do not see credit-related fields.

6. Calendar Guidelines (Business Week Alignment)

Critical section that enforces FinOps Center's Sunday-to-Saturday business week definition. All weeks run SUNDAY to SATURDAY (not the default Monday-Sunday). The instruction includes explicit week definitions (W1 through W6) for each month, with rules for partial first and last weeks. The "SUNDAY to SATURDAY" rule is stated at the top of this section and reinforced at the bottom as a reminder. This ensures that when users ask "show me week 2 spending," Agent Bill uses the correct date range aligned to FinOps Center's period cards.

7. Response Formatting Guidelines

Optional section that controls how Agent Bill formats its responses. May include instructions to always show costs in USD, include time period labels, group by specific dimensions, or present data in a particular format suited to the role's needs.

Per-Role Topic Assignments

The following table summarizes which topics and capabilities are available to each role's persona instruction. Full persona instructions for each role are documented on the QuickChat Personas page.

• Financial Admins — Topics: Cost Management, Container Allocation, Marketplace Spending, Savings Plans Management. Credits: Yes. MCP Actions: No (admin oversight role). Scope: Full organization.

• Business Unit Managers — Topics: Cost Management only. Credits: No. MCP Actions: No. Scope: Business unit (E1), view-only.

• Department Managers — Topics: Cost Management, Container Allocation. Credits: No. MCP Actions: No. Scope: Department (E2), view-only.

• Portfolio Managers — Topics: Cost Management, Container Allocation. Credits: No. MCP Actions: No (but manage spend card governance and budget approvals through the FinOps Center UI). Scope: Portfolio (E3).

• Product Owners — Topics: Cost Management, Container Allocation. Credits: No. MCP Actions: Yes (accept spend cards, submit budgets, request reschedules). Scope: Product (E4).

• Cloud Engineers — Topics: Cost Management, Container Allocation. Credits: No. MCP Actions: Yes (claim resources, implement optimizations, manage workloads). Scope: Product (E4).

Managing Persona Instructions via API

Persona instructions can be managed programmatically using the AWS QuickSight API. This is essential for version control, bulk updates across roles, and automated deployment pipelines. The three relevant API operations are:

• DescribeTopic — Retrieves the current persona instruction for a topic. The custom instruction is returned in the CustomInstructions object via the CustomInstructionsString field. Use this to read and verify instructions before making changes.

• CreateTopic — Creates a new topic with a persona instruction included at creation time via the CustomInstructions field. Used when setting up Agent Bill for a new role or creating a new environment.

• UpdateTopic — Modifies the persona instruction on an existing topic. This is the primary API for iterating on instructions. Use DescribeTopic first, modify the instruction text, then call UpdateTopic to apply changes.

Best Practices for Creating and Iterating on Instructions

• Stay within the ~3,200 character limit. QuickSight topic custom instructions have a hard character limit. If your instruction exceeds this, prioritize the routing rules and calendar guidelines over verbose descriptions.

• Reinforce critical rules at both the beginning and end of the instruction. The business week definition ("SUNDAY to SATURDAY") is stated at the top and repeated at the bottom because AI models can lose track of rules in the middle of long instructions.

• Test with real user queries after each iteration. Use the QuickSight embedded chat preview to test questions like "What was my spend last week?" and verify the response uses the correct date range and topic.

• Use calculated fields in the dataset rather than the topic instruction when possible. For example, business_week_number and business_week_label were initially attempted as topic expressions but were moved to dataset calculated fields for reliability.

• Keep instructions consistent across roles. All personas should use the same terminology section, the same calendar guidelines, and the same cost metric definitions. Only the agent identity, data scope, and routing rules should differ between roles.

• Version your instructions. Use the API (DescribeTopic) to save a copy of the current instruction before making changes. This allows rollback if a new version causes unexpected behavior.