Log in


API reference

Getting started with

9 min read.

On this page


    This guide will assist you in the creation of your first project in

    We will guide you to create your first agent to structure information from contents and to retrieve relevant information in these contents by interacting with your data in natural language.

    We will demonstrate different capabilities of through a very simple use case:

    • You have some contents where you want to retrieve the postal address to create some metadata, for instance to classify the information.
    • Furthermore, you have customers who want to query these contents by searching with a postal address. Queries should be in natural language to facilitate the interactions.

    In practice, you will create an agent allowing you to send a text to the Agents API and it will extract the French postal addresses in a structured way.

    Extraction example schema

    Best practices to start

    Defining the scope and usage is your first priority before starting any new project in It will help you create the most appropriate design for your agents.

    What is a postal address?

    • A postal address usually contains a route, a street number, a postal code, and a locality.
    • It could also contain additional information about the floor, the apartment, the building.
    • It would be interesting to have the GPS coordinates of the locality, to use on a map, for instance.

    Postal addresses could be slightly different from one country to another. So let’s start this tutorial with French postal address!

    A typical example is: 12 avenue de Flandres 75019 Paris (find some information about postal addresses on Wikipedia).

    Can I reuse components or should I create everything from scratch?

    Think about the elementary components you will need to create agents that are able to identify a postal address.

    In the example “12 avenue de Flandres 75019 Paris”, the decomposition into elementary components gives:

    • 12: Street number
    • avenue: Route type
    • de Flandres: Route name
    • 75019: Postal code (i.e. a specific pattern of numbers)
    • Paris: Locality

    Optionally, it could contain information about the apartment, building, floor. already contains some generic agents - numbers and French cities - to help you in this creation.

    We will create a module (named Agents in’s world) able to identify each part of the address, and a postal address.

    Create an agent

    Login to You will see an interface listing the available agents. Click on the New Agent button.

    Application screenshot

    A modal box with the form “Create a new agent” opens.

    1. Fill the Name field with “Address Tutorial”.
    2. Set the Visibility to Private, so that you will be the only user to see this agent.
    3. Fill the ID field with “address-tutorial”.
    4. Check the following options for languages: No language, fr (french) and uncheck en (english).
    5. Choose a background color or upload an image.
    6. Submit the form with the Create button.

    Agent creation form screenshot

    The agent is now created. By default, you land on the Overview tab of the agent.

    On the left part of the UI, you can edit agent’s configuration, manage access rights, dependencies and add a Readme to describe your agent. On the right part, a console allows you to play with the agent, but we will come back to it later.

    Overview screenshot

    First basic interpretation

    Create an interpretation

    In the Interpretations tab, click on the New Interpretation button.

    New interpretation screenshot

    A modal box with the form “Create a new interpretation” opens.

    1. Fill the ID with “address”.
    2. Set your interpretation visibility to Public.
    3. Fill a description: “Identifies the French postal addresses.”
    4. Click on the Create button.

    Interpretation form screenshot

    Create your first formulation

    Your first interpretation is created. Now click on it and select the fr tab. Type “12 avenue de Flandres 75019 Paris” in the text area, then click on Add.

    Keep the default options (keep order, close, auto solution) as is. We will come back to them later.

    Formulation form screenshot

    Testing the agent

    A console panel is on the right to test in live your agent. Type “12 avenue de Flandres 75019 Paris” in the text field and click on the arrow to send the request. This console calls your agent by REST API.

    You can see the returned solution in the Explain tab (opened by default). The solution is also available in JSON format; click on the JSON tab to see it.

    Console screenshot

    The returned value is the interpretation you just created and the score is the match confidence level: 0 means no match, and 1 means an exact match. Here the score is 1 because the sentence typed in the console exactly matches the formulation you just created.

    Route types

    You want to be able to identify any French postal address with other street number, route types and names, and localities.

    We will start with the route types detection by using an entities list.

    Create a route type entities list

    Click on the Entities tab and click on the New entities list button.

    Entities lists UI screenshot

    A modal box with the form “Create a new entities list” opens.

    1. Type “route_types” in the ID text field.
    2. Select Private and Glued options.
    3. Click on the Create button.

    create entities list screenshot

    Click on the entities list you just created to open it and enter route types names:

    1. Type “rue” in the Terms text area ; then click on Add,
    2. Type “avenue” in the Terms text area; then click on Add,
    3. Type “impasse” in the Terms text area; then click on Add,
    4. Type “passage” in the Terms text area; then click on Add,

    filling the entities list screenshot

    Go back to the Interpretations tab, click on the address public interpretation.

    Step 1 Edit the current formulation in address interpretation

    Click on the formulation “12 avenue de Flandres 75019 Paris” in order to edit it.

    UI screenshot

    Step 2 Link avenue with route_types entities list

    1. Highlight avenue in “12 avenue de Flandres 75019 Paris”.
    2. A drop-down list appears displaying the different interpretations and entities lists available.
    3. Choose the route_types entities list (it should be labeled like yourname/youragent/entities_lists/route_types).
    4. Click on Update

    Interpretation form screenshot

    updating interpretation screenshot

    Step 3 Validate

    Test in console the interpretation with the following sentences:

    • 12 impasse de Flandres 75019 Paris
    • 12 avenue de Flandres 75019 Paris
    • 12 rue de Flandres 75019 Paris

    All sentences are successful, the interpretation address is found on each route type variant.

    Console screenshots

    Street number, postal code & locality

    Let’s continue with the detection of street number, postal code and locality.

    Let’s add some dependencies

    In order not to reinvent the wheel, you will add 2 agent dependencies as seen above:

    • Numbers agent will allow you to understand ordinal and cardinal numbers written in digits or in letters. This seems appropriate to recognize street number and postal code.
    • VillesFR agent will allow you to recognize French cities and give you their geographical coordinates. This seems appropriate to recognize locality.

    To do this, return to the agent Overview tab.

    Step 1 Click on Add new dependency.

    Add dependency screenshot

    Step 2 Search and choose the Numbers public agent.

    Search dependencies screenshot

    Step 3 The Numbers agent is now in your dependencies.

    Populated dependencies section screenshot

    Step 4 Let’s add other dependency. Click on Add new dependency, search and choose the Cities French All public agent.

    Search dependencies screenshot

    Done Now, both dependencies are in place.

    Dependencies screenshot

    Edit address interpretation

    In order to make the agent understand the street number, postal code and locality, go to the Interpretations tab. Then go to the address interpretation and edit the “12 avenue de Flandres 75019 Paris” formulation.

    Let’s start making highlights:

    1. Highlight “12” and create an alias to the viky/numbers/interpretations/number interpretation.
    2. Highlight “75019” and create an alias to the viky/numbers/interpretations/number interpretation.
    3. Highlight “Paris” and create an alias to the viky/cities-fr-all/interpretations/city interpretation.

    Don’t highlight the route name for the moment, we will come back to it later.

    Interpretation form screenshot

    If you try to update the formulation, an error will be displayed because the parameter name number is used twice.

    In parameter name column:

    1. Replace the first number value by street_number.
    2. Replace route_types value by route_type.
    3. Replace the second number value by postal_code.
    4. Replace city by locality.

    Interpretation form screenshot

    Click on Update in order to save these modifications.

    Validate in the console

    Now test the sentence “12 avenue de Flandres 75019 Paris” in the console.

    Unreadable solution screenshot

    Every part is understood correctly, but the solution is quite verbose.

    We will now customize the output in order to make it simpler to read.

    Improve solution output

    Open the formulation and uncheck Auto solution. A textarea is now open at the bottom of the form.

    Solution textarea screenshot

    This textarea allows you to customize the solution. The solution is a json map, and you can use all the variables listed in the Parameter name column.

    Update the solution in order to have a solution like this:

      "street_number": street_number,
      "route_type": route_type,
      "postal_code": postal_code,
      "locality": locality

    Update solution screenshot

    The solution now becomes:

    Improved but too complex solution screenshot

    This is much more readable, but it is still not completely OK. Let’s remove the extra number and only keep the locality name for the moment.

    Replace the current solution with:

      "street_number": street_number.number,
      "route_type": route_type,
      "postal_code": postal_code.number,
      "locality": locality.nom_commune

    The solution is much better now:

    Solution screenshot

    Route name

    We will now try to understand the route names.

    Route names entities list

    There are too many route names to import them all in Instead we will try to make the agent understand unknown route names.

    First create a new private entities list route_names.

    Fill it with some common route names such as Champs Elysées, Rivoli, etc…

    Entities list route_names screenshot

    Edit address interpretation

    Go back in the Address interpretation, edit the formulation, then:

    1. Highlight de Flandres.
    2. Create an alias to the entities list route_names.
    3. Select any for this alias.
    4. Replace parameter name route_names value by route_name.
    5. Update solution with the code below.
    6. Click on Update button.
      "street_number": street_number.number,
      "route": route_type + " " + route_name,
      "postal_code": postal_code.number,

    Street names with any screenshot

    In the console, test the sentence “12 avenue de Flandres 75019 Paris” now. Every part is understood correctly, even the route name.

    Final solution screenshot

    Try a completely different address, for example “108 rue Jean Moulin 54230 Neuves-Maisons”. It works too!

    Successful solutions screenshot

    Congratulations! You now have your very own agent in that can recognize simple French postal addresses. does not limit you to use your agents within the platform. In the following section, we will show you how you can access your agent through an external application.

    Connect with your agent

    In this last step you will use your agent’s abilities from your own application. Every agent in is reachable through a public REST API. To access the API, you will first need the agent’s API token. You can find it in the configuration panel in the agent’s overview screen.

    Configure agent

    The API token is a 32 characters unique identifier that the developers must provide to prove that they are allowed to consume this agent.

    Agent API token

    Then, any HTTP client library will be able to send a sentence to the agent and get back the corresponding solution. A quick connection check can be made with a simple curl call:

    $ curl -G "<your_username>/address-tutorial/interpret.json?" \
           -H "Agent-Token: <agent_token>" \
           --data-urlencode "sentence=12 avenue de Flandres 75019 Paris"

    The HTTP response is the expected JSON:

      "interpretations": [
          "id": "<interpretation_id>",
          "slug": "<your_username>/address-tutorial/interpretations/address",
          "name": "address",
          "score": 0.91,
          "solution": {
            "street_number": 12,
            "route": "avenue de Flandres",
            "postal_code": 75019,
            "locality": "PARIS"

    Copyright ©2019 All rights reserved.

    Contact us by email at

    Made by Pertimm. Enjoy the rest of your day!

    On this page

      Home Documentation Blog