Skip to content

Migrating from 0.22.5 to 0.22.6

Breaking changes

Change Impact Error if you skip §
branch.instruct() removed High AttributeError: 'Branch' object has no attribute 'instruct' §1
lionagi.operations.instruct removed High ModuleNotFoundError §2
Persistence: logs/agents/ → runs/{run_id}/ Medium Resume finds nothing §3
last_branch.json schema Low None (auto-normalized) §4
Flat artifact dumps removed Medium FileNotFoundError on old paths §5
DAG op name "instruct" → "operate" Medium Orchestrator ignores op §6
"codex/gpt-5.4" fallback removed Low ValueError: Provider must be provided §7
TEAM_WORKER_SYSTEM composition Low Wrong prompt composition (silent) §8

§1 branch.instruct() → branch.operate()

AttributeError: 'Branch' object has no attribute 'instruct'

grep -rn "\.instruct(" --include="*.py" .

# before: await branch.instruct(instruction="...", stream_persist=True, persist_dir="./runs")
# after:  await branch.operate( instruction="...", stream_persist=True, persist_dir="./runs")
  • ✓ Rename .instruct( → .operate(; all kwargs unchanged; Instruct(...) objects unchanged
  • ✓ New optional middle= kwarg — omit to auto-dispatch (API→communicate, CLI→run_and_collect)

§2 lionagi.operations.instruct module removed

ModuleNotFoundError: No module named 'lionagi.operations.instruct'

grep -rn "from lionagi.operations.instruct\|import instruct" --include="*.py" .

from lionagi.operations.instruct import instruct  # 0.22.5
from lionagi.operations.operate  import operate   # 0.22.6
  • ✓ Instruct dataclass unchanged — only module path and function name changed

§3 Persistence layout: logs/agents/ → runs/{run_id}/

# 0.22.5: ~/.lionagi/logs/agents/{provider}/{branch_id}.json

# 0.22.6: ~/.lionagi/runs/{YYYYMMDDTHHMMSS-uuid6}/
    ├── run.json
    ├── branches/{branch_id}.json
    ├── stream/{branch_id}.buffer.jsonl
    └── artifacts/{agent_id}/

li agent -r {branch_id} unchanged — find_branch() falls back to logs/agents/ for pre-0.22.6 branches.

grep -rn "logs/agents" --include="*.py" .
  • ✓ Replace ~/.lionagi/logs/agents/{provider}/ references → ~/.lionagi/runs/*/branches/
  • ✓ Pass LIONAGI_RUN_ID=$run_id when spawning CLI subprocesses to inherit the parent run

Minor changes (§4–§8)

§4 last_branch.json schema — auto-normalized; direct parsers only. {"provider": "...", "branch_id": "..."} → {"run_id": "...", "branch_id": "..."}. Grep: grep -rn "last_branch.json" --include="*.py" .

  • ✓ Replace data["provider"] with data["run_id"] in direct JSON parsers

§5 Flat artifact dumps — path format changed. ./artifacts/r1_research.md → ./artifacts/r1/research.md Grep: grep -rn "artifact" --include="*.py" . | grep "_\.md"

  • ✓ Update: {id}_{name}.md → {agent_id}/{name}.md

§6 DAG op name — "instruct" → "operate" in run.json manifests; end-user CLI unaffected. Grep: grep -rn '"instruct"' --include="*.py" --include="*.json" .

  • ✓ Replace operation.type == "instruct" with "operate" in custom flow plugins §7 "codex/gpt-5.4" fallback — ValueError: Provider must be provided if model unset.

  • ✓ Add --model codex/gpt-5.4 or export LIONAGI_CHAT_MODEL=codex/gpt-5.4 §8 TEAM_WORKER_SYSTEM — now BARE_WORKER_SYSTEM + TEAM_COORD_SECTION; may double-include base. Grep: grep -rn "TEAM_WORKER_SYSTEM\|TEAM_COORD_SECTION" --include="*.py" .

  • ✓ Use TEAM_COORD_SECTION for coordination-only block; audit custom prompts for duplicate base See also: CHANGELOG.md — 0.22.6 entry.