Rule Reference¶

Rules in the I category check instruction.txt files for structural correctness, reference validity, and best-practice adherence.

I001 — required-xml-structure

Every instruction must have all three of <role>, <persona>, and <taskflow> tags. These sections organize the instruction into context (who the agent is) and behavior (what it does).

Triggers: Any of the three tags is absent.

Fix: Add the missing section. Minimum structure:

<role>...</role>
<persona>...</persona>
<taskflow>
  <subtask name="...">
    <step>...</step>
  </subtask>
</taskflow>

I002 — taskflow-children

A <taskflow> with no children is effectively an empty instruction — the LLM has no steps to follow.

Triggers: <taskflow>...</taskflow> present but contains no <subtask> or <step> elements.

Fix: Add at least one <subtask name="..."> with <step> children.

I003 — excessive-if-else

Putting lots of IF/ELSE logic in instructions makes the LLM less reliable. LLMs are good at understanding intent, not at executing imperative logic trees. Move branching logic to callbacks.

Triggers: 3 or more lines matching IF ... ELSE pattern (case-insensitive).

Fix: Move deterministic branching into a before_model_callback or after_model_callback. Keep the instruction focused on goals, not conditional flows.

I004 — negative-triggers

Negative conditions in <trigger> elements confuse the LLM. "Trigger when NOT X" is harder for the model to reason about reliably than "Trigger when Y (the positive case)".

Triggers: <trigger> element containing NOT, is NOT, or similar negations.

Fix: Rewrite as a positive trigger. If you need to exclude a case, use a separate, earlier <step> that captures that case explicitly.

I005 — conditional-logic-block

<conditional_logic> blocks with priority-ordered conditionals are a pattern that confuses models because they require the model to evaluate conditions in order and pick the first match.

Triggers: Presence of <conditional_logic> in the instruction.

Fix: Use separate <step> elements with distinct triggers instead.

I006 — hardcoded-data

Phone numbers, prices, and other frequently-changing data in instructions create maintenance problems and risk the agent giving outdated information.

Triggers: Patterns matching phone numbers or dollar amounts in non-template lines.

Fix: Move dynamic data to tool responses. The agent should call a tool to get the current value, not read it from the instruction.

Configurable: You can add custom patterns in cxaslint.yaml under options.I006.patterns.

I007 — instruction-too-long

Very long instructions tax the model's context window and can reduce reliability. Consider splitting into multiple sub-agents.

Triggers: Word count exceeds the configured threshold (default: 3000 words).

Fix: Split complex responsibilities into sub-agents. Each agent should have a focused, manageable instruction.

Configurable: Set options.I007.max_words in cxaslint.yaml.

I008 — invalid-agent-ref

The {@AGENT: Name} syntax transfers control to another agent. If the referenced agent doesn't exist, the LLM can't transfer.

Triggers: {@AGENT: Name} where Name doesn't match any agent in the app.

Fix: Check the agent display name or resource name. The fix message lists available agents.

I009 — invalid-tool-ref

The {@TOOL: Name} syntax tells the LLM to call a tool. If the tool doesn't exist in the app's tool registry, it can't be called.

Triggers: {@TOOL: Name} where Name isn't in the list of known tools.

Fix: Verify the tool's display name. The fix message lists available tools.

I010 — wrong-agent-syntax

Common wrong forms for agent references that look almost right but won't be recognized by the platform.

Triggers: ${AGENT:...}, {AGENT:...} (without @), or ${@AGENT:...}.

Fix: Use {@AGENT: Display Name} (with @ sign, space after colon).

I011 — wrong-tool-syntax

Similar to I010, but for tool references.

Triggers: ${TOOL:...}, {TOOL:...}, or ${@TOOL:...}.

Fix: Use {@TOOL: Tool Name}.

I012 — unused-tool-in-config

If a tool is in the agent's JSON but never referenced in the instruction, the LLM doesn't know it can call the tool — which makes having it in the config pointless.

Triggers: Tool appears in agent.json's tools array but has no {@TOOL: ...} reference in instruction.txt.

Fix: Either add {@TOOL: tool_name} to the instruction (with appropriate context), or remove the tool from the agent's config.

I013 — tool-not-in-config

The instruction references a tool with {@TOOL: ...} that isn't in the agent's JSON config. The LLM will be told to call a tool that it doesn't have access to.

Triggers: {@TOOL: Name} where Name is not in agent.json's tools array.

Fix: Add the tool to the agent's tools array, or remove the reference from the instruction.

I014 — missing-current-date

Instructions should reference {current_date} or {{current_date}} so the agent knows the current date at runtime. This is important for date-sensitive tasks. If the global instruction or all agent instructions reference it, the warning is suppressed.

Triggers: No current_date reference found in instruction.txt or global_instruction.txt.

Fix: Add {current_date} or {{current_date}} to the instruction or global instruction.

I015 — banned-legacy-xml-tags

Instructions must not contain legacy CamelCase or state-machine XML tags that diverge from the canonical lowercase taskflow schema.

Triggers: Presence of tags like <Agent>, <Conversation_Schema>, <Persona>, <Role>, <General_Instruction>, <Context>, <state>, <transitions>, or <transition>.

