Using the REST API & CLI¶

The Flou Engine abstracts all the infrastructure needed for orchestrating Flou's Networks of Agents. It provides state management, efficient concurrency, error handling, retries, a time machine (an execution history with replay and rewind) and data storage out-of-the-box.

It provides several APIs best suited for different use cases:

A REST API similar to that of LLM providers
Websockets for realtime updates
CLI for development UX, scripts and easy CI/DC integration

You can create many instances of a Network of Agents. An instance is the fixed structure defined in your code plus a status for each LTM (State Machine / State) and a store. You interact with the Network of Agents by performing labelled transitions and waiting for other transitions to run.

Every time a transition is performed or a state get's executed a snapshot is taken so it's possible to inspect and trace the whole execution history at any point in time. It also allows for rollbacks to a previous snapshot and replays.

Working with Network of Agents¶

Listing registered LTMs¶

To create a LTM you will need to know it's FQN (Fully Qualified Name) of the Python class. You can get it by listing all your registered LTMs:

REST APICLI

curl -X 'GET' \
    'http://localhost:8000/api/v0/ltm/registry' \
    -H 'accept: application/json'

Sample output

[
    {
        "fqn": "flou.app.SampleLTM",
        "name": "sample_ltm"
    }
]

flou registry-list

Sample output

┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┓
┃ name       ┃ fqn                ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━┩
│ sample_ltm │ flou.app.SampleLTM │
└────────────┴────────────────────┘

Creating an LTM instance¶

You can then create a new instance with the FQN and possible payload:

REST APICLI

curl -X 'POST' \
    'http://localhost:8000/api/v0/ltm' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
        "fqn": "flou.app.SampleLTM",
        "payload": {}
    }'

Sample output

{
    "id": 1
}

flou create flou.app.SampleLTM

Sample output

Created LTM root, id: 1, kwargs: {}

Creating an LTM returns a unique id across all Networks of Agents.

Listing all LTMs¶

You can list all the LTM's instances by:

REST APICLI

curl -X 'GET' \
    'http://localhost:8000/api/v0/ltm' \
    -H 'accept: application/json'

Sample output

[
    {
        "id": 1,
        "name": "sample_ltm",
        "fqn": "flou.app.SampleLTM",
        "snapshots_count": 1,
        "created_at": "2024-09-01 21:32:43",
        "updated_at": "2024-09-01 21:32:43"
    }
]

flou get 1

Sample output

┏━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
┃ id  ┃ name       ┃ fqn                ┃ #snapshots ┃ created_at          ┃ updated_at          ┃
┡━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
│ 1   │ sample_ltm │ flou.app.SampleLTM │ 1          │ 2024-09-01 21:32:43 │ 2024-09-01 21:32:43 │
└─────┴────────────┴────────────────────┴────────────┴─────────────────────┴─────────────────────┘

Retrieving an instance¶

You will need the instance ID and call:

REST APICLI

curl -X 'GET' \
    'http://localhost:8000/api/v0/ltm/1' \
    -H 'accept: application/json'

Sample output

{
    "name": "sample_ltm",
    "state": {
        "_status": "active",
        ...
    },
    "snapshots": [
        {
        "time": "2024-09-01 18:32:43.473991",
        "reason": "start",
        "item": {...},
        "patch": [...],
        "execute_queue": [...],
        "transitions_queue": [...]
        },
        ...
    ],
    "fqn": "tests.concurrency.test_concurrent_arg.ConcurrentLTM",
    "params": null,
    "structure": {
        ...
    },
    "concurrent_instances": {...},
    "created_at": "2024-09-01 21:32:43",
    "updated_at": "2024-09-01 21:32:43"
}

flou get 1

Sample output

┏━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
┃ name       ┃ fqn                ┃ state   ┃ params ┃ structur┃ concurrent_instances ┃ created_at          ┃ uploaded_at         ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
│ sample_ltm │ flou.app.SampleLTM │ {       │ None   │ {       │ {                    │ 2024-09-01 21:32:43 │ 2024-09-01 21:32:43 │
│            │                    │     ... │        │     ... │     ...              │                     │                     │
└────────────┴────────────────────┴─────────┴────────┴─────────┴──────────────────────┴─────────────────────┴─────────────────────┘

Performing a transition¶

To perform a transition you need to know the transition label, it's namespace, your desired params and payload.

REST APICLI

curl -X 'POST' \
    'http://localhost:8000/api/v0/ltm/1/transition' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
        "transition": "sample_transition",
        "namespace": "sample_ltm",
        "params": [],
        "payload": {}
    }'

Sample output

true

flou transition 1 sample_transition

Sample output

Launched transition sample_ltm for LTM sample_ltm, id: 1 with payload: None

If you want a blocking call until another transition is performed un can use the wait_until_transition parameter that blocks the return until the transition you requested is performed. This way you can mimic a regular LLM call from your app and swap it to a Network of Agents without changing much of your app's code.

REST API

curl -X 'POST' \
    'http://localhost:8000/api/v0/ltm/1/transition' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -d '{
        "transition": "sample_transition",
        "namespace": "sample_ltm",
        "params": [],
        "payload": {},
        "wait_until_transition": "another_transition",
    }'

Sample output

true

REST API reference documentation¶

You can visit http://localhost:8000/docs and check out the complete REST API reference documentation.

Command Line Interface help¶

By calling flou --help from your terminal you can see all the cli commands.