Skip to content

V1 Getting Started en

weego edited this page Nov 15, 2026 · 4 revisions

Installation and Your First Agent

简体中文 | English

Applies to LightAgent v1.0.0. The default Agent in this guide uses an OpenAI-compatible Chat Completions service. To use an authenticated local Codex CLI instead of configuring a model API, see Agent Backends and Codex.

1. Choose how to install

Installation from PyPI and installation from source are alternatives. Choose one. Create an isolated virtual environment first. This release's CI covers Python 3.10–3.13:

python -m venv .venv
source .venv/bin/activate

On Windows PowerShell, activate it with .\.venv\Scripts\Activate.ps1.

Option 1: Install from PyPI (recommended)

pip downloads the published package; no Git or source checkout is required. Choose one command below: the base package for core features, selected extras for specific integrations, or all for every optional Python dependency.

pip install lightagent
pip install 'lightagent[mcp,mem0]'
pip install 'lightagent[all]'

These commands install the same package with different optional dependencies. To pin PyPI v1.0.0, use pip install 'lightagent==1.0.0' or pip install 'lightagent[all]==1.0.0'.

Option 2: Install from GitHub source

Git is required. pip fetches the v1.0.0 source tag from GitHub and builds LightAgent locally instead of downloading the LightAgent package from PyPI. Dependencies are still typically resolved from the package index. You do not need to run Option 1 first.

python -m pip install 'git+https://github.com/wanxingai/LightAgent.git@v1.0.0'

To install from source with all optional dependencies, use this instead:

python -m pip install 'lightagent[all] @ git+https://github.com/wanxingai/LightAgent.git@v1.0.0'

Verify the installed version

python -c 'from LightAgent import __version__; print(__version__)'

An ordinary Agent does not require Codex, Docker, LightResearch, the MCP SDK, or a database. See the base and optional dependencies table for what each extra installs and what you still need to configure.

2. Start a conversation with the native backend

Set LIGHTAGENT_MODEL, LIGHTAGENT_API_KEY, and LIGHTAGENT_BASE_URL before running this example. Inject the key from the environment or a secret manager rather than putting it in source. Use the model ID and base URL from your provider. The base URL is usually the /v1 root, not /chat/completions.

import os

from LightAgent import LightAgent

agent = LightAgent(
    name="docs-demo",
    instructions="你是一个用中文简洁回答的助手。",
    model=os.environ["LIGHTAGENT_MODEL"],
    api_key=os.environ["LIGHTAGENT_API_KEY"],
    base_url=os.environ["LIGHTAGENT_BASE_URL"],
    auto_discover_skills=False,
)

print(agent.run("用一句话介绍 LightAgent。"))

result = agent.run("给出三个项目验收要点。", result_format="object", trace=True)
if result.error:
    raise RuntimeError(result.error)
print(result.content)
print(result.usage, result.trace_id)

name identifies the Agent, instructions defines its behavior, and role can describe its responsibilities for LightSwarm routing. ToT and self-learning are disabled by default. This example disables automatic Skill discovery so the current project's files do not affect the run. For OpenAI, DeepSeek, Qwen, OpenRouter, Atlas Cloud, or local vLLM and llama.cpp, verify model IDs, function calling, and streaming against the provider: API compatibility does not imply identical behavior. provider="litellm" requires the corresponding extra. See Model Provider Configuration.

3. Choose a result format and execution style

Call What it returns and when to use it
agent.run(query) The compatible string return, for the simplest call.
agent.run(query, result_format="object", trace=True) A RunResult with content, error, usage, tool summaries, and a trace. Missing usage is not zero usage.
agent.run(query, stream=True) The compatible streaming iterator. Forward chunks using the protocol your application expects.
agent.run(query, stream=True, result_format="event") An iterator of StreamEvent objects; dispatch by type and data.
await agent.arun(query) Use in async applications. In streaming mode, await the iterator, then consume it with async for.

See Usage and Budgets for token counts, cost estimates, and missing usage.

Continue with the agent created above:

for event in agent.run("讲一个简短的技术比喻。", stream=True, result_format="event"):
    print(event.type, event.data)
import asyncio

async def main():
    result = await agent.arun("你好", result_format="object")
    if result.error:
        raise RuntimeError(result.error)
    print(result.content)

asyncio.run(main())

For native execution, max_retry controls retries and max_tool_iterations caps the tool loop. Omitting the latter preserves the previous behavior. Check structured errors for timeouts and policy rejections rather than treating those as business success. A final output rule cannot retract content already streamed to a client; where review is required, buffer and inspect the response in your application. See Error Handling and Safety, Observability, and Evaluation.

4. Optional planning and self-learning

  • tree_of_thought=True adds planning and tool selection. Enable it when there are many tools or the work benefits from decomposition, and measure the added latency and call cost. You can configure tot_model, tot_api_key, and tot_base_url separately. See Tree of Thought.
  • self_learning=True uses memory to generate reflections. Internal reflections are not directly injectable user memories. Configure isolation, review, promotion, and cleanup before enabling it. See Memory and RAG.
  • An ordinary conversation does not automatically become a reconnectable task. Use LightFlow for fixed workflows, LightDAG for dynamic workflows, and ExecutionService for ordinary tasks that must survive a process restart.

Clone this wiki locally