Skip to content

Agent settings

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 only

The 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

Field Description
adjectives Map of personality traits to booleans
custom Free-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 adjectives

The 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

Field Description
value Role name, such as Customer Service Representative
additional_info Extra context about the role
custom Free-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:

Syntax Meaning
{{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_name State 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 guidance

Rules 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. Open functions

  • Languages

    Configure default and additional language settings for the agent. Open languages

  • Translations

    Define localized text strings per language. Open translations

  • Safety filters

    Configure content safety filtering at the project and channel level. Open safety filters

  • Experimental config

    Configure optional advanced features and runtime overrides. Open experimental config