Skip to content

Migration Guide

weego edited this page Nov 15, 2026 · 3 revisions

Migration Guide

This guide covers practical upgrades across recent LightAgent versions.

For an upgrade to v1.0.0, start with deployment, migration, and verification, particularly for optional dependencies, historical backups, and the separate LightResearch extension. The sections below describe earlier version transitions.

Summary

  • Existing agent.run("hello") code remains compatible.
  • Existing agent.run(query, stream=True, user_id=user_id) code remains compatible.
  • Structured results are opt-in through result_format.
  • Tracing is opt-in through trace=True.
  • LightFlow is additive in v0.8.0; existing LightAgent and LightSwarm calls do not need to change.
  • Memory isolation is stronger when MemoryPolicy or memory_namespace is configured.

v0.7.0 to v0.8.0

LightFlow

v0.8.0 adds LightFlow for deterministic multi-step workflows. It is an additive API, so existing code such as agent.run("hello"), streaming runs, tools, memory, Skills, and LightSwarm remains compatible.

Import LightFlow only when you want workflow orchestration:

from LightAgent import LightAgent, LightFlow

flow = (
    LightFlow()
    .step("research", agent=research_agent)
    .step("write", agent=writer_agent, depends_on=["research"])
)

result = flow.run("Analyze this company", trace=True)
print(result.content)

Use LightFlow for fixed DAG-style workflows. Continue using LightSwarm when you want model-directed handoff between agents.

The initial v0.8.0 scope is non-streaming workflow execution. Durable execution, human approval nodes, and resume support are planned for later versions.

Validation and examples:

PYTHONPATH=. python -m pytest -q tests/test_lightflow.py
python example/10.lightflow.py

v0.6.4 to v0.6.5

Default Return Value

No change is required:

response = agent.run("hello")
print(response)  # str

Use structured results only when needed:

result = agent.run("hello", result_format="object")
print(result.content)
print(result.tool_calls)
print(result.error)

Streaming

Legacy streaming remains compatible:

for chunk in agent.run(query, stream=True, user_id=user_id):
    print(chunk, end="")

Structured stream events are opt-in:

for event in agent.run(query, stream=True, user_id=user_id, result_format="event"):
    print(event.type, event.data)

Tool Arguments

Tool argument validation is stricter. Check that:

  • tool_info["tool_params"] names match the Python function parameters.
  • Required parameters are listed correctly.
  • Types are JSON-schema-like values such as string, integer, number, boolean, array, and object.

v0.6.5 to v0.7.0

Tracing

Tracing is new and disabled by default:

result = agent.run("hello", result_format="object", trace=True)
print(result.trace_id)
print(result.trace)

For string compatibility mode:

response = agent.run("hello", trace=True)
trace = agent.export_trace()

Model request trace events store prompt-safe summaries, not full prompts. Tool arguments and tool outputs may appear in traces because they are required for debugging tool behavior.

Memory Isolation

For single-user experiments, existing memory adapters can continue to work.

For shared deployments, prefer:

from LightAgent import MemoryPolicy

agent = LightAgent(
    model="gpt-4.1",
    api_key="your_api_key",
    base_url="https://api.openai.com/v1",
    memory=memory_backend,
    memory_policy=MemoryPolicy(
        namespace="tenant-a",
        allow_unattributed_results=False,
    ),
)

Shortcut:

agent = LightAgent(
    model="gpt-4.1",
    api_key="your_api_key",
    base_url="https://api.openai.com/v1",
    memory=memory_backend,
    memory_namespace="tenant-a",
)

Environment Variables

Use:

OPENAI_API_KEY
OPENAI_BASE_URL

Do not use the old OPENAI_API_BASE name in new examples.

Upgrade Checklist

  1. Update package version.
  2. Replace old repository links with https://github.com/wanxingai/LightAgent.
  3. Confirm OPENAI_BASE_URL is used.
  4. Run the minimal agent example.
  5. Run at least one tool-calling example.
  6. Run memory examples with stable user_id.
  7. Add MemoryPolicy for shared memory backends.
  8. Use trace=True when debugging new failures.
  9. Use LightFlow when a task needs deterministic multi-step orchestration.
  10. Run focused tests before opening a PR.

Clone this wiki locally