Fix: Rewrite using the canonical lowercase taskflow schema: <role>, <persona>, <primary_goal>, <constraints>, <guidelines>, <taskflow>, <subtask>, <step>, <trigger>, <action>.

I016 — prose-state-machine

The single most damaging instruction anti-pattern: hand-building a finite-state machine inside the prompt and asking the LLM to execute it every turn. The model is made to read a counter variable, compare it to a literal, branch to a named step, write state back, and follow agent_action codes verbatim — control flow that an LLM executes unreliably and that belongs in deterministic code. This rule is a deterministic, multi-signal composite: it scores eleven independent surface forms (retry/attempt counters, STOP. halt tokens, -> transitions, conditional "go to step X" dispatch edges, back-edge loops, {var} == value tests, UPPER_SNAKE state writes, lookup_flag: "INIT" orchestrator traversal, follow the returned agent_action verbatim, a "state machine" named in a step, and IF-on-result-code) grouped into four categories, and fires only on co-occurrence (or a single high-confidence marker) so that a well-designed, declarative instruction stays silent.

Triggers: A high-confidence marker on its own (a retry-counter read/write, an UPPER_SNAKE state write, a lookup_flag enum, an agent_action-verbatim loop, or a "state machine" step name); or signals from ≥ 2 categories totalling ≥ 4 occurrences; or ≥ 3 strong control-flow edges (conditional jumps + loop back-edges). Plain forward navigation ("proceed to subtask conclusion") on its own never fires. Surface forms are kept disjoint from I003 and I005 so no line is double-reported. Content inside <inline_example> regions is ignored.

Fix: Move the control flow out of the prompt. Put retry/attempt counters and failure limits in a before_model/after_model callback — the slot-filling pattern keeps retry state in Python (a _retries dict), never in a {counter} the LLM has to read and increment. Replace Proceed to subtask X / Loop back to step Y / STOP GOTOs, state-variable writes, and IF-on-agent_action dispatch with declarative slot-filling DAG transitions so the framework owns routing. Then rewrite the instruction to state the goal, not a transition table.

Configurable: options.I016.min_distinct_categories (default 2), options.I016.min_total (default 4), options.I016.min_strong_edges (default 3).

Rules in the C category check callback python_code.py files for naming conventions, correct signatures, and safe coding practices.

C001 — callback-fn-name

Each callback type has a required entry function name. The platform looks for this specific function name when loading the callback.

Fix: Rename or add the entry function with the correct name.

C002 — callback-args

Each callback type has a required set of arguments. The platform passes specific objects; missing arguments cause runtime errors.

C003 — callback-camelcase

CES requires all function names to be snake_case. Functions with camelCase names are silently ignored.

Triggers: Any function definition using camelCase (e.g., def injectContext():).

Fix: Rename to inject_context.

C004 — callback-return-type

Model callbacks (before/after model) should return LlmResponse or None, never a raw dict. Returning a dict causes unpredictable behavior.

Fix: Use return LlmResponse.from_parts(parts=[Part.from_text(text="...")]).

C005 — callback-hardcoded-phrases

Hardcoded lists of phrases for intent detection in callbacks miss natural language variations. The LLM in the instruction is better at this.

Fix: Keep intent detection in the instruction. Use callbacks for execution only.

C006 — callback-bare-except

A bare except: catches everything — including platform-internal exceptions that should propagate. Always catch specific exceptions or use except Exception as e: with logging.

Fix: Replace except: with except Exception as e: logging.error(...).

C008 — callback-missing-typing-import

Using Optional, List, Dict, etc. without from typing import ... causes NameError at push time, silently breaking the callback.

Fix: Add from typing import Optional, List, Dict (or whichever types you use).

C009 — callback-signature

Type annotations must be exactly right — the platform validates signatures and silently drops callbacks with wrong types.

Fix: Use the exact signatures defined in the platform documentation. Example for before_model_callback:

def before_model_callback(
    callback_context: CallbackContext,
    llm_request: LlmRequest,
) -> Optional[LlmResponse]:

C010 — callback-python-syntax

Invalid Python syntax means the callback file can't be loaded. The platform silently fails to register callbacks with syntax errors.

Fix: Fix the syntax error. Run python -m py_compile python_code.py locally to check.

Rules in the T category check tool python_code.py files.

T001 — tool-error-pattern

When a tool encounters an error, it should return a dict with an agent_action key. This gives the agent a message to relay to the user instead of hallucinating a response.

Triggers: No agent_action string found anywhere in the tool file.

Fix:

if error_condition:
    return {"agent_action": "I encountered an error looking up that information. Please try again."}

T002 — tool-docstring

CES uses the tool's docstring as its description for the LLM. Without a docstring, the LLM has to guess when to call the tool based on its name alone.

Fix: Add a descriptive docstring explaining when and how the LLM should use the tool.

T004 — tool-fn-name

The tool function name should match the directory name for consistency. CES uses the function name for certain routing.

T005 — tool-high-cardinality

Arguments like timestamp, latitude/longitude, or internal session_id/request_id values are hard for users to express, especially in voice mode.

