Data Storage

Data Storage in Agent Orbit

Agent Orbit provides a robust key-value store for agents to persist and share data. Each store is independent and can be attached to multiple agents, enabling seamless collaboration or isolated data handling.

Key Features

• Persistence: Stores remain intact even if agents are deleted.

• Shared Access: A single store can be shared between multiple agents.

• Atomic Transactions: Ensure consistent state with transaction support.

• Locking: Prevent conflicts in concurrent executions.

---

Creating a Store

You can create a store via:

• Dashboard: Easily create and manage stores visually.

• API/SDK: Programmatically handle stores for advanced workflows.

---

Accessing a Store

Once a store is attached to an agent, it becomes accessible via the store argument in the agent's main function:

pythonCopy codedef main(request, store):  
    print(store.items())  # View all key-value pairs  

---

Using a Store

The store object behaves like a Python dictionary. Here are common operations:

pythonCopy codedef main(request, store):  
    # Get the value of "color"  
    color = store["color"]  

    # Set the value of "color" to "red"  
    store["color"] = "red"  

    # Delete the key "color"  
    del store["color"]  

    # Iterate over all keys  
    for key in store:  
        print(key)  

    # Check for a key  
    if "color" in store:  
        print("Key exists!")  

    # Clear the entire store  
    store.clear()  

---

Supported Types

• Keys: Must be strings (store["key"] = value).

• Values: Must be JSON-serializable (strings, numbers, lists, dicts, etc.).

Example of valid operations:

pythonCopy codestore["key"] = "value"  
store["key"] = 42  
store["key"] = {"nested": "dict"}  

---

Transactions

Transactions allow you to group operations and ensure they either complete fully or roll back entirely in case of errors:

pythonCopy codedef main(request, store):  
    store["color"] = "blue"  
    with store.transaction():  
        store["color"] = "green"  
        some_function_that_may_fail()  
        store["shape"] = "rectangle"  

def some_function_that_may_fail():  
    raise ValueError("Oops!")  

If an exception occurs during the transaction, all changes will be reverted.

---

Locking

For concurrent executions, locking ensures that only one execution can modify the store at a time:

pythonCopy codedef main(request, store):  
    with store.transaction(lock=True):  
        store["runs"] = store.get("runs", 0) + 1  
        print(f"Agent runs: {store['runs']}")  

Why Locking Matters

Without locking, concurrent executions can result in race conditions:

• Agent A reads the value of runs (e.g., 0).

• Agent B reads the value of runs (also 0).

• Agent A increments and writes 1.

• Agent B increments and writes 1.

With locking, these operations happen sequentially, ensuring runs is incremented correctly.

---

Agent Orbit’s data storage offers powerful tools to simplify agent workflows while maintaining consistency and reliability. Start leveraging stores for your agents today!