Enjoyed this article? See more similar articles in 
Pega Gen AI Cookbook - Recipes series
TOON — A Smarter Way to Build High-Fidelity AI Agents
How structured agent instructions improve maintainability, consistency, and scalability in enterprise AI solutions.
Introduction
As organizations adopt Pega Agentic AI, one challenge quickly emerges:
How do we provide increasingly complex instructions to an AI agent while keeping prompts understandable, maintainable, and scalable?
Modern enterprise agents are no longer simple question-answering systems. They are expected to:
- Execute business policies
- Analyze large volumes of data
- Follow regulatory requirements
- Orchestrate decisions
- Interact with tools and external systems
- Generate structured outputs
- Handle exceptions and edge cases
As agent complexity grows, prompt design becomes increasingly important.
Many teams start with traditional free-form instructions or continue appending new requirements to existing prompts. Initially, this works well. However, over time prompts often become difficult to understand, review, and maintain.
A more structured approach is emerging:
TOON (Token-Oriented Object Notation). Structured Agent Instructions)
TOON introduces a clear and organized way to define agent behavior using explicit sections for responsibilities, goals, inputs, rules, constraints, and outputs.
Rather than asking whether AI can understand large paragraphs of instructions, TOON asks a different question:
How can we make prompts easier for both humans and AI systems to work with?
The Evolution of AI Prompts
Most AI solutions begin with simple instructions:
You are a fraud analyst. Review all related fraud cases,
identify duplicates, determine whether they should be merged,
identify conflicts, generate recommendations, and provide
next actions for investigators.
For simple use cases, this approach is perfectly acceptable.
However, enterprise-grade agents rarely remain simple.
Over time, additional requirements are introduced:
- Business rules
- Compliance policies
- Regulatory constraints
- Security requirements
- Formatting instructions
- Escalation procedures
- Tool invocation rules
- Data quality validations
- Output requirements
The result is often a prompt that grows into several pages of instructions.
While functional, these prompts become increasingly difficult to manage.
The Problem with unstructured Prompts
Consider the following example:
You are a fraud analyst.
Review all related cases.
Identify duplicates.
The oldest case becomes the master case.
Do not include the master case in duplicates.
Generate summaries.
Return HTML.
Do not use CSS.
Generate action items.
Sort cases by date.
Use investigator terminology.
Identify trends.
Return JSON.
Nothing in the above instructions is technically wrong.
The challenge is that instructions are scattered throughout the prompt without a clear organizational structure.
As prompts continue to evolve, several issues begin to emerge:
-
Reduced Readability
- Architects and business analysts must read the entire prompt to understand agent behavior.
-
Difficult Maintenance
- Introducing new requirements often means inserting instructions into multiple locations.
-
Governance Challenges
- Reviewing prompts for compliance and approval becomes more difficult.
-
Higher Risk of Contradictions
- As prompts grow, duplicated or conflicting instructions can appear.
-
Limited Reusability
- Large free-form prompts are often difficult to reuse across multiple agent implementations.
- These challenges become even more significant when multiple teams are collaborating on the same solution.
What is TOON?
TOON is a structured format for organizing agent instructions.
Instead of describing the agent using large narrative paragraphs, TOON organizes information into clearly defined sections.
Example:
Role: Fraud Investigation Agent
Audience: Fraud Investigators
Goal: Analyze related fraud cases and provide actionable insights.
Inputs:
- Current Case
- Related Cases
Rules:
- Identify Master Case
- Detect Duplicates
- Detect Conflicts
- Recommend Merges
Constraints:
- Use investigator terminology
- Follow fraud investigation guidelines
Output:
JSON
The information itself has not changed.
What has changed is how the information is organized.
TOON transforms prompts from narrative text into structured instruction contracts.
Why TOON structure matters
The primary benefit of TOON is not that it changes what the model can understand.
The benefit is that it improves how instructions are organized and managed.
Clear separation of responsibilities
Each section has a specific purpose.
For example:
Role: defines the agent’s identity.
Goal:defines what must be achieved.
Rules: defines business logic.
Constraints:defines limitations and guardrails.
This creates a cleaner and more maintainable instruction set.
Enterprise AI solutions
Enterprise AI solutions are rarely built by prompt engineers alone.
Stakeholders often include:
- Business analysts
- Architects
- Product owners
- Compliance teams
- Risk teams
- Governance reviewers
A structured format makes prompts easier to review and validate.
For example, a compliance reviewer can focus on:
Constraints: without reviewing the entire prompt.
Similarly, a business analyst can focus on:
Rules: without navigating implementation details.
Improved Maintainability
Enterprise requirements change frequently.
A new fraud detection rule can be added directly into the Rules section:
Rules:
- Detect duplicate cases
- Detect conflicts
- Flag suspicious account changes
without modifying multiple paragraphs.
This makes prompt updates more predictable and easier to manage over time.
TOON and Enterprise Governance
One of the most overlooked aspects of Agentic AI is governance.
Organizations increasingly require AI solutions to undergo:
- Architecture reviews
- Compliance reviews
- Security reviews
- AI governance assessments
Large free-form prompts can be difficult to review consistently.
TOON introduces a standardized structure that helps establish repeatable review processes. Creates a common framework that teams can apply across multiple agents.
This consistency becomes increasingly valuable as organizations expand their Agentic AI programs.
TOON and Reusability
Enterprise organizations rarely build a single agent.
They build dozens.
A practical enterprise template might include:
Role: Who the agent is
Audience: Who consumes the results
Goal: What success looks like
Inputs: Available information
Rules: Business logic
Constraints: Guardrails and limitations
Tools: Available tools or capabilities
Output: Expected response format
Although their business objectives differ, many sections remain similar. can become a reusable organizational standard.
Not every agent requires every section, but maintaining a consistent structure helps improve readability and long-term maintainability. This encourages consistency across AI initiatives and reduces the effort required to create new agents.
TOON in Pega Agentic AI
Pega Agentic AI often involves:
- Multi-agent collaboration
- Decision orchestration
- Business rule execution
- Complex workflow automation
- Enterprise governance requirements
As these solutions grow in sophistication, prompt structure becomes increasingly important.
TOON provides a practical framework for organizing agent instructions without changing the underlying business requirements.
The result is an instruction set that is easier to understand, easier to maintain, and easier to govern.
Key takeaways
TOON is not a replacement for JSON, YAML, or any other data format.
Instead, it is a structured approach to defining agent instructions.
By organizing prompts into clearly defined sections such as Role, Goal, Inputs, Rules, Constraints, and Output, organizations can create AI agents that are easier to review, maintain, govern, and evolve.
As Agentic AI continues to expand across the enterprise, prompt structure becomes just as important as prompt content.
TOON helps bring that structure to enterprise-scale AI solutions.
#Pega #PegaAgenticFabric #AgenticAI #PromptEngineering #GenerativeAI #EnterpriseAI #PegaCommunity #AIArchitecture #Decisioning #WorkflowAutomation #ArtificialIntelligence
