# 4.1. State Referencing

## Start State

Let us create transitions for a virtual agent that handles time, weather, and playing music:

{% code lineNumbers="true" %}

```python
transitions = {
    'state': 'start',
    '`What can I do for you?`': {
        '[{time, clock}]': {
            '`It\'s 3PM.`': 'end'
        },
        '[{weather, forecast}]': {
            '`It\'s sunny outside`': 'end'
        },
        '[play, raining tacos]': {
            '`It\'s raining tacos. From out of the sky ...`': 'end'
        },
        'error': {
            '`Sorry, I didn\'t understand you.`': 'start'
        }
    }
}
```

{% endcode %}

* `#5`: shows the current time (although it is correct only twice a day at the moment).
* `#8`: informs the current weather in Sunnyville.
* `#11`: plays the song "[Raining Tacos](https://www.youtube.com/watch?v=npjF032TDDQ)".
* `#14`: print the error message and references to the `start` state.

{% tabs %}
{% tab title="M1" %}

```
S: What can I do for you?
U: What time is it now?
S: It's 3PM.
```

{% endtab %}

{% tab title="M2" %}

```
S: What can I do for you?
U: What's the weather like?
S: It's sunny outside
```

{% endtab %}

{% tab title="UM" %}
{% code lineNumbers="true" %}

```
S: What can I do for you?
U: Play rainy taco
S: Sorry, I didn't understand you. What can I do for you?
U: Play raining tacos
S: It's raining tacos. From out of the sky ...
```

{% endcode %}
{% endtab %}
{% endtabs %}

Notice that when the user input does not match any of the conditions, it prints the error message and loops back to the `start` state.

## Custom States

It is possible to name any transition you create as a state:

{% code lineNumbers="true" %}

```python
transitions = {
    'state': 'start',
    '`What can I do for you?`': {
        '[{time, clock}]': {
            'state': 'time',
            '`It\'s 3PM.`': 'end'
        },
        '[{weather, forecast}]': {
            'state': 'weather',
            '`It\'s sunny outside`': 'end'
        },
        '[play, raining tacos]': {
            'state': 'play_raining_tacos',
            '`It\'s raining tacos. From out of the sky ...`': 'end'
        },
        'error': {
            '`Sorry, I didn\'t understand you.`': 'play_raining_tacos'
        }
    }
}
```

{% endcode %}

* `#6`: names the state as `time`.
* `#9`: names the state as `weather`.
* `#13`: names the state as `play_raining_tacos`.
* `#17`: references to the  `play_raining_tacos` state.

{% tabs %}
{% tab title="Output" %}

```
S: What can I do for you?
U: Play rainy taco
S: Sorry, I didn't understand you. It's raining tacos. From out of the sky ...
```

{% endtab %}
{% endtabs %}

## Exit State

State referencing can be abused to create transitions that never end (infinite loop). It is important to design an exit state so you can terminate the conversation without throwing errors:

{% code lineNumbers="true" %}

```python
transitions = {
    'state': 'start',
    '`What can I do for you?`': {
        '[{time, clock}]': {
            'state': 'time',
            '`It\'s 3PM.`': 'start'
        },
        '[{weather, forecast}]': {
            'state': 'weather',
            '`It\'s sunny outside`': 'start'
        },
        '[play, raining tacos]': {
            'state': 'play_raining_tacos',
            '`It\'s raining tacos. From out of the sky ...`': 'start'
        },
        'error': {
            '`Sorry, I didn\'t understand you.`': 'start'
        },
        '[exit]': {
            'state': 'exit',
            '`Goodbye!`': 'end'
        }
    }
}
```

{% endcode %}

* `#6,10,14,17`: loops back to the `start` state.
* `#19-21`: creates an exit state to terminate the dialogue.

{% tabs %}
{% tab title="Output" %}

```
S: What can I do for you?
U: time
S: It's 3PM. What can I do for you?
U: weather
S: It's sunny outside What can I do for you?
U: play raining tacos
S: It's raining tacos. From out of the sky ... What can I do for you?
U: exit
S: Goodbye!
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="Question" %}
What is the main difference between an `error` transition and an `exit` state?
{% endtab %}

{% tab title="Answer" %}
An error transition defines a default action for uninterpretable user input, whereas an exit state terminates the current session of the dialogue.
{% endtab %}
{% endtabs %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://emory.gitbook.io/conversational-ai/4.-interaction-design/4.1.-state-referencing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.