> ## Documentation Index > Fetch the complete documentation index at: https://docs.poly.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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`](/adk/reference/cli#poly-init) and [`poly pull`](/adk/reference/cli#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: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} agent_settings/ ├── languages.yaml # Optional ├── personality.yaml ├── role.yaml ├── rules.txt ├── safety_filters.yaml # Optional └── experimental_config.json # Optional ``` ## What agent settings control Controls the agent's tone and conversational style. Defines what the agent is and what kind of job it performs. Provides plain-text instructions the agent should follow on every turn. Configures the default language and any additional languages the agent supports. Project-level content safety filtering across four categories. 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 ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} 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 ```yaml theme={"theme":{"light":"github-light","dark":"github-dark"}} 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](/adk/reference/functions) | | `{{twilio_sms:template_name}}` | [SMS template](/adk/reference/sms) | | `{{ho:handoff_name}}` | [Handoff destination](/adk/reference/handoffs) | | `{{attr:attribute_name}}` | [Variant attribute](/adk/reference/variants) | | `{{vrbl:variable_name}}` or `$variable_name` | [State variable](/adk/reference/variables) | ### Example ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} 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: ```text theme={"theme":{"light":"github-light","dark":"github-dark"}} 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](/adk/reference/languages) 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](/adk/reference/safety_filters) 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 ## Related pages Learn how referenced global functions are defined and used. Configure default and additional language settings for the agent. Define localized text strings per language. Configure content safety filtering at the project and channel level. Configure optional advanced features and runtime overrides.