Principle:Microsoft Autogen Team Persistence
| Knowledge Sources | |
|---|---|
| Domains | Agent Frameworks, Database Management, CRUD Operations, Configuration Persistence |
| Last Updated | 2026-02-11 00:00 GMT |
Overview
Persisting multi-agent team configurations, sessions, and run history in a relational database to enable creation, retrieval, update, and deletion of team definitions across application restarts.
Description
Team persistence is the practice of storing agent team configurations and their associated metadata in a durable data store so that they survive application restarts, can be shared across users, and maintain a history of modifications. Without persistence, team configurations exist only in memory or as static files, making it difficult to iterate on designs, track changes, or support multi-user environments.
A team persistence layer provides several key capabilities:
CRUD Operations: Create, read, update, and delete team configurations through a uniform interface. The persistence layer abstracts the underlying database engine (SQLite for development, PostgreSQL for production) behind a common API.
Import/Export: Teams can be imported from JSON or YAML files and stored in the database, or exported from the database back to portable file formats. This supports workflows where teams are authored in code, version-controlled in Git, and then imported into the studio for visual testing.
Upsert Semantics: When saving a team configuration, the system checks whether a record with the same identifier already exists. If so, it updates the existing record with the new values and refreshes the timestamp. If not, it creates a new record. This idempotent behavior simplifies synchronization between file-based and database-based configurations.
Filtered Retrieval: Teams and related entities (sessions, runs, messages) can be retrieved with arbitrary filters (e.g., by user ID, by team ID) and ordered by creation or update timestamps. This supports the studio UI's need to display user-specific data with most-recent-first ordering.
Deduplication: When importing teams, the system can optionally check whether an identical configuration already exists for the given user, avoiding duplicate entries.
Usage
Use team persistence when:
- You need team configurations to survive application restarts
- Multiple users need to manage their own team configurations independently
- You want to import teams from JSON/YAML files into a database-backed studio
- You need an audit trail of when teams were created and last modified
- You are building a multi-user environment where teams are associated with specific users
Theoretical Basis
Team persistence follows the Repository Pattern from domain-driven design, where a single class encapsulates all data access logic for a set of related entities:
DATABASE LAYER ARCHITECTURE:
DatabaseManager
|
+-- upsert(model) -- Create or update any entity
+-- get(model_class, filters, order) -- Retrieve entities with filtering
+-- delete(model_class, filters) -- Remove entities
+-- import_team(config, user_id) -- Import team from file/dict
|
+-- Engine (SQLAlchemy)
| +-- SQLite (development)
| +-- PostgreSQL (production)
|
+-- SchemaManager (Alembic)
+-- initialize_migrations()
+-- ensure_schema_up_to_date()
UPSERT FLOW:
1. Open database session
2. Query for existing record by ID
3. If exists:
a. Update all fields from new model
b. Set updated_at to current timestamp
4. If not exists:
a. Insert new record
5. Commit transaction
6. Refresh model from database (get DB-generated fields)
7. Return Response with status and data
IMPORT TEAM FLOW:
1. Receive team_config (str path, Path, or dict)
2. If path: load JSON/YAML from file
3. If check_exists: scan existing teams for identical config
4. Create Team DB model with user_id and component config
5. Upsert into database
6. Return Response with team ID
The Response wrapper pattern ensures all database operations return a uniform result containing a status boolean, a human-readable message, and the operation data. This simplifies error handling in the API layer, which can directly forward the response status and message to clients.
The schema management subsystem uses Alembic for database migrations, allowing the schema to evolve over time without manual intervention. On startup, the system can detect schema differences and optionally auto-generate and apply migrations.