Tracing and Debugging

Tracing and Debugging

LightAgent supports human-readable debug logs and optional structured trace events.

Structured Tracing

Pass trace=True:

result = agent.run(
    "Check the weather in Shanghai.",
    result_format="object",
    trace=True,
)

print(result.trace_id)
print(result.trace)

You can also read the latest trace from the agent:

for event in agent.export_trace():
    print(event["type"], event["data"])

Trace events can include:

• run_start
• model_request
• model_response
• tool_call
• tool_result
• error
• run_end

Model request traces summarize metadata such as model name, stream mode, message count, and tool names. They do not store full prompt content by default.

LightFlow Trace Events

LightFlow uses flow-level trace events when trace=True is passed to flow.run():

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

for event in result.trace:
    print(event["type"], event["data"])

Flow trace events include:

• flow_start
• step_start
• step_end
• flow_end

Step results can also preserve the underlying agent trace when the step agent returns a structured RunResult.

Structured Streaming Events

for event in agent.run("Tell me a short story.", stream=True, result_format="event"):
    print(event.type, event.data)

Use this mode when building UI or API layers that need typed stream events instead of raw text chunks.

Debug Logs

Enable local debug logging:

agent = LightAgent(
    model="gpt-4.1",
    api_key="your_api_key",
    base_url="https://api.openai.com/v1",
    debug=True,
    log_level="DEBUG",
    log_file="agent.log",
)

Logs are written under logs/.

Error Codes

LightAgent formats common failures with stable error codes:

Code	Meaning
LA-400	Bad request
LA-401	Authentication or authorization failure
LA-404	Model, endpoint, or resource not found
LA-413	Request too large
LA-429	Rate limit
LA-JSON	Malformed JSON or tool arguments
LA-TOOL	Tool execution failure

Recommended Debug Flow

1. Reproduce with result_format="object".
2. Enable trace=True.
3. Confirm provider model, api_key, and base_url.
4. Inspect tool schemas and required arguments.
5. Retry without memory and Skills if the issue may be context-related.
6. Use a minimal tool to isolate model tool-calling behavior.

More detail:

• Tracing docs
• Error handling docs