Enterprise agent platform for building, deploying, and operating AI teammates.
Scripts
Operational helper scripts for local development, upgrades, and release checks. Run commands from the repository root unless a script says otherwise.
parallel_search_example.py
Runs opt-in, keyless web search and optional page fetching through Xagent's MCP configuration model and agent tool loader. See Parallel Search MCP for the runnable configuration and setup instructions.
backfill_uploaded_files.py
Registers files already present under the configured uploads directory into the
uploaded_files table. Useful after upgrading from an older build that wrote
files to disk but did not create database records for them.
Common usage:
PYTHONPATH=src python scripts/backfill_uploaded_files.py --dry-run
PYTHONPATH=src python scripts/backfill_uploaded_files.py
PYTHONPATH=src python scripts/backfill_uploaded_files.py --user-id 1
check_alembic_heads.sh
Checks the Alembic revision graph and reports which invariant broke: more than
one head, a duplicate revision ID, or a down_revision that is not on disk.
Alembic enforces none of these itself -- a branched graph is legal to it, and a
duplicate ID only produces a warning -- so this is the guard against accidental
migration branching, run both locally via pre-commit and on every PR.
Common usage:
PYTHONPATH=src scripts/check_alembic_heads.sh
Set ALEMBIC_CHECK_PYTHON to a specific interpreter to run alembic under
(default: uv run alembic, falling back to python -m alembic). Its regression
coverage is tests/migrations/test_check_alembic_heads.py.
convert_trace_checkpoint_messages.py
Converts historical checkpoint trace rows from legacy inline payloads to refs
backed by blob tables. It currently covers snapshot.context.messages,
snapshot.pattern_state.tool_ledger, and snapshot.context.metadata. This is
an internal storage migration only: API/runtime readers still decode refs back
into normal checkpoint objects.
The script is dry-run by default. Use --execute to write changes.
Common usage:
# Preview all configured database rows without writing changes.
PYTHONPATH=src python scripts/convert_trace_checkpoint_messages.py
# Convert all historical checkpoint rows.
PYTHONPATH=src python scripts/convert_trace_checkpoint_messages.py --execute
# Convert only one task.
PYTHONPATH=src python scripts/convert_trace_checkpoint_messages.py --execute --task-id 467
# Resume after a known trace_events id or process in smaller batches.
PYTHONPATH=src python scripts/convert_trace_checkpoint_messages.py --execute --start-id 100000 --batch-size 100
Notes:
- The configured database comes from
DATABASE_URL, or the normal xagent default database path ifDATABASE_URLis unset. - Existing refs rows are skipped, so it is safe to rerun.
- New writes from the upgraded app already use refs and will be skipped.
- Row-level conversion failures are logged and counted, then the script continues with later rows. A run with any row errors exits non-zero.
- For SQLite, the database file may not physically shrink until you run
VACUUMafter conversion.
export_openapi.py
Exports the FastAPI OpenAPI schema to JSON.
Common usage:
PYTHONPATH=src python scripts/export_openapi.py -o openapi.json
connector_smoke/
Black-box connector smoke checks against a deployed instance. L1 checks the connector catalog and each builtin OAuth provider's client configuration, with no vendor accounts. See connector_smoke/README.md.
Common usage:
PYTHONPATH=src:scripts python -m connector_smoke l1 --base-url https://xagent.example.com