Skip to main content

Agent settings define the agent’s identity and behavioral rules. They live in agent_settings/ and are made up of personality, role, and rules resources.

Personality and role are platform-provisioned — update onlyThe personality and role resources are created automatically by the platform when a project is created. They always exist on any Agent Studio project and can be updated with poly push, but cannot be created from scratch via the ADK. If these files appear in a project directory without matching entries in .agent_studio_config — for example, after copying a directory from another project — the push will fail with a “Create operation not supported” error. Always start a new project with poly init and poly pull rather than copying an existing directory.
These settings shape how the agent presents itself and how it should behave across the conversation.

​
Location

Agent settings live under: 
agent_settings/
├── languages.yaml                  # Optional
├── personality.yaml
├── role.yaml
├── rules.txt
├── safety_filters.yaml             # Optional
└── experimental_config.json        # Optional

​
What agent settings control

Personality

Controls the agent’s tone and conversational style.

Role

Defines what the agent is and what kind of job it performs.

Rules

Provides plain-text instructions the agent should follow on every turn.

Languages

Configures the default language and any additional languages the agent supports.

Safety filters

Project-level content safety filtering across four categories.

Experimental config

Optional advanced feature flags and tuning.

​
Personality

The personality.yaml file controls the agent’s conversational tone.

​
Fields

FieldDescription
adjectivesMap of personality traits to booleans
customFree-text personality description

​
Adjectives

Allowed adjective values are:
  • Polite
  • Calm
  • Kind
  • Funny
  • Energetic
  • Thoughtful
  • Other
If Other is set to true, no other adjective can be selected.
Non-standard adjectivesThe platform may return adjectives not in the local allowed set (for example, deprecated or newly added adjectives). Validation only fails for adjectives that are enabled (true) and not in the allowed set. Disabled (false) non-standard adjectives pass validation and are silently excluded from the update payload when pushing.

​
custom

The custom field is a free-text description of the personality. It supports:
  • {{attr:...}}
  • {{vrbl:...}}

​
Example

adjectives:
  Polite: true
  Calm: true
  Kind: true
custom: ""

​
Role

The role.yaml file defines what the agent is. This is usually the agent’s role, title, or function in the business context.

​
Fields

FieldDescription
valueRole name, such as Customer Service Representative
additional_infoExtra context about the role
customFree-text role description used when value is other
If value is set to other, the custom field is used instead. The custom field supports:
  • {{attr:...}}
  • {{vrbl:...}}

​
Example

value: Customer Service Representative
additional_info: Handles customer inquiries and bookings
custom: ""

​
Rules

The rules.txt file contains plain-text behavioral instructions that the agent should follow on every turn. This is one of the most important files for shaping agent behavior.

​
Supported references

The rules file supports the following references:
SyntaxMeaning
{{fn:function_name}}Global function
{{twilio_sms:template_name}}SMS template
{{ho:handoff_name}}Handoff destination
{{attr:attribute_name}}Variant attribute
{{vrbl:variable_name}} or $variable_nameState variable

​
Example

Be helpful and professional at all times.
Use {{fn:validate_email}} when the user provides an email address.
For complex issues, use {{ho:escalation_handoff}} to transfer to a specialist.
Send confirmation via {{twilio_sms:confirmation_template}} after booking.

​
Writing effective rules

Rules are most useful when they are:
  • concise
  • explicit
  • actionable
  • stable across turns
Good rules tell the agent what standard it should follow, not how to perform step-by-step branching logic.
Use rules for behavioral guidanceRules are a good place for durable operating principles such as escalation behavior, safety guidance, or how the agent should handle common classes of requests.

​
What not to put in rules

Avoid putting deterministic branching logic into rules.txt.

​
Avoid

  • long conditional logic chains
  • step-by-step routing logic
  • hard-coded values that should come from references
For example, do not write logic such as: 
If $x == 0 do A, else do B.
That kind of logic belongs in flows and Python functions.

​
Prefer

  • references such as {{fn:...}}, {{attr:...}}, and {{vrbl:...}}
  • concise instructions that apply broadly
  • deterministic logic handled in code or flow transitions

​
Languages

The optional languages.yaml file configures which languages the agent supports. When present, it defines the default language and any additional languages. See the Languages reference for full field descriptions, validation rules, and examples.

​
Safety filters

The safety_filters.yaml file configures project-level content safety filtering. It controls whether harmful content is filtered across all channels by default. See the Safety filters reference for field descriptions, schema, and examples.

​
Best practices

  • keep rules concise and actionable
  • use references instead of hard-coded values
  • use custom personality and role text only when you need more than the structured fields provide
  • treat rules as a global behavioral layer, not a place for detailed flow logic

Functions

Learn how referenced global functions are defined and used.

Languages

Configure default and additional language settings for the agent.

Translations

Define localized text strings per language.

Safety filters

Configure content safety filtering at the project and channel level.

Experimental config

Configure optional advanced features and runtime overrides.
Last modified on July 9, 2026