Migration Guide

Migration Guide

This guide covers practical upgrades across recent LightAgent versions.

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.