Multi Agent

Multi-Agent

LightSwarm is LightAgent's lightweight multi-agent helper. It registers named agents and lets a selected entry agent route work to another registered agent when the task matches that agent's role.

Basic Example

from LightAgent import LightAgent, LightSwarm

front_desk = LightAgent(
    name="FrontDesk",
    instructions="You route users to the right specialist.",
    role="Front desk assistant.",
    model="gpt-4.1",
    api_key="your_api_key",
    base_url="https://api.openai.com/v1",
)

hr_agent = LightAgent(
    name="HR",
    instructions="You answer HR onboarding, leave, and benefits questions.",
    role="HR specialist.",
    model="gpt-4.1",
    api_key="your_api_key",
    base_url="https://api.openai.com/v1",
)

it_agent = LightAgent(
    name="IT",
    instructions="You answer technical support questions.",
    role="IT support specialist.",
    model="gpt-4.1",
    api_key="your_api_key",
    base_url="https://api.openai.com/v1",
)

swarm = LightSwarm()
swarm.register_agent(front_desk, hr_agent, it_agent)

response = swarm.run(
    agent=front_desk,
    query="I need help with employee onboarding.",
    stream=False,
)
print(response)

Design Notes

• Give each agent a unique name.
• Keep instructions and role focused.
• Start the run from an entry agent, usually a router or front-desk agent.
• Use specialized tools and memory per agent when roles need different capabilities.
• Keep high-risk actions behind explicit tools and guardrails.

Debugging Handoffs

Use debug=True or trace=True when diagnosing routing:

result = front_desk.run(
    "I need help with employee onboarding.",
    light_swarm=swarm,
    result_format="object",
    trace=True,
)

print(result.content)
print(result.trace)

Common issues:

• The target agent name is ambiguous.
• The entry agent is not registered in the swarm.
• Agent roles overlap too much.
• The model provider has weak tool or reasoning behavior.

More detail: Multi-agent failure map.