Skip to content

Known Limitations

weego edited this page Nov 15, 2026 · 2 revisions

Known Limitations

This page documents current constraints so users can design around them.

Model Function Calling Varies

LightAgent uses OpenAI-compatible tool schemas, but not every compatible provider implements function calling equally well.

Symptoms:

  • the model ignores tools
  • arguments are missing or malformed
  • streaming tool-call chunks differ from OpenAI behavior

Mitigation:

  • test the provider with example/02.tools_agent.py
  • use result_format="object" and trace=True
  • keep tool schemas small and explicit

Durable Execution Is Explicit

Default agent.run() is not a durable task. Use LightFlow checkpoints for fixed workflows, LightDAG for dynamic verified graphs, or ExecutionService for reconnectable long-running tasks. There is no generic LightAgent.resume(run_id).

Mitigation:

  • make high-value tools idempotent
  • persist external side effects in your application layer
  • store important intermediate outputs outside the agent process

v1.0.0 durable execution is single-host and does not guarantee exactly-once external side effects.

LightSwarm Is Lightweight Routing

LightSwarm is useful for simple agent handoff, but it is not a deterministic workflow engine.

Use LightFlow or LightDAG when you need explicit dependencies, verification, or durable state.

MCP Session Lifecycle Is Basic

MCP integration registers tools from enabled servers and calls them through the configured transport. Long-lived enterprise MCP operation may need additional supervision in the application layer.

Mitigation:

  • test MCP servers independently
  • keep server config small
  • disable unused servers
  • add retries and health checks outside the agent when needed

Built-in Python Execution Tools Are Powerful

Legacy arbitrary-Python tools are not registered by default and are blocked in model/tool dispatch. Direct trusted application calls are not sandboxed; see the v1.0.0 safety guide.

Mitigation:

  • do not expose them to arbitrary users without isolation
  • restrict filesystem and network access
  • add approval for high-risk actions
  • review logs for side effects

Memory Security Depends on the Backend

LightAgent provides a small memory protocol and MemoryPolicy, but the backend remains responsible for persistence, provenance, deletion, access control, and conflict handling.

Mitigation:

  • use namespaces
  • store provenance metadata
  • filter by user, tenant, agent, and trust level
  • treat retrieved memories as untrusted context

Skills Are Not Signed Packages

Default Skill discovery is not a trust approval mechanism. v1.0.0 supports explicit Provider attestation and host trust approval, including attestation for Skill bundles when the host opts in.

Mitigation:

  • review third-party Skills
  • inspect scripts before execution
  • keep Skills in trusted repositories

Tool Generator Produces Draft Code

create_tool() generates code from a prompt. Generated code can be incomplete, unsafe, or incompatible with production requirements.

Mitigation:

  • review generated imports and side effects
  • add tests
  • run static checks
  • avoid committing secrets

Trace Data Can Contain Sensitive Tool Context

Trace model request events avoid full prompts by default, but tool arguments and outputs can contain sensitive values.

Mitigation:

  • redact sensitive values before sharing traces
  • disable tracing for sensitive workloads unless needed
  • keep logs and trace exports access-controlled

Clone this wiki locally