> ## Documentation Index
> Fetch the complete documentation index at: https://koreai-content-gov.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# How to use ON_START to greet users before the first message

<Badge icon="arrow-left" color="gray">[Back to how-to guides](/agent-platform/abl/how-to/overview#conversation-entry-and-welcome-experience)</Badge>

Use this pattern when the agent must run startup logic before the user sends the first turn.

## Concept

`ON_START` is the session-start lifecycle handler. It can set session values, call a tool, choose a response branch, return voice or rich payloads, and delegate to another agent. It runs once per initialized runtime session and is idempotent: if the session is already initialized, startup does not run again.

Use `ON_START` for work that belongs to session initialization: greeting, reading channel context, loading a profile, setting counters, or selecting a first-turn experience. Do not use it as a replacement for normal per-turn routing.

## Minimal working example

```yaml expandable=true theme={null}
AGENT: On_Start_Welcome_Agent
GOAL: "Run startup logic before the first user message"

ON_START:
  SET: startup_source = session.channel
  RESPOND: "Hello. I am ready to help."

FLOW:
  entry_point: first_step
  steps:
    - first_step

first_step:
  REASONING: false
  RESPOND: "You reached us from {{startup_source}}."
  THEN: COMPLETE
```

## How it works

`SET` executes before the response. That means values copied from runtime context can be interpolated into the welcome or into the first flow step. The runtime emits `dsl_set` traces for assignments and `dsl_respond` traces for the startup response.

## Common variations

### Personalize the welcome with startup values

A startup response can include placeholders. The welcome renders with values that `SET` assigns earlier in the same `ON_START` block, so the user sees real session data in the first message rather than a generic greeting.

```yaml expandable=true theme={null}
AGENT: On_Start_Personalized_Agent
GOAL: "Greet the user with values set during startup"

ON_START:
  SET: startup_source = session.channel
  RESPOND: "Hello. You reached us from {{startup_source}}."

FLOW:
  entry_point: ready
  steps:
    - ready

ready:
  REASONING: false
  RESPOND: "How can I help?"
  THEN: COMPLETE
```

This works on every channel that triggers a welcome. On Kore Agent Assist, Agent AI triggers it when you select **Use 'Trigger Welcome message' as the first request to Agentic**. For details, see [Agent AI integration](/agent-platform/integrations/agent-ai#choose-first-request-trigger).

### Choose a branch at startup

Branches are evaluated in order. The first matching branch wins. An `ELSE` branch is the default branch.

```yaml expandable=true theme={null}
AGENT: On_Start_Branch_Agent
GOAL: "Choose the first welcome turn from session context"

ON_START:
  BRANCHES:
    - IF: session.interaction.current.language == "fr"
      RESPOND: "Bonjour. Comment puis-je vous aider ?"
    - ELSE:
      RESPOND: "Hello. How can I help?"

FLOW:
  entry_point: ready
  steps:
    - ready

ready:
  REASONING: false
  RESPOND: "Ready."
  THEN: COMPLETE
```

## Verification

Create sessions with different interaction language values and confirm the selected welcome changes. In traces, check `dsl_on_start_branch` for the matched branch index. Confirm `ON_START` runs once by sending a second message in the same session and checking that no second startup trace is emitted. For a personalized welcome, confirm the first message shows the assigned value rather than the raw placeholder.

## Common mistakes

| Mistake | Why it happens | How to avoid it |
| - | - | - |
| Putting `SET` or `CALL` inside a branch | Branches look like mini flows. | Keep side effects at top-level `ON_START`; use branches only to select startup responses. |
| Expecting startup to rerun on every message | `ON_START` is a session initialization hook. | Use normal flow, handoff, or reasoning logic for per-turn behavior. |
| Branching on values that do not exist yet | The first user turn has not happened. | Branch only on runtime context, constants, memory recall, or values set during startup. |

## Troubleshooting

If a branch condition is malformed, the runtime fails closed and falls back to the top-level `ON_START` response when one exists. If no startup response is returned, the flow can still run from its entry point.

## Production readiness checklist

* Put side effects at top-level `ON_START`; branches can choose responses but cannot run `SET`, `CALL`, or `DELEGATE`.
* Use an `ELSE` branch or a top-level fallback response.
* Keep branch conditions based on values that are present before the first user turn.
* Validate traces for `dsl_on_start`, `dsl_set`, and `dsl_on_start_branch`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.