Fix: Design arguments that a human can express naturally (e.g., region, category, last_n_days).

T007 — tool-name-snake-case

Tool names with spaces or mixed case cause issues with the platform's routing. All tool names and displayName values must be snake_case.

Fix: Change "displayName": "Look Up Order" to "displayName": "lookup_order".

T009 — tool-kwargs-signature

The platform silently drops tools that use **kwargs in their signature. Always use explicit named parameters.

Fix: Replace def my_tool(**kwargs): with def my_tool(param1: str = '', param2: str = '') -> dict:.

T011 — tool-none-default

Parameters with None as a default value cause the platform to silently drop the tool during import. Use type-appropriate defaults instead.

Fix: Change def tool(name: str = None): to def tool(name: str = '') -> dict:.

T012 — tool-json-missing-description

Tool JSON configuration must include pythonFunction.description or widgetTool.description. The LLM relies on this description to know when to call the tool.

Triggers: The description field is missing or empty in the tool's JSON configuration.

Fix: Add a 'description' key within the 'pythonFunction' or 'widgetTool' object in the tool's JSON file.

Rules in the E category check golden and simulation YAML files.

E006 — eval-no-mocks

A golden that exercises tool calls without mock session parameters will make real API calls during testing — unpredictable and slow. Provide common_session_parameters to mock tool responses.

E008 — eval-missing-agent

Every turn with a user field must have a corresponding agent field. Without it, the platform reports "UNEXPECTED RESPONSE" for any agent response, causing false failures.

E010 — eval-tool-test-wrong-key

SCRAPI expects tool test YAML to use tests: as the top-level list key. Using test_cases: causes all tests to be silently skipped — SCRAPI returns 0 tests with no error.

Fix: Rename test_cases: to tests:.

E011 — eval-invalid-match-type

Valid $matchType values are: ignore, semantic, contains, regexp. Common typos like regex (should be regexp) or fuzzy (should be semantic) silently fall back to exact matching.

Rules in the A category check app.json and agent JSON configuration files.

A003 — config-tool-exists

An agent JSON that lists a tool that doesn't exist in the app results in the agent having no access to that tool — silently, with no error from the platform.

A005 — config-root-missing-end-session

The root agent must have end_session in its tools array. Without it, the agent can never cleanly terminate a conversation.

A006 — config-root-agent

App configuration must have a valid rootAgent field in app.json pointing to an existing agent directory. It must be camelCase, a string, and the corresponding agent directory and JSON file must exist.

Triggers: root_agent (snake_case) is used instead of rootAgent, rootAgent is missing or not a string, or the referenced agent directory/JSON is missing.

Fix: Add or fix the rootAgent field in app.json and ensure the agent directory and config file exist.

Rules in the S category perform cross-reference checks between multiple files.

These rules are similar to I009 and I013 but operate at a higher level, cross-referencing the agent JSON config against the local file system.

S008 — singleton-guardrail-types

The platform allows only one guardrail of certain types per app — currently llmPromptSecurity. The console UI enforces the limit, but the App Import API used by cxas push does not, so pushing duplicates leaves the app un-editable in the console ("Too many llm prompt security guardrails, the limit is 1").

Triggers: More than one directory under guardrails/ declares the same singleton guardrail type (llmPromptSecurity or llm_prompt_security).

Fix: Keep a single guardrail of that type and remove the others.

Rules in the V category validate resource configs against the CES protobuf schema. These catch structural issues that would cause API errors on push.

Schema validation catches issues like unknown fields, wrong types, and missing required fields — before you try to push and get a cryptic API error.

Rules in the V category (Variables) validate state, instruction, and eval references against declared variables in app.json variableDeclarations.

V100 — variable-declared

State reads/writes in callbacks/tools, or variable references in evals, must target a declared variable in app.json's variableDeclarations. Undeclared variables cause silent failures at runtime.

Triggers: Dotted path or flat name referenced but not found in variableDeclarations.

Fix: Declare the variable under variableDeclarations in app.json.

V101 — variable-type-match

State writes in callbacks or tools must assign values that match the declared schema type for that variable.

Triggers: Literal type of assigned value (e.g. integer) doesn't match the declared schema type (e.g. STRING).

Fix: Assign a value of the correct type, or update the schema in app.json.

V102 — nested-property-exists

Dotted state keys must resolve to declared properties of OBJECT type variables.

Triggers: Accessing a nested property (e.g. obj.prop) where obj is not an OBJECT, or prop is not declared in obj's properties schema.

Fix: Add the property to the schema in app.json or correct the code reference.

V103 — no-stale-flat-var-regression

Detects top-level state references or instruction template references that match a nested property, indicating a likely stale flat-variable reference that should be updated to the nested path.

Triggers: Accessing child when it has been migrated to parent.child in the schema.

Fix: Replace the flat reference with the dotted path (e.g. parent.child).

V104 — instruction-variable-ref

Instruction template references (e.g. {var}) must resolve to a declared variable. Unresolved references silently resolve to empty strings at runtime.

Triggers: {var} reference where var is not declared or doesn't resolve.

Fix: Declare the variable in app.json or fix the reference.