{ "canonical_name": "microsoft/agent-lightning", "compilation_id": "pack_158051757b46470abf9be1c687dd834f", "created_at": "2026-05-21T09:16:07.819778+00:00", "created_by": "project-pack-compiler", "feedback": { "carrier_selection_notes": [ "viable_asset_types=skill, recipe, host_instruction, eval, preflight", "recommended_asset_types=skill, recipe, host_instruction, eval, preflight" ], "evidence_delta": { "confirmed_claims": [ "identity_anchor_present", "capability_and_host_targets_present", "install_path_declared_or_better" ], "missing_required_fields": [], "must_verify_forwarded": [ "Run or inspect `pip install agentlightning` in an isolated environment.", "Confirm the project exposes the claimed capability to at least one target host." ], "quickstart_execution_scope": "allowlisted_sandbox_smoke", "sandbox_command": "pip install agentlightning", "sandbox_container_image": "python:3.12-slim", "sandbox_execution_backend": "docker", "sandbox_planner_decision": "llm_execute_isolated_install", "sandbox_validation_id": "sbx_eeadcb5857144158b92e94d8ca569d59" }, "feedback_event_type": "project_pack_compilation_feedback", "learning_candidate_reasons": [], "template_gaps": [] }, "identity": { "canonical_id": "project_881090af417e3985d27876dc0763be86", "canonical_name": "microsoft/agent-lightning", "homepage_url": null, "license": "unknown", "repo_url": "https://github.com/microsoft/agent-lightning", "slug": "agent-lightning", "source_packet_id": "phit_120f65fdc5bf4dea9a3c4d2f7f4b74c3", "source_validation_id": "dval_7811550190c749da836bb4a10c48be53" }, "merchandising": { "best_for": "需要软件开发与交付能力，并使用 chatgpt的用户", "github_forks": null, "github_stars": null, "one_liner_en": "

", "one_liner_zh": "

", "primary_category": { "category_id": "software-development", "confidence": "medium", "name_en": "Software Development", "name_zh": "软件开发与交付", "reason": "matched_keywords:git" }, "target_user": "使用 chatgpt 等宿主 AI 的用户", "title_en": "agent-lightning", "title_zh": "agent-lightning 能力包", "visible_tags": [ { "label_en": "Knowledge Retrieval", "label_zh": "知识检索", "source": "repo_evidence_project_characteristics", "tag_id": "product_domain-knowledge-retrieval", "type": "product_domain" }, { "label_en": "Knowledge Base Q&A", "label_zh": "知识库问答", "source": "repo_evidence_project_characteristics", "tag_id": "user_job-knowledge-base-q-a", "type": "user_job" }, { "label_en": "Workflow Automation", "label_zh": "流程自动化", "source": "repo_evidence_project_characteristics", "tag_id": "core_capability-workflow-automation", "type": "core_capability" }, { "label_en": "Node-based Workflow", "label_zh": "节点式流程编排", "source": "repo_evidence_project_characteristics", "tag_id": "workflow_pattern-node-based-workflow", "type": "workflow_pattern" }, { "label_en": "Evaluation Suite", "label_zh": "评测体系", "source": "repo_evidence_project_characteristics", "tag_id": "selection_signal-evaluation-suite", "type": "selection_signal" } ] }, "packet_id": "phit_120f65fdc5bf4dea9a3c4d2f7f4b74c3", "page_model": { "artifacts": { "artifact_slug": "agent-lightning", "files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json", "REPO_INSPECTION.md", "CAPABILITY_CONTRACT.json", "EVIDENCE_INDEX.json", "CLAIM_GRAPH.json" ], "required_files": [ "PROJECT_PACK.json", "QUICK_START.md", "PROMPT_PREVIEW.md", "HUMAN_MANUAL.md", "AI_CONTEXT_PACK.md", "BOUNDARY_RISK_CARD.md", "PITFALL_LOG.md", "REPO_INSPECTION.json" ] }, "detail": { "capability_source": "Project Hit Packet + DownstreamValidationResult", "commands": [ { "command": "pip install agentlightning", "label": "Python / pip · 官方安装入口", "source": "https://github.com/microsoft/agent-lightning#readme", "verified": true } ], "display_tags": [ "知识检索", "知识库问答", "流程自动化", "节点式流程编排", "评测体系" ], "eyebrow": "软件开发与交付", "glance": [ { "body": "判断自己是不是目标用户。", "label": "最适合谁", "value": "需要软件开发与交付能力，并使用 chatgpt的用户" }, { "body": "先理解能力边界，再决定是否继续。", "label": "核心价值", "value": "

" }, { "body": "未完成验证前保持审慎。", "label": "继续前", "value": "publish to Doramagic.ai project surfaces" } ], "guardrail_source": "Boundary & Risk Card", "guardrails": [ { "body": "Prompt Preview 只展示流程，不证明项目已安装或运行。", "label": "Check 1", "value": "不要把试用当真实运行" }, { "body": "chatgpt", "label": "Check 2", "value": "确认宿主兼容" }, { "body": "publish to Doramagic.ai project surfaces", "label": "Check 3", "value": "先隔离验证" } ], "mode": "skill, recipe, host_instruction, eval, preflight", "pitfall_log": { "items": [ { "body": "README/documentation is current enough for a first validation pass.", "category": "能力坑", "evidence": [ "capability.assumptions | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | README/documentation is current enough for a first validation pass." ], "severity": "medium", "suggested_check": "将假设转成下游验证清单。", "title": "能力判断依赖假设", "user_impact": "假设不成立时，用户拿不到承诺的能力。" }, { "body": "未记录 last_activity_observed。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | last_activity_observed missing" ], "severity": "medium", "suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。", "title": "维护活跃度未知", "user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "downstream_validation.risk_items | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "进入安全/权限治理复核队列。", "title": "下游验证发现风险项", "user_impact": "下游已经要求复核，不能在页面中弱化。" }, { "body": "No sandbox install has been executed yet; downstream must verify before user use.", "category": "安全/权限坑", "evidence": [ "risks.safety_notes | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | No sandbox install has been executed yet; downstream must verify before user use." ], "severity": "medium", "suggested_check": "转成明确权限清单和安全审查提示。", "title": "存在安全注意事项", "user_impact": "用户安装前需要知道权限边界和敏感操作。" }, { "body": "no_demo", "category": "安全/权限坑", "evidence": [ "risks.scoring_risks | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | no_demo; severity=medium" ], "severity": "medium", "suggested_check": "把风险写入边界卡，并确认是否需要人工复核。", "title": "存在评分风险", "user_impact": "风险会影响是否适合普通用户安装。" }, { "body": "issue_or_pr_quality=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | issue_or_pr_quality=unknown" ], "severity": "low", "suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。", "title": "issue/PR 响应质量未知", "user_impact": "用户无法判断遇到问题后是否有人维护。" }, { "body": "release_recency=unknown。", "category": "维护坑", "evidence": [ "evidence.maintainer_signals | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | release_recency=unknown" ], "severity": "low", "suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。", "title": "发布节奏不明确", "user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。" } ], "source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals", "summary": "发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：能力坑 - 能力判断依赖假设。", "title": "踩坑日志" }, "snapshot": { "contributors": null, "forks": null, "license": "unknown", "note": "站点快照，非实时质量证明；用于开工前背景判断。", "stars": null }, "source_url": "https://github.com/microsoft/agent-lightning", "steps": [ { "body": "不安装项目，先体验能力节奏。", "code": "preview", "title": "先试 Prompt" }, { "body": "理解输入、输出、失败模式和边界。", "code": "manual", "title": "读说明书" }, { "body": "把上下文交给宿主 AI 继续工作。", "code": "context", "title": "带给 AI" }, { "body": "进入主力环境前先完成安装入口与风险边界验证。", "code": "verify", "title": "沙箱验证" } ], "subtitle": "

", "title": "agent-lightning 能力包", "trial_prompt": "# agent-lightning - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for microsoft/agent-lightning.\n\nProject:\n- Name: agent-lightning\n- Repository: https://github.com/microsoft/agent-lightning\n- Summary:

\n- Host target: chatgpt\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet:

\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1:

\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. introduction: Introduction to Agent Lightning. Produce one small intermediate artifact and wait for confirmation.\n2. architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n3. core_abstractions: Core Abstractions and Data Models. Produce one small intermediate artifact and wait for confirmation.\n4. train-first-agent: Tutorial: Train Your First Agent. Produce one small intermediate artifact and wait for confirmation.\n5. write-agents: Tutorial: Writing Agents. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/microsoft/agent-lightning#readme\n- README.md\n- agentlightning/__init__.py\n- docs/deep-dive/birds-eye-view.md\n- agentlightning/trainer/trainer.py\n- agentlightning/store/base.py\n- agentlightning/types/core.py\n- agentlightning/types/resources.py\n- agentlightning/types/tracer.py\n- docs/how-to/train-first-agent.md\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n", "voices": [ { "body": "来源平台：github。github/github_issue: Intermittent missing openai.chat.completion spans from query_spans (RLin（https://github.com/microsoft/agent-lightning/issues/525）；github/github_issue: Question about Code Availability for EMPO^2 Paper（https://github.com/microsoft/agent-lightning/issues/511）；github/github_issue: calc-x example fails on next（https://github.com/microsoft/agent-lightning/issues/498）；github/github_issue: APO's TraceToMessages adapter fails with multi-turn agent rollouts (KeyE（https://github.com/microsoft/agent-lightning/issues/425）；github/github_issue: Installation Problem（https://github.com/microsoft/agent-lightning/issues/521）；github/github_issue: GRPO grouping in multi-turn agent RL: is it valid to mix samples with di（https://github.com/microsoft/agent-lightning/issues/489）；github/github_issue: Announcing Solantra: Next-Gen Blockchain on Solana（https://github.com/microsoft/agent-lightning/issues/515）；github/github_issue: Add interaction scripts and token utilities（https://github.com/microsoft/agent-lightning/issues/514）；github/github_issue: blockchain project（https://github.com/microsoft/agent-lightning/issues/513）；github/github_release: Agent Lightning v0.3.0（https://github.com/microsoft/agent-lightning/releases/tag/v0.3.0）；github/github_release: Agent Lightning v0.2.2（https://github.com/microsoft/agent-lightning/releases/tag/v0.2.2）；github/github_release: Agent Lightning v0.2.1（https://github.com/microsoft/agent-lightning/releases/tag/v0.2.1）。这些是项目级外部声音，不作为单独质量证明。", "items": [ { "kind": "github_issue", "source": "github", "title": "Intermittent missing openai.chat.completion spans from query_spans (RLin", "url": "https://github.com/microsoft/agent-lightning/issues/525" }, { "kind": "github_issue", "source": "github", "title": "Question about Code Availability for EMPO^2 Paper", "url": "https://github.com/microsoft/agent-lightning/issues/511" }, { "kind": "github_issue", "source": "github", "title": "calc-x example fails on next", "url": "https://github.com/microsoft/agent-lightning/issues/498" }, { "kind": "github_issue", "source": "github", "title": "APO's TraceToMessages adapter fails with multi-turn agent rollouts (KeyE", "url": "https://github.com/microsoft/agent-lightning/issues/425" }, { "kind": "github_issue", "source": "github", "title": "Installation Problem", "url": "https://github.com/microsoft/agent-lightning/issues/521" }, { "kind": "github_issue", "source": "github", "title": "GRPO grouping in multi-turn agent RL: is it valid to mix samples with di", "url": "https://github.com/microsoft/agent-lightning/issues/489" }, { "kind": "github_issue", "source": "github", "title": "Announcing Solantra: Next-Gen Blockchain on Solana", "url": "https://github.com/microsoft/agent-lightning/issues/515" }, { "kind": "github_issue", "source": "github", "title": "Add interaction scripts and token utilities", "url": "https://github.com/microsoft/agent-lightning/issues/514" }, { "kind": "github_issue", "source": "github", "title": "blockchain project", "url": "https://github.com/microsoft/agent-lightning/issues/513" }, { "kind": "github_release", "source": "github", "title": "Agent Lightning v0.3.0", "url": "https://github.com/microsoft/agent-lightning/releases/tag/v0.3.0" }, { "kind": "github_release", "source": "github", "title": "Agent Lightning v0.2.2", "url": "https://github.com/microsoft/agent-lightning/releases/tag/v0.2.2" }, { "kind": "github_release", "source": "github", "title": "Agent Lightning v0.2.1", "url": "https://github.com/microsoft/agent-lightning/releases/tag/v0.2.1" } ], "status": "已收录 13 条来源", "title": "社区讨论" } ] }, "homepage_card": { "category": "软件开发与交付", "desc": "

", "effort": "安装已验证", "forks": null, "icon": "code", "name": "agent-lightning 能力包", "risk": "可发布", "slug": "agent-lightning", "stars": null, "tags": [ "知识检索", "知识库问答", "流程自动化", "节点式流程编排", "评测体系" ], "thumb": "gray", "type": "Skill Pack" }, "manual": { "markdown": "# https://github.com/microsoft/agent-lightning Project Manual\n\nGenerated on: 2026-05-21 09:13:59 UTC\n\n## Table of Contents\n\n- [Introduction to Agent Lightning](#introduction)\n- [Installation Guide](#installation)\n- [System Architecture](#architecture)\n- [Core Abstractions and Data Models](#core_abstractions)\n- [Tutorial: Train Your First Agent](#train-first-agent)\n- [Tutorial: Writing Agents](#write-agents)\n- [Trainer Component](#trainer)\n- [Runner Component](#runner)\n- [LightningStore](#store)\n- [Algorithm Zoo](#algorithm-zoo)\n\n\n\n## Introduction to Agent Lightning\n\n### Related Pages\n\nRelated topics: [System Architecture](#architecture), [Installation Guide](#installation)\n\n

\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/microsoft/agent-lightning/blob/main/README.md)\n- [CLAUDE.md](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n- [AGENTS.md](https://github.com/microsoft/agent-lightning/blob/main/AGENTS.md)\n- [examples/minimal/README.md](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/README.md)\n- [examples/claude_code/README.md](https://github.com/microsoft/agent-lightning/blob/main/examples/claude_code/README.md)\n- [agentlightning/types/core.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n- [agentlightning/runner/base.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/base.py)\n- [agentlightning/semconv.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/semconv.py)\n- [agentlightning/cli/__init__.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/cli/__init__.py)\n- [contrib/recipes/agentos/README.md](https://github.com/microsoft/agent-lightning/blob/main/contrib/recipes/agentos/README.md)\n- [dashboard/README.md](https://github.com/microsoft/agent-lightning/blob/main/dashboard/README.md)\n- [mkdocs.yml](https://github.com/microsoft/agent-lightning/blob/main/mkdocs.yml)\n
\n\n# Introduction to Agent Lightning\n\nAgent Lightning is a reinforcement learning framework designed to train any AI agent with RL algorithms. The project provides a unified execution stack, instrumentation capabilities, and training infrastructure that enables researchers and developers to improve agent behavior through reward-based learning. Source: [README.md:1](https://github.com/microsoft/agent-lightning/blob/main/README.md)\n\n## What is Agent Lightning?\n\nAgent Lightning bridges the gap between raw agent execution and RL-based training by providing:\n\n- **Instrumentation Layer**: Transparent tracing and logging of agent interactions\n- **Training Infrastructure**: Built-in support for RL algorithms like GRPO\n- **Distributed Execution**: Multi-worker rollout management with state synchronization\n- **Integration Points**: Adapters for popular agent frameworks and execution environments\n\nThe framework treats agent training as a continuous feedback loop where traces collected from agent execution are consumed by training algorithms to improve policy behavior over time. Source: [CLAUDE.md:3](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n\n## Architecture Overview\n\nThe Agent Lightning architecture follows a producer-consumer pattern centered around trace collection and consumption.\n\n### Core Loop\n\n```mermaid\ngraph TD\n A[Runner] -->|emits spans| B[Tracers]\n B -->|writes traces| C[LightningStore]\n C -->|serves traces| D[Algorithms]\n D -->|updates policy| A\n C -->|serves traces| E[Dashboard]\n```\n\nThe continuous execution loop works as follows:\n\n1. **Runners** execute agents and emit execution spans\n2. **Tracers** capture and format these spans with semantic conventions\n3. **LightningStore** maintains synchronized state across all components\n4. **Algorithms** consume traces to compute rewards and update agent policies\n5. **Dashboard** provides real-time visualization for debugging\n\nSource: [CLAUDE.md:3](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n\n### Component Hierarchy\n\n| Layer | Components | Responsibility |\n|-------|-----------|----------------|\n| Execution | `Runner`, `LitAgent` | Execute agent logic and manage lifecycle |\n| Instrumentation | `Tracer`, `OtelTracer`, `AgentOpsTracer` | Capture execution traces |\n| Storage | `LightningStore`, `LightningStoreClient` | Synchronized state management |\n| Training | Algorithms in `agentlightning/algorithm/` | Process traces, compute rewards |\n| CLI | `agl` command | User-facing interface |\n\nSource: [agentlightning/cli/__init__.py:13-16](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/cli/__init__.py)\n\n## Core Data Models\n\nThe framework defines several fundamental data structures in `agentlightning/types/core.py`.\n\n### Task and Rollout\n\n```mermaid\nclassDiagram\n class Task {\n +str task_id\n +Any input\n +Optional~str~ instance_id\n +Optional~str~ dataset\n }\n class Rollout {\n +str rollout_id\n +str status\n +Optional~str~ worker_id\n +List~Attempt~ attempts\n }\n class Attempt {\n +str attempt_id\n +str status\n +List~Span~ spans\n +Optional~float~ reward\n }\n class Triplet {\n +Any prompt\n +Any response\n +Optional reward\n }\n \n Task \"1\" --> \"*\" Rollout\n Rollout \"1\" --> \"*\" Attempt\n Attempt --> Triplet\n```\n\n### Core Type Exports\n\n| Type | Purpose |\n|------|---------|\n| `Task` | Represents a unit of work to be executed by an agent |\n| `Rollout` | Collection of attempts for a single task execution |\n| `Attempt` | Single execution attempt with spans and reward |\n| `Triplet` | Prompt-response-reward tuple for RL training |\n| `LightningStore` | Synchronized state store for distributed execution |\n\nSource: [agentlightning/types/core.py:1-60](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n\n## Runner System\n\nThe runner system provides the execution context for agents with integrated lifecycle management.\n\n### Runner Lifecycle\n\n```mermaid\nsequenceDiagram\n participant User\n participant Runner\n participant Store\n participant Agent\n \n User->>Runner: async with Runner(agent, store)\n Runner->>Runner: init(agent)\n Runner->>Runner: init_worker(store)\n Runner->>Store: Register worker\n Loop Until event\n Runner->>Agent: Execute task\n Agent-->>Runner: Result\n Runner->>Store: Update state\n end\n Runner->>Runner: teardown_worker()\n Runner->>Runner: teardown()\n```\n\n### Runner Base Class\n\nThe `Runner` class provides context manager support for safe initialization and cleanup:\n\n```python\nasync with runner:\n runner.init(agent=agent, hooks=hooks)\n runner.init_worker(worker_id=0, store=store)\n # Execute tasks...\n```\n\nKey runner responsibilities:\n- **Initialization**: Set up agent and worker state\n- **Execution**: Poll store for tasks and execute them\n- **Cleanup**: Graceful teardown of worker and agent resources\n\nSource: [agentlightning/runner/base.py:1-80](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/base.py)\n\n## Tracing and Instrumentation\n\nAgent Lightning provides multiple tracing backends for capturing agent execution.\n\n### Supported Tracers\n\n| Tracer | Use Case | Backend |\n|--------|----------|---------|\n| `OtelTracer` | OpenTelemetry-compatible tracing | OTLP endpoint |\n| `AgentOpsTracer` | AgentOps platform integration | AgentOps service |\n| Custom Tracer | Framework integration | Pluggable |\n\n### Semantic Conventions\n\nThe framework defines semantic conventions in `agentlightning/semconv.py` for consistent span attributes:\n\n| Attribute | Description |\n|-----------|-------------|\n| `LightningSpanAttributes.REWARD` | Reward values for RL spans |\n| `LightningSpanAttributes.LINK` | Span linking relationships |\n| `LightningSpanAttributes.TAG` | Custom span tagging |\n| `LightningResourceAttributes.ROLLOUT_ID` | Rollout identification |\n| `LightningResourceAttributes.ATTEMPT_ID` | Attempt identification |\n\nSource: [agentlightning/semconv.py:1-40](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/semconv.py)\n\n### Trace Writing Example\n\nThe minimal examples demonstrate trace writing with `LightningStore`:\n\n```python\nfrom agentlightning import AgentOpsTracer, LightningStoreClient, OtelTracer, Span\n\n# Write traces directly to in-memory store\nstore = InMemoryLightningStore()\ntracer = OtelTracer(store=store)\n\n# Or connect to a server-side store\nclient = LightningStoreClient(endpoint=\"http://localhost:45993\")\n```\n\nSource: [examples/minimal/write_traces.py:1-50](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/write_traces.py)\n\n## LightningStore\n\n`LightningStore` is the central state management component that keeps all components synchronized.\n\n### Store Capabilities\n\n```mermaid\ngraph LR\n A[Runners] -->|enqueue/dequeue| B[Rollouts]\n A -->|register| C[Workers]\n D[Tracers] -->|write spans| B\n E[Algorithms] -->|query traces| B\n F[Dashboard] -->|inspect state| B\n```\n\n### Store Collections\n\n| Collection | Data Type | Access Pattern |\n|------------|-----------|----------------|\n| `rollouts` | `Rollout` | Enqueue/dequeue by worker |\n| `attempts` | `Attempt` | Link to rollout |\n| `spans` | `Span` | Query by attempt |\n| `workers` | `Worker` | Heartbeat management |\n| `resources` | `ResourcesUpdate` | Model/prompt versioning |\n\nSource: [dashboard/test-utils/python-server.py:1-100](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n\n## Training Algorithms\n\nAgent Lightning integrates with reinforcement learning algorithms to improve agent behavior.\n\n### Algorithm Integration\n\nThe framework supports pluggable algorithms defined in `agentlightning/algorithm/`. Algorithms consume traces from the LightningStore and compute policy updates.\n\n### Agent-OS Integration\n\nFor production safety-critical deployments, Agent Lightning integrates with Agent-OS:\n\n```python\nfrom agentlightning.contrib.runner.agentos import AgentOSRunner\nfrom agentlightning.contrib.reward.agentos import PolicyReward\n\nrunner = AgentOSRunner(kernel, fail_on_violation=False, emit_violations=True)\nreward_fn = PolicyReward(kernel)\n```\n\nThis integration provides:\n- **Policy enforcement**: Kernel-level safety during training\n- **Violation penalties**: Unsafe actions convert to negative RL rewards\n- **Audit trail**: Complete visibility from training to production\n\nSource: [contrib/recipes/agentos/README.md:1-60](https://github.com/microsoft/agent-lightning/blob/main/contrib/recipes/agentos/README.md)\n\n## Minimal Component Showcase\n\nThe `examples/minimal/` directory provides isolated demonstrations of individual building blocks.\n\n### Available Examples\n\n| Component | File | Demonstrates |\n|-----------|------|--------------|\n| LightningStore + OTLP | `write_traces.py` | `OtelTracer`, `AgentOpsTracer`, rollout/span emission |\n| MultiMetrics backend | `write_metrics.py` | Console and Prometheus metrics simultaneously |\n| LLM proxying | `llm_proxy.py` | Request routing through `/rollout//attempt/` |\n| vLLM lifecycle | `vllm_server.py` | Server startup, readiness monitoring, teardown |\n\nEach example is self-documenting with CLI arguments and environment variables embedded in module docstrings.\n\nSource: [examples/minimal/README.md:1-30](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/README.md)\n\n## Command-Line Interface\n\nThe `agl` CLI provides entry points for all major framework operations.\n\n### Available Subcommands\n\n| Command | Module | Description |\n|---------|--------|-------------|\n| `agl vllm` | `agentlightning.cli.vllm` | vLLM server with instrumentation |\n| `agl store` | `agentlightning.cli.store` | LightningStore server |\n| `agl prometheus` | `agentlightning.cli.prometheus` | Prometheus metrics endpoint |\n| `agl agentops` | `agentlightning.cli.agentops_server` | AgentOps server manager |\n\n### Starting a LightningStore Server\n\n```bash\nagl store --port 45993 --log-level DEBUG\n```\n\nThe store server enables distributed execution where multiple workers can connect and synchronize state.\n\nSource: [agentlightning/cli/__init__.py:1-35](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/cli/__init__.py)\n\n## Dashboard\n\nThe Agent Lightning Dashboard is a React-based web application for inspecting store state and debugging experiments.\n\n### Features\n\n- **Real-time state inspection**: View rollouts, attempts, and spans\n- **Worker monitoring**: Track worker status and heartbeat statistics\n- **Resource visualization**: Inspect model configurations and prompts\n- **Experiment debugging**: Analyze trace sequences and reward flows\n\n### Technology Stack\n\n| Layer | Technology |\n|-------|------------|\n| Framework | React |\n| UI Components | Mantine UI |\n| Documentation | Storybook |\n| Testing | Vitest |\n\nSource: [dashboard/README.md:1-35](https://github.com/microsoft/agent-lightning/blob/main/dashboard/README.md)\n\n## Project Structure\n\n```\nagent-lightning/\n├── agentlightning/ # Core library\n│ ├── algorithm/ # RL training algorithms\n│ ├── cli/ # Command-line interface\n│ ├── contrib/ # Third-party integrations\n│ ├── runner/ # Execution runners\n│ ├── store/ # LightningStore implementations\n│ ├── tracer/ # Tracing backends\n│ ├── types/ # Data models\n│ └── semconv.py # Semantic conventions\n├── contrib/\n│ └── recipes/ # Integration examples (webshop, agentos)\n├── dashboard/ # React web application\n├── docs/ # Documentation (mkdocs)\n├── examples/ # Runnable workflows\n├── scripts/ # Automation scripts\n└── tests/ # Test suite\n```\n\nSource: [CLAUDE.md:5-15](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n\n## Development Workflow\n\n### Setup\n\n```bash\nuv sync --group dev\n```\n\n### Testing\n\n```bash\n# Full test suite\nuv run --no-sync pytest -v\n\n# Specific tests\nuv run --no-sync pytest -v tests/path/to/test.py\nuv run --no-sync pytest -v -k \"test_pattern\"\n```\n\n### Type Checking\n\n```bash\nuv run --no-sync pyright\n```\n\n### Pre-commit Checks\n\n```bash\nuv run --no-sync pre-commit run --all-files --show-diff-on-failure\n```\n\n### Documentation\n\n```bash\nuv run --no-sync mkdocs build --strict\n```\n\nSource: [CLAUDE.md:18-30](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n\n## Contributing\n\nAgent Lightning welcomes contributions through a structured process:\n\n1. **Branch naming**: `feature/`, `fix/`, `docs/`, or `chore/`\n2. **Commits**: Imperative, scoped commits with issue references (e.g., `Fixes #123`)\n3. **Pre-submission**: Run pre-commit hooks and relevant pytest/doc builds\n4. **CLA**: Contributor License Agreement required (automatically prompted by CLA bot)\n\nSource: [README.md:50-70](https://github.com/microsoft/agent-lightning/blob/main/README.md)\n\n## Citation\n\nIf you use Agent Lightning in research, please cite:\n\n```bibtex\n@misc{luo2025agentlightningtrainai,\n title={Agent Lightning: Train ANY AI Agents with Reinforcement Learning},\n author={Xufang Luo and Yuge Zhang and Zhiyuan He and Zilong Wang and Siyun Zhao and Dongsheng Li and Luna K. Qiu and Yuqing Yang},\n year={2025},\n eprint={2508.03680},\n archivePrefix={arXiv},\n primaryClass={cs.AI},\n url={https://arxiv.org/abs/2508.03680},\n}\n```\n\nSource: [README.md:15-25](https://github.com/microsoft/agent-lightning/blob/main/README.md)\n\n## Further Reading\n\n- [Minimal Examples Guide](../examples/minimal/) - Hands-on with individual components\n- [Claude Code Integration](../examples/claude_code/) - Example: Training with SWE-bench\n- [Agent-OS Integration](../contrib/recipes/agentos/) - Safety-critical training\n- [API Reference](../api/) - Detailed type and function documentation\n\n---\n\n\n\n## Installation Guide\n\n### Related Pages\n\nRelated topics: [Introduction to Agent Lightning](#introduction), [Tutorial: Train Your First Agent](#train-first-agent)\n\n
\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [docs/tutorials/installation.md](https://github.com/microsoft/agent-lightning/blob/main/docs/tutorials/installation.md)\n- [pyproject.toml](https://github.com/microsoft/agent-lightning/blob/main/pyproject.toml)\n- [CLAUDE.md](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n- [AGENTS.md](https://github.com/microsoft/agent-lightning/blob/main/AGENTS.md)\n- [contrib/recipes/webshop/agl/requirements.txt](https://github.com/microsoft/agent-lightning/blob/main/contrib/recipes/webshop/agl/requirements.txt)\n- [README.md](https://github.com/microsoft/agent-lightning/blob/main/README.md)\n
\n\n# Installation Guide\n\nThis guide covers all supported methods for installing and configuring Agent Lightning in your environment. Agent Lightning is a reinforcement learning framework for training AI agents, with support for GPU acceleration, distributed training, and various algorithm backends.\n\n## Prerequisites\n\n### System Requirements\n\n| Component | Minimum | Recommended |\n|-----------|---------|-------------|\n| Python | 3.10+ | 3.11 or 3.12 |\n| OS | Linux (Ubuntu 20.04+), macOS | Linux with CUDA |\n| RAM | 8 GB | 32 GB+ |\n| GPU | Optional | NVIDIA GPU with CUDA 11.8+ |\n| Disk Space | 5 GB | 20 GB+ |\n\nSource: [contrib/recipes/webshop/agl/requirements.txt:1-3]()\n\n### Required Tools\n\n- **uv**: Modern Python package manager (recommended)\n- **Git**: For cloning the repository\n- **CUDA Toolkit** (for GPU training): Version 11.8 or later\n\n## Installation Methods\n\n### Method 1: Install from Source\n\nThis is the recommended approach for development and contributing.\n\n```bash\n# Clone the repository\ngit clone https://github.com/microsoft/agent-lightning.git\ncd agent-lightning\n\n# Install all dependencies including development tools\nuv sync --group dev\n\n# Install optional GPU dependencies\nuv sync --group GPU\n```\n\nSource: [CLAUDE.md:20-22]()\n\n### Method 2: Install with Specific Algorithm Backends\n\nAgent Lightning supports multiple reinforcement learning algorithms through optional dependency groups:\n\n```bash\n# Install with VERL backend (recommended for GPU training)\nuv sync --group VERL\n\n# Install with APO backend\nuv sync --group APO\n\n# Install with GPU optimizations\nuv sync --group GPU\n```\n\nSource: [CLAUDE.md:22]()\n\n### Method 3: Using setup.sh for GPU Training\n\nFor GPU-accelerated training with the webshop recipe:\n\n```bash\n# From the contrib/recipes/webshop directory\n./setup.sh\n```\n\nThis script installs VERL extras for GPU training support. Source: [contrib/recipes/webshop/agl/requirements.txt:1-8]()\n\n## Dependency Groups\n\nThe `pyproject.toml` defines several optional dependency groups:\n\n| Group | Purpose | Installation Command |\n|-------|---------|---------------------|\n| `dev` | Development tools (pytest, pyright, pre-commit) | `uv sync --group dev` |\n| `GPU` | GPU acceleration packages | `uv sync --group GPU` |\n| `VERL` | VERL algorithm backend | `uv sync --group VERL` |\n| `APO` | APO algorithm backend | `uv sync --group APO` |\n\nSource: [CLAUDE.md:20-23]()\n\n## Environment Setup\n\n### Creating a Virtual Environment\n\nUsing `uv` (recommended):\n\n```bash\n# Create and activate a new virtual environment\nuv venv\nsource .venv/bin/activate # Linux/macOS\n# or\n.venv\\Scripts\\activate # Windows\n```\n\n### Verifying Installation\n\nRun the test suite to verify your installation:\n\n```bash\n# Run all tests\nuv run --no-sync pytest -v\n\n# Run specific test\nuv run --no-sync pytest -v tests/path/to/test.py\n\n# Run tests matching a pattern\nuv run --no-sync pytest -v -k \"test_pattern\"\n```\n\nSource: [CLAUDE.md:21]()\n\n### Type Checking\n\nVerify type annotations are correct:\n\n```bash\nuv run --no-sync pyright\n```\n\nSource: [CLAUDE.md:22]()\n\n### Pre-commit Hooks\n\nBefore committing code, run pre-commit checks:\n\n```bash\nuv run --no-sync pre-commit run --all-files --show-diff-on-failure\n```\n\nSource: [CLAUDE.md:23]()\n\n## Dashboard Installation\n\nThe Agent Lightning Dashboard is a separate React application:\n\n```bash\ncd dashboard\n\n# Install dependencies\nnpm install\n\n# Start development server\nnpm run dev\n\n# Build for production\nnpm run build\n```\n\nSource: [dashboard/README.md:npm scripts section]()\n\n### Dashboard npm Scripts\n\n| Script | Purpose |\n|--------|---------|\n| `dev` | Start development server |\n| `build` | Build production bundle |\n| `preview` | Preview production build locally |\n| `storybook` | Start Storybook dev server |\n| `build-storybook` | Build Storybook bundle |\n| `eslint` | Run ESLint |\n| `stylelint` | Run Stylelint |\n| `prettier` | Run Prettier |\n| `typecheck` | Run TypeScript typecheck |\n| `vitest` | Run vitest tests |\n\nSource: [dashboard/README.md:npm scripts]()\n\n## Recipe-Specific Installation\n\n### Webshop Recipe\n\nThe webshop recipe has specific dependencies:\n\n```bash\ncd contrib/recipes/webshop/agl\n\n# Install requirements\npip install -r requirements.txt\n\n# For GPU training\n./setup.sh\n```\n\nRequired dependencies include:\n- `pandas>=2.0.0` - Data manipulation\n- `pyarrow>=14.0.0` - Parquet file support\n- `rich>=13.0.0` - Terminal formatting\n- `tqdm>=4.64.0` - Progress bars\n\nSource: [contrib/recipes/webshop/agl/requirements.txt:1-15]()\n\n## Development Workflow\n\n### Branching Conventions\n\nCreate feature branches from a fresh `main`:\n\n| Branch Type | Naming Convention |\n|-------------|-------------------|\n| Feature | `feature/` |\n| Fix | `fix/` |\n| Documentation | `docs/` |\n| Maintenance | `chore/` |\n\nSource: [CLAUDE.md:8](), [AGENTS.md:8]()\n\n### Commit and PR Guidelines\n\n1. Write imperative, scoped commit messages\n2. Reference issues with `Fixes #123`\n3. Rerun pre-commit and relevant pytest/doc builds before pushing\n4. Include verification commands in PR descriptions\n5. Update documentation via `mkdocs.yml` or `examples/README.md`\n\nSource: [CLAUDE.md:9-13](), [AGENTS.md:9-13]()\n\n## GPU Configuration\n\nFor optimal GPU training performance:\n\n1. Install NVIDIA drivers (CUDA 11.8+)\n2. Install the `GPU` dependency group\n3. For VERL-based training, use `uv sync --group GPU`\n\nGPU metrics are tracked via heartbeat statistics in worker nodes:\n\n```python\nheartbeat_stats={\"queue_depth\": 2, \"gpu_utilization\": 0.82}\n```\n\nSource: [dashboard/test-utils/python-server.py:Worker class]()\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| `uv` command not found | Install uv: `pip install uv` |\n| CUDA not found | Ensure NVIDIA drivers and CUDA toolkit are installed |\n| Import errors | Run `uv sync` to ensure all dependencies are installed |\n| Type checking failures | Run `uv run --no-sync pyright` to identify issues |\n\nSource: [CLAUDE.md:26-30]()\n\n### Lock File Updates\n\nWhen dependencies change, commit the refreshed `uv.lock`:\n\n```bash\ngit add uv.lock\ngit commit -m \"chore: update lock file\"\n```\n\nSource: [CLAUDE.md:24]()\n\n## Next Steps\n\nAfter installation:\n\n1. Explore [Minimal Component Showcase](examples/minimal/README.md) to understand individual components\n2. Set up the [LightningStore](agentlightning/store/) for trace storage\n3. Configure [tracers](agentlightning/tracer/) for your agent execution\n4. Review the [Algorithm Documentation](docs/tutorials/) for training options\n\n---\n\n\n\n## System Architecture\n\n### Related Pages\n\nRelated topics: [Trainer Component](#trainer), [Runner Component](#runner), [LightningStore](#store)\n\n
\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [dashboard/src/layouts/AppLayout.tsx](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/layouts/AppLayout.tsx)\n- [dashboard/src/pages/Rollouts.page.tsx](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/pages/Rollouts.page.tsx)\n- [dashboard/src/pages/Resources.page.tsx](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/pages/Resources.page.tsx)\n- [dashboard/src/pages/Workers.page.tsx](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/pages/Workers.page.tsx)\n- [dashboard/src/components/TracesTable.component.tsx](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/TracesTable.component.tsx)\n- [dashboard/src/components/WorkersTable.component.tsx](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/WorkersTable.component.tsx)\n- [dashboard/src/components/AppDrawer.component.tsx](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/AppDrawer.component.tsx)\n- [dashboard/test-utils/python-server.py](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n
\n\n# System Architecture\n\n## Overview\n\nAgent Lightning is a reinforcement learning framework for training AI agents, with a distributed system architecture that supports multi-worker training orchestration, resource management, and distributed tracing. The system consists of three primary layers: a **Backend Training Engine**, a **State Store**, and a **Dashboard Frontend**.\n\nThe architecture enables parallel training across multiple workers, centralized resource configuration, and real-time monitoring of training workflows through traces and metrics.\n\nSource: [dashboard/src/layouts/AppLayout.tsx:1-50](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/layouts/AppLayout.tsx)\n\n## High-Level Architecture Components\n\nThe Agent Lightning system comprises the following core entities:\n\n| Component | Description | Key Attributes |\n|-----------|-------------|----------------|\n| **Resources** | Configuration templates for prompts, models, and sampling parameters | `resources_id`, `version`, `resources` (dict with PromptTemplate/LLM) |\n| **Workers** | Runner processes that execute training rollouts | `worker_id`, `status`, `heartbeat_stats`, `current_rollout_id` |\n| **Rollouts** | Complete training episodes with multiple attempts | `rollout_id`, `status`, `mode`, `attempts` |\n| **Attempts** | Individual training attempts within a rollout | `attempt_id`, `status`, `metrics` |\n| **Spans** | Distributed tracing spans for observability | `trace_id`, `span_id`, `status`, `attributes`, `start_time`, `end_time` |\n\nSource: [dashboard/test-utils/python-server.py:1-300](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n\n## Frontend Dashboard Architecture\n\nThe dashboard is a React-based frontend built with **Mantine UI** components that communicates with the backend via REST APIs.\n\n### Navigation Structure\n\nThe application uses a sidebar navigation layout with the following sections:\n\n```mermaid\ngraph TD\n A[AppLayout] --> B[Navbar]\n A --> C[Main Content Area]\n B --> D[Rollouts]\n B --> E[Workers]\n B --> F[Resources]\n B --> G[Traces]\n B --> H[Settings]\n C --> I[Outlet Component]\n```\n\nSource: [dashboard/src/layouts/AppLayout.tsx:20-50](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/layouts/AppLayout.tsx)\n\n### Page Components\n\n| Page | File Path | Purpose |\n|------|-----------|---------|\n| Rollouts | `dashboard/src/pages/Rollouts.page.tsx` | Display and manage training rollouts with status filtering |\n| Workers | `dashboard/src/pages/Workers.page.tsx` | Monitor worker health and current assignments |\n| Resources | `dashboard/src/pages/Resources.page.tsx` | View and manage configuration resources |\n| Traces | `dashboard/src/components/TracesTable.component.tsx` | Analyze distributed tracing spans |\n\nSource: [dashboard/src/pages/Rollouts.page.tsx:1-80](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/pages/Rollouts.page.tsx)\n\n## Data Flow Architecture\n\n### Worker Heartbeat Flow\n\nWorkers periodically send heartbeat signals to indicate their operational state. The dashboard monitors these heartbeats to determine worker availability.\n\n```mermaid\nsequenceDiagram\n participant W as Worker\n participant S as Store\n participant D as Dashboard\n \n W->>S: Heartbeat (status, queue_depth, gpu_utilization)\n S->>S: Update last_heartbeat_time\n D->>S: Poll /workers endpoint\n S-->>D: Worker list with status\n```\n\nSource: [dashboard/test-utils/python-server.py:100-150](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n\n### Rollout Execution Flow\n\nTraining rollouts follow a multi-attempt execution model:\n\n```mermaid\ngraph LR\n A[Rollout Created] --> B[Attempt 1]\n B --> C{Success?}\n C -->|Yes| D[Rollout Complete]\n C -->|No| E[Attempt 2]\n E --> F{Success?}\n F -->|Yes| D\n F -->|No| G[Attempt N]\n G --> H[Max Attempts Reached]\n```\n\nSource: [dashboard/src/components/TracesTable.component.tsx:50-150](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/TracesTable.component.tsx)\n\n## Core Entity Schemas\n\n### Resources Entity\n\nResources define reusable configuration templates used by workers during training.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `resources_id` | string | Unique identifier for the resource |\n| `version` | integer | Version number for tracking changes |\n| `create_time` | timestamp | Creation timestamp |\n| `update_time` | timestamp | Last modification timestamp |\n| `resources` | dict | Configuration dictionary (PromptTemplate, LLM configs) |\n\nSource: [dashboard/test-utils/python-server.py:50-100](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n\n### Workers Entity\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `worker_id` | string | Unique worker identifier |\n| `status` | enum | Current status: `idle`, `busy`, `offline` |\n| `heartbeat_stats` | dict | Metrics including `queue_depth`, `gpu_utilization` |\n| `last_heartbeat_time` | timestamp | Time of last heartbeat |\n| `current_rollout_id` | string | Currently assigned rollout (if busy) |\n| `current_attempt_id` | string | Currently executing attempt |\n\nSource: [dashboard/src/components/AppDrawer.component.tsx:1-60](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/AppDrawer.component.tsx)\n\n### Spans Entity (Distributed Tracing)\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `rollout_id` | string | Associated rollout |\n| `attempt_id` | string | Associated attempt |\n| `trace_id` | string | Distributed trace identifier |\n| `span_id` | string | Unique span identifier |\n| `parent_id` | string | Parent span ID for hierarchy |\n| `name` | string | Operation name (e.g., `classification_pipeline`) |\n| `status` | TraceStatus | Status with `status_code` (OK, ERROR) and description |\n| `attributes` | dict | Key-value metadata (model, batch_size, accuracy) |\n| `start_time` | timestamp | Span start time |\n| `end_time` | timestamp | Span end time |\n\nSource: [dashboard/src/components/TracesTable.component.tsx:50-120](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/TracesTable.component.tsx)\n\n## Component Architecture (Frontend)\n\n### Table Components Pattern\n\nThe dashboard uses a consistent table component pattern across all pages:\n\n```mermaid\ngraph TD\n A[Page Component] --> B[Table Component]\n B --> C[Column Definitions]\n B --> D[Filtering Logic]\n B --> E[Pagination Controls]\n A --> F[useQuery Hook]\n F --> G[API Endpoints]\n```\n\n| Component | Props | Purpose |\n|-----------|-------|---------|\n| `RolloutTable` | `rollouts`, `totalRecords`, `statusFilters`, `onViewTraces` | Training rollout display |\n| `WorkersTable` | `workers`, `onShowDetails` | Worker monitoring |\n| `ResourcesTable` | `resourcesList`, `renderRowExpansion` | Resource configuration |\n| `TracesTable` | `spans`, `onShowSpanDetail` | Trace analysis |\n\nSource: [dashboard/src/components/WorkersTable.component.tsx:1-80](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/WorkersTable.component.tsx)\n\n### Drawer Container Pattern\n\nThe application uses an `AppDrawerContainer` for displaying detailed information:\n\n```mermaid\ngraph TD\n A[AppDrawerContainer] --> B[Redux State]\n B --> C{Content Type}\n C -->|worker-detail| D[WorkerDrawerTitle]\n C -->|rollout-detail| E[RolloutDrawer]\n C -->|span-detail| F[SpanDetailDrawer]\n D --> G[ConnectionIndicator]\n G --> H[baseUrl, status, isRefreshing]\n```\n\nSource: [dashboard/src/components/AppDrawer.component.tsx:60-120](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/AppDrawer.component.tsx)\n\n## State Management\n\nThe frontend uses Redux for state management with the following key selectors:\n\n| Selector | Purpose |\n|----------|---------|\n| `selectConfig` | Application configuration (baseUrl, autoRefreshMs) |\n| `selectDrawerIsOpen` | Drawer visibility state |\n| `selectDrawerContent` | Current drawer content type and data |\n| `selectConnectionState` | Backend connection status |\n\nSource: [dashboard/src/layouts/AppLayout.tsx:50-80](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/layouts/AppLayout.tsx)\n\n## Connection Management\n\nThe dashboard includes a `ConnectionIndicator` component that displays the connection status to the backend:\n\n| Status | Description |\n|--------|-------------|\n| `connected` | Successfully connected to backend |\n| `disconnected` | Cannot reach backend |\n| `refreshing` | Actively reconnecting |\n\nSource: [dashboard/src/layouts/AppLayout.tsx:40-45](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/layouts/AppLayout.tsx)\n\n## Training Workflow Integration\n\n### Status Lifecycle\n\nRollouts and attempts follow a defined status lifecycle:\n\n| Status | Description |\n|--------|-------------|\n| `pending` | Initial state, not yet started |\n| `running` | Currently executing |\n| `succeeded` | Completed successfully |\n| `failed` | Execution failed |\n| `cancelled` | Manually cancelled |\n\n### Mode Types\n\n| Mode | Description |\n|------|-------------|\n| `train` | Training mode with gradient updates |\n| `eval` | Evaluation mode without updates |\n| `inference` | Production inference mode |\n\nSource: [dashboard/src/pages/Rollouts.page.tsx:30-60](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/pages/Rollouts.page.tsx)\n\n## Observability Architecture\n\n### Trace Hierarchy\n\nTraces are organized in a hierarchical structure:\n\n```\nTrace\n└── Span (root)\n ├── Span (child - preprocess)\n ├── Span (child - classifier)\n └── Span (child - formatter)\n```\n\nEach span captures:\n- Execution timing (`start_time`, `end_time`, `duration`)\n- Status and error information\n- Custom attributes (model, batch_size, accuracy)\n- Resource metadata (service name)\n\nSource: [dashboard/test-utils/python-server.py:200-300](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n\n### Attribute Keys\n\nCommon span attributes include:\n\n| Attribute | Example Value | Description |\n|-----------|---------------|-------------|\n| `type` | `classification` | Operation type |\n| `model` | `bert-classifier` | Model used |\n| `batch_size` | `10` | Processing batch size |\n| `accuracy` | `0.95` | Achieved accuracy |\n| `timeout` | `true` | Whether operation timed out |\n| `retry` | `true` | Whether this was a retry attempt |\n\nSource: [dashboard/src/components/TracesTable.component.tsx:30-50](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/TracesTable.component.tsx)\n\n## Resource Configuration Templates\n\nResources support multiple template engines:\n\n| Engine | Syntax | Example |\n|--------|--------|---------|\n| `f-string` | `{variable}` | `\"Classify: {ticket}\"` |\n| `jinja` | `{{ variable }}` or `{% for %}` | `\"{% for r in results %}{{ r }}{% endfor %}\"` |\n\nSource: [dashboard/test-utils/python-server.py:50-90](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n\n## Summary\n\nThe Agent Lightning system architecture provides:\n\n1. **Distributed Training** - Multiple workers executing rollouts in parallel\n2. **Centralized Configuration** - Versioned resource templates for prompts and models\n3. **Real-time Monitoring** - Worker heartbeat tracking and status dashboards\n4. **Full Observability** - Distributed tracing with hierarchical spans\n5. **State Persistence** - Store-based architecture for maintaining system state\n\nThe architecture is designed for horizontal scalability, allowing additional workers to be added to increase training throughput while maintaining centralized configuration management and monitoring through the dashboard frontend.\n\n---\n\n\n\n## Core Abstractions and Data Models\n\n### Related Pages\n\nRelated topics: [System Architecture](#architecture), [Trainer Component](#trainer)\n\n
\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [agentlightning/types/core.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n- [agentlightning/types/tracer.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/tracer.py)\n- [agentlightning/types/resources.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/resources.py)\n- [agentlightning/emitter/annotation.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/emitter/annotation.py)\n- [agentlightning/tracer/weave.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/tracer/weave.py)\n- [dashboard/test-utils/python-server.py](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n
\n\n# Core Abstractions and Data Models\n\nThe Agent Lightning framework relies on a set of foundational abstractions and data models that enable the coordination between runners, tracers, the LightningStore, and training algorithms. These core types are defined in `agentlightning/types/` and serve as the canonical data structures used throughout the system for representing tasks, rollouts, attempts, traces, and resources.\n\n## Architecture Overview\n\nAgent Lightning operates through a continuous execution loop where multiple components interact. The core abstractions facilitate:\n\n1. **Trace Emission** - Runners and tracers emit spans during execution\n2. **State Synchronization** - `LightningStore` maintains synchronized state\n3. **Algorithm Consumption** - Training algorithms in `agentlightning/algorithm/` consume traces to improve agent behavior\n\n```mermaid\ngraph TD\n A[Runners] -->|emit spans| B[Tracers]\n B --> C[LightningStore]\n C --> D[Algorithms]\n D -->|improve behavior| A\n C --> E[Dashboard]\n F[Resources] -->|configure| A\n```\n\nSource: [CLAUDE.md](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n\n## Task and Rollout Models\n\n### Task Representation\n\nThe `Task` and related classes define the fundamental unit of work in Agent Lightning. Tasks represent the objectives that agents attempt to accomplish during training and evaluation.\n\n| Class | Purpose |\n|-------|---------|\n| `Task` | Core task definition containing input and configuration |\n| `TaskInput` | Input data passed to a task |\n| `TaskIfAny` | Conditional task input supporting optional parameters |\n| `Dataset` | Collection of tasks for batch processing |\n\nSource: [agentlightning/types/core.py:1-50](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n\n### Rollout Lifecycle\n\nRollouts represent complete execution attempts of a task. The rollout model captures the entire lifecycle from enqueue to completion.\n\n```mermaid\nstateDiagram-v2\n [*] --> Enqueued: EnqueueRolloutRequest\n Enqueued --> InProgress: Runner picks up\n InProgress --> Attempted: First attempt completes\n Attempted --> InProgress: Retry triggered\n InProgress --> [*]: Final attempt\n Attempted --> [*]: Success/Failure\n```\n\n| Class | Description |\n|-------|-------------|\n| `Rollout` | Represents a single task execution instance |\n| `RolloutConfig` | Configuration for rollout execution |\n| `RolloutMode` | Execution mode (training, evaluation, etc.) |\n| `RolloutStatus` | Current state of the rollout |\n\nSource: [agentlightning/types/core.py:50-100](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n\n### Attempt Model\n\nAttempts represent individual tries within a rollout, enabling retry mechanisms and granular progress tracking.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `attempt_id` | `str` | Unique identifier for the attempt |\n| `rollout_id` | `str` | Parent rollout identifier |\n| `status` | `AttemptStatus` | Current attempt status |\n| `sequence_id` | `int` | Order within the rollout |\n\nSource: [agentlightning/types/core.py:100-150](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n\n### AttemptedRollout\n\nThe `AttemptedRollout` class aggregates results from all attempts within a rollout:\n\n```python\nclass AttemptedRollout(BaseModel):\n rollout: Rollout\n attempts: List[Attempt]\n # Aggregated metrics and results\n```\n\nSource: [agentlightning/types/core.py:150-180](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n\n## Tracing Abstractions\n\n### OpenTelemetry Integration\n\nAgent Lightning uses OpenTelemetry for distributed tracing. The tracer types provide serialization and interoperability with the broader observability ecosystem.\n\n| Class | Purpose |\n|-------|---------|\n| `Span` | Single unit of work in a trace |\n| `SpanCoreFields` | Core fields shared across span implementations |\n| `OtelResource` | Serializable OpenTelemetry resource representation |\n| `TraceStatus` | Span completion status with error information |\n\nSource: [agentlightning/types/tracer.py:1-80](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/tracer.py)\n\n### Span Structure\n\nSpans form the atomic tracing unit, capturing timing, status, attributes, and relationships:\n\n```mermaid\ngraph LR\n subgraph Span\n A[name] --> B[status]\n B --> C[attributes]\n C --> D[start_time/end_time]\n D --> E[parent_id/span_id]\n E --> F[resource]\n end\n```\n\n| Attribute | Description |\n|-----------|-------------|\n| `name` | Human-readable span identifier |\n| `status` | `TraceStatus` with status_code and optional description |\n| `attributes` | Key-value metadata dictionary |\n| `parent_id` | Reference to parent span (None for root) |\n| `resource` | `OtelResource` containing service metadata |\n\nSource: [agentlightning/types/tracer.py:80-120](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/tracer.py)\n\n### OtelResource Model\n\nThe `OtelResource` class provides a serializable representation of OpenTelemetry resources:\n\n```python\nclass OtelResource(BaseModel):\n attributes: Attributes\n schema_url: str\n```\n\nThis model avoids confusion with the application's `Resource` class and enables span serialization for store persistence.\n\nSource: [agentlightning/types/tracer.py:120-150](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/tracer.py)\n\n### Span Creation Patterns\n\n#### SpanCoreFields for Lightweight Creation\n\nFor span creators that don't require the full span model, `SpanCoreFields` provides a minimal interface:\n\n```python\nclass SpanCoreFields(BaseModel):\n name: str\n status: TraceStatus\n attributes: Attributes\n start_time: Optional[float]\n end_time: Optional[float]\n```\n\nSource: [agentlightning/types/tracer.py:150-180](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/tracer.py)\n\n#### Weave Tracer Span Creation\n\nThe Weave tracer implementation demonstrates proper span construction with resource attributes:\n\n```python\nresource=OtelResource(\n attributes={\n LightningResourceAttributes.ROLLOUT_ID.value: rollout_id,\n LightningResourceAttributes.ATTEMPT_ID.value: attempt_id,\n LightningResourceAttributes.SPAN_SEQUENCE_ID.value: sequence_id,\n LightningResourceAttributes.TRACER_NAME.value: \"weave\",\n },\n schema_url=\"\",\n)\n```\n\nSource: [agentlightning/tracer/weave.py:1-50](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/tracer/weave.py)\n\n## Resource Management\n\n### ResourcesUpdate Model\n\nResources define configurable components that can be versioned and updated:\n\n```python\nclass ResourcesUpdate(BaseModel):\n resources_id: str\n version: int\n create_time: float\n update_time: float\n resources: Dict[str, Any]\n```\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `resources_id` | `str` | Unique identifier for the resource set |\n| `version` | `int` | Version number for optimistic concurrency |\n| `create_time` | `float` | Unix timestamp of creation |\n| `update_time` | `float` | Unix timestamp of last update |\n| `resources` | `Dict[str, Any]` | Arbitrary resource configuration |\n\nSource: [dashboard/test-utils/python-server.py:1-80](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n\n### Resource Types\n\nResources support flexible configuration through templates and model definitions:\n\n| Resource Type | Description |\n|---------------|-------------|\n| `PromptTemplate` | Templated prompts with jinja2 or f-string engines |\n| `LLM` | Language model configuration with endpoint and sampling parameters |\n| Custom `Dict[str, Any]` | Arbitrary configuration dictionaries |\n\nSource: [dashboard/test-utils/python-server.py:80-150](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n\n## Worker Abstraction\n\nWorkers represent execution agents that process rollouts:\n\n```mermaid\nclassDiagram\n class Worker {\n +worker_id: str\n +status: WorkerStatus\n +heartbeat_stats: Dict\n +last_heartbeat_time: float\n +current_rollout_id: Optional[str]\n +current_attempt_id: Optional[str]\n }\n```\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `worker_id` | `str` | Unique worker identifier |\n| `status` | `WorkerStatus` | Current status (busy, idle, etc.) |\n| `heartbeat_stats` | `Dict` | Runtime metrics (queue_depth, gpu_utilization) |\n| `last_heartbeat_time` | `float` | Last check-in timestamp |\n| `current_rollout_id` | `Optional[str]` | Currently executing rollout |\n\nSource: [agentlightning/types/core.py:180-220](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n\n### Worker Status States\n\n```mermaid\nstateDiagram-v2\n [*] --> Idle: Startup\n Idle --> Busy: Dequeue rollout\n Busy --> Idle: Complete\n Busy --> Busy: Heartbeat\n Idle --> [*]: Shutdown\n Busy --> [*]: Shutdown\n```\n\nSource: [dashboard/test-utils/python-server.py:150-200](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n\n## Filtering and Pagination\n\n### Query Models\n\nThe store supports filtered and paginated queries for efficient data access:\n\n| Class | Purpose |\n|-------|---------|\n| `FilterOptions` | Criteria for filtering results |\n| `FilterField` | Individual filter condition |\n| `SortOptions` | Sorting configuration |\n| `PaginatedResult` | Paginated response wrapper |\n\nSource: [agentlightning/types/core.py:220-260](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n\n## Operation Context\n\nThe `@operation` decorator provides a simplified span creation interface for user code:\n\n```python\n@operation(name=\"my_operation\")\nasync def my_function():\n # Automatically creates and manages a span\n pass\n```\n\n### OperationContext Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `propagate` | `bool` | Whether spans should use active span processor |\n| `name` | `Optional[str]` | Alias populating `OPERATION_NAME` attribute |\n\nThe decorator supports two usage patterns:\n1. As a bare decorator: `@operation`\n2. As a context manager factory: `with operation(name=\"custom\"):`\n\nSource: [agentlightning/emitter/annotation.py:1-60](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/emitter/annotation.py)\n\n## Data Flow Summary\n\n```mermaid\ngraph TD\n subgraph Input\n A[Dataset] --> B[Task]\n B --> C[EnqueueRolloutRequest]\n end\n \n subgraph Execution\n C --> D[Runner]\n D --> E[Worker]\n E --> F[Attempt]\n F --> G[Span]\n end\n \n subgraph Storage\n G --> H[LightningStore]\n H --> I[PaginatedResult]\n end\n \n subgraph Training\n H --> J[Algorithm]\n J --> K[Improved Policy]\n end\n```\n\n## Key Type Exports\n\nThe `agentlightning/types/core.py` module exports the following public API:\n\n```python\n__all__ = [\n \"Triplet\",\n \"RolloutLegacy\",\n \"Task\",\n \"TaskInput\",\n \"TaskIfAny\",\n \"RolloutRawResultLegacy\",\n \"RolloutRawResult\",\n \"RolloutMode\",\n \"GenericResponse\",\n \"ParallelWorkerBase\",\n \"Dataset\",\n \"AttemptStatus\",\n \"RolloutStatus\",\n \"RolloutConfig\",\n \"Rollout\",\n \"Attempt\",\n \"AttemptedRollout\",\n \"EnqueueRolloutRequest\",\n \"Hook\",\n \"Worker\",\n \"WorkerStatus\",\n \"PaginatedResult\",\n \"FilterOptions\",\n \"SortOptions\",\n \"FilterField\",\n]\n```\n\nSource: [agentlightning/types/core.py:40-60](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n\n## Usage Patterns\n\n### Creating a Rollout Request\n\n```python\nrequest = EnqueueRolloutRequest(\n task_id=\"task-001\",\n config=RolloutConfig(mode=RolloutMode.TRAINING),\n priority=1\n)\n```\n\n### Querying with Filters\n\n```python\nfilters = FilterOptions(\n fields=[FilterField(name=\"status\", operator=\"eq\", value=\"completed\")],\n sort=SortOptions(field=\"create_time\", direction=\"desc\"),\n offset=0,\n limit=50\n)\n```\n\nSource: [agentlightning/types/core.py:260-300](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n\n---\n\n\n\n## Tutorial: Train Your First Agent\n\n### Related Pages\n\nRelated topics: [Tutorial: Writing Agents](#write-agents), [Algorithm Zoo](#algorithm-zoo)\n\n
\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [examples/apo/README.md](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/README.md)\n- [examples/apo/apo_debug.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_debug.py)\n- [examples/apo/room_selector.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/room_selector.py)\n- [CLAUDE.md](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n- [agentlightning/types/tracer.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/tracer.py)\n- [examples/minimal/README.md](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/README.md)\n\n**Note:** The file `docs/how-to/train-first-agent.md` referenced in the specification was not present in the retrieved context. The tutorial content below is synthesized from available APO example documentation and source code.\n\n
\n\n# Tutorial: Train Your First Agent\n\n## Overview\n\nThis tutorial guides you through training your first AI agent using Agent Lightning's reinforcement learning framework. You will learn how to set up a training pipeline, define prompts and resources, create a dataset, and run the APO (Agent Prompt Optimization) algorithm to improve your agent's behavior through feedback-driven learning.\n\nAgent Lightning provides a complete training loop where runners and tracers emit spans, `LightningStore` keeps them synchronized, and algorithms consume those traces to improve behavior. Source: [CLAUDE.md](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n\n## Prerequisites\n\nBefore starting this tutorial, ensure you have:\n\n- Python 3.10+ installed\n- Agent Lightning installed following the [installation guide](../../docs/tutorials/installation.md)\n- An OpenAI-compatible API service available\n- APO extra dependencies installed\n\n## Architecture Overview\n\nAgent Lightning trains agents through a continuous feedback loop:\n\n```mermaid\ngraph TD\n A[Runner - Executes Agent] --> B[Tracer - Emits Spans]\n B --> C[LightningStore - Synchronizes Data]\n C --> D[Algorithm - Consumes Traces]\n D --> E[Improved Agent Behavior]\n E --> A\n \n F[Dataset - Training Data] --> D\n G[Resources - Prompts/Models] --> A\n```\n\nSource: [CLAUDE.md](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n\n## Step 1: Create Your Agent\n\nBegin by defining a simple room booking agent that uses function calling. The agent receives a user request and selects an appropriate room from available options.\n\n```python\n# examples/apo/room_selector.py\n\nfrom agentlightning import Runner, DataProto\nfrom typing import Any\nimport json\n\nclass RoomSelector(Runner):\n \"\"\"Room booking agent using function calling.\"\"\"\n\n def run(self, task: str, context: dict | None = None) -> DataProto:\n # Define available rooms\n rooms = [\n {\"id\": \"R001\", \"name\": \"Conference A\", \"capacity\": 10},\n {\"id\": \"R002\", \"name\": \"Meeting Room B\", \"capacity\": 4},\n {\"id\": \"R003\", \"name\": \"Board Room\", \"capacity\": 20},\n ]\n \n # Mock LLM response selecting a room\n selected_room = rooms[1] # Default to Meeting Room B\n \n return DataProto(\n data={\n \"selected_room\": selected_room[\"name\"],\n \"room_id\": selected_room[\"id\"],\n },\n raw_response=json.dumps(selected_room),\n )\n```\n\nSource: [examples/apo/room_selector.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/room_selector.py)\n\n### Supported Agent Components\n\n| Component | Description | Usage |\n|-----------|-------------|-------|\n| `Runner` | Base class for agent execution | Extend to define custom agent logic |\n| `Trainer` | Training orchestration | Manages training loop and workers |\n| `LightningStore` | Data synchronization | Stores traces and spans |\n| `OtelTracer` | OpenTelemetry span emission | Records execution traces |\n\nSource: [examples/apo/apo_debug.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_debug.py)\n\n## Step 2: Prepare Your Dataset\n\nCreate a training dataset with room booking scenarios. Each task should include the user request and expected room selection.\n\n```python\n# examples/apo/room_selector_apo.py\n\nfrom datasets import load_dataset\n\ndef create_room_dataset():\n \"\"\"Create dataset for room booking tasks.\"\"\"\n \n # Example tasks for room booking\n tasks = [\n {\n \"task\": \"I need to schedule a meeting for 3 people tomorrow at 2 PM\",\n \"expected_room\": \"Meeting Room B\",\n },\n {\n \"task\": \"We are hosting a team event for 15 team members\",\n \"expected_room\": \"Board Room\",\n },\n {\n \"task\": \"Quick 1-on-1 sync needed this afternoon\",\n \"expected_room\": \"Meeting Room B\",\n },\n ]\n \n return tasks\n```\n\nSource: [examples/apo/room_selector_apo.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/room_selector_apo.py)\n\n## Step 3: Define Training Resources\n\nResources define the prompts and model configurations used by your agent during training. You can tune any resource—typically prompt templates—using reinforcement learning.\n\n```python\nfrom agentlightning.prompts import PromptTemplate\nfrom agentlightning.models import LLM\n\n# Define a tunable prompt template\nmain_prompt = PromptTemplate(\n template=\"\"\"You are a helpful assistant that helps users book meeting rooms.\n \n Available rooms:\n - Conference A: capacity 10\n - Meeting Room B: capacity 4\n - Board Room: capacity 20\n \n User request: {user_request}\n \n Select the most appropriate room and explain your choice.\"\"\",\n engine=\"f-string\",\n)\n```\n\nSource: [examples/apo/apo_debug.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_debug.py)\n\n### Resource Types\n\n| Type | Description | Tunable |\n|------|-------------|---------|\n| `PromptTemplate` | Text templates with variable substitution | Yes |\n| `LLM` | Model configuration (endpoint, sampling params) | No |\n| `SystemPrompt` | System-level instructions | Yes |\n| `SamplingParameters` | Temperature, top_p, max_tokens | No |\n\nSource: [examples/apo/README.md](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/README.md)\n\n## Step 4: Configure the Trainer\n\nThe `Trainer` class orchestrates the training loop. It manages workers, coordinates with the LightningStore, and applies the optimization algorithm.\n\n```python\nfrom agentlightning import Trainer\n\n# Initialize trainer with one worker\ntrainer = Trainer(\n n_workers=1,\n # Resources to tune - only these will be optimized\n initial_resources={\n \"main_prompt\": main_prompt,\n },\n)\n\n# Configure the APO algorithm\ntrainer.configure(\n algorithm=\"APO\",\n lr=1e-3,\n epochs=10,\n)\n```\n\nSource: [examples/apo/apo_debug.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_debug.py)\n\n### Trainer Configuration Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `n_workers` | int | 1 | Number of parallel training workers |\n| `initial_resources` | dict | Required | Resources to optimize |\n| `algorithm` | str | Required | Optimization algorithm name |\n| `lr` | float | 1e-3 | Learning rate |\n| `epochs` | int | 10 | Number of training epochs |\n\nSource: [examples/apo/apo_debug.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_debug.py)\n\n## Step 5: Implement Reward Function\n\nThe reward function evaluates agent outputs and provides feedback signals for reinforcement learning.\n\n```python\nfrom typing import Any\n\ndef room_booking_reward(output: Any, expected: dict) -> float:\n \"\"\"\n Calculate reward based on room selection accuracy.\n \n Args:\n output: Agent's room selection\n expected: Expected room from dataset\n \n Returns:\n float: Reward score between 0.0 and 1.0\n \"\"\"\n if not output or not output.data:\n return 0.0\n \n selected_room = output.data.get(\"selected_room\", \"\")\n expected_room = expected.get(\"expected_room\", \"\")\n \n # Exact match gets full reward\n if selected_room == expected_room:\n return 1.0\n \n # Partial match gets partial reward\n if expected_room.lower() in selected_room.lower():\n return 0.5\n \n return 0.0\n```\n\nSource: [examples/apo/room_selector_apo.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/room_selector_apo.py)\n\n## Step 6: Run the Training Loop\n\nExecute the training with your runner, dataset, and reward function.\n\n```python\nimport asyncio\nfrom agentlightning import setup_logging\n\nasync def train_room_selector():\n setup_logging()\n \n # Initialize agent and trainer\n agent = RoomSelector()\n dataset = create_room_dataset()\n \n trainer = Trainer(\n n_workers=1,\n initial_resources={\"main_prompt\": main_prompt},\n )\n \n # Run training\n results = await trainer.train(\n runner=agent,\n dataset=dataset,\n reward_fn=room_booking_reward,\n max_iterations=100,\n )\n \n print(f\"Training completed: {results}\")\n\nif __name__ == \"__main__\":\n asyncio.run(train_room_selector())\n```\n\nSource: [examples/apo/apo_debug.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_debug.py)\n\n## Understanding the Training Flow\n\n```mermaid\nsequenceDiagram\n participant User as User Code\n participant Trainer as Trainer\n participant Runner as RoomSelector\n participant Store as LightningStore\n participant Algo as APO Algorithm\n \n User->>Trainer: train(runner, dataset, reward_fn)\n Trainer->>Runner: execute_task(task)\n Runner->>Runner: select_room()\n Runner-->>Trainer: output\n Trainer->>Store: record_span(rollout_id, attempt_id)\n Trainer->>Trainer: calculate_reward(output, expected)\n Trainer->>Algo: optimize_step(rewards, traces)\n Algo-->>Trainer: updated_resources\n Trainer->>Runner: update_resources()\n Note over Trainer,Algo: Repeat for max_iterations\n```\n\n## Debugging Your Training\n\nAgent Lightning provides multiple debugging approaches:\n\n### Approach 1: Runner Mode\n\nDirect execution without training to verify agent logic:\n\n```bash\npython apo_debug.py --mode runner\n```\n\nSource: [examples/apo/apo_debug.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_debug.py)\n\n### Approach 2: Hook Mode\n\nDebug with tracing hooks enabled:\n\n```bash\npython apo_debug.py --mode hook\n```\n\n### Approach 3: Trainer Mode\n\nFull training debug with detailed logging:\n\n```bash\npython apo_debug.py --mode trainer\n```\n\n## Viewing Training Traces\n\nDuring and after training, spans are recorded to the LightningStore. View them in the dashboard:\n\n```mermaid\ngraph LR\n A[Training Run] --> B[Spans Emitted]\n B --> C[LightningStore]\n C --> D[Dashboard]\n D --> E[Trace Visualization]\n D --> F[Span Details]\n```\n\nThe dashboard displays:\n\n| View | Description |\n|------|-------------|\n| Rollouts | Complete training iterations |\n| Spans | Individual function calls and operations |\n| Resources | Tunable prompt templates |\n| Metrics | Reward scores and training statistics |\n\nSource: [examples/minimal/README.md](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/README.md)\n\n## Common Issues and Solutions\n\n### Issue: Tracer Conflicts\n\nRunning multiple modes consecutively in one process may cause tracer conflicts.\n\n**Solution:** Run each mode in a separate process or ensure proper tracer cleanup between runs.\n\nSource: [examples/apo/apo_debug.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_debug.py)\n\n### Issue: Missing Dependencies\n\nAPO requires additional dependencies not in the core installation.\n\n**Solution:** Install with extras:\n```bash\npip install agentlightning[apo]\n```\n\nSource: [examples/apo/README.md](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/README.md)\n\n## Next Steps\n\nAfter completing this tutorial:\n\n1. **Advanced Algorithms**: Explore custom algorithms in `apo_custom_algorithm.py`\n2. **Integration**: Learn Agent-OS integration for policy-aware training\n3. **Dashboard**: Use the dashboard to visualize training progress\n4. **Production**: Scale training with multiple workers and distributed execution\n\n## Summary\n\nThis tutorial covered the essential steps to train your first agent with Agent Lightning:\n\n- Define a `Runner` implementing your agent logic\n- Prepare a dataset with tasks and expected outputs\n- Configure `PromptTemplate` resources for tuning\n- Implement a reward function for RL feedback\n- Use `Trainer` to orchestrate the training loop\n- Debug with multiple modes and visualize traces in the dashboard\n\nThe training loop continuously improves your agent by optimizing prompt resources based on reward signals, enabling agents to learn from feedback without manual prompt engineering.\n\n---\n\n\n\n## Tutorial: Writing Agents\n\n### Related Pages\n\nRelated topics: [Tutorial: Train Your First Agent](#train-first-agent), [Runner Component](#runner)\n\n
\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [CLAUDE.md](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n- [AGENTS.md](https://github.com/microsoft/agent-lightning/blob/main/AGENTS.md)\n- [examples/minimal/README.md](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/README.md)\n- [examples/minimal/write_traces.py](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/write_traces.py)\n- [dashboard/test-utils/python-server.py](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n- [dashboard/src/components/AppDrawer.component.tsx](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/AppDrawer.component.tsx)\n- [agentlightning/store/](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/) (store module referenced via CLAUDE.md)\n
\n\n# Tutorial: Writing Agents\n\nThis tutorial provides a comprehensive guide to building AI agents using the Agent Lightning framework. It covers the core concepts, architecture, and practical implementation patterns for creating agents that can be trained with reinforcement learning.\n\n## Overview\n\nAgent Lightning is a framework designed to train AI agents using reinforcement learning. The framework provides a complete execution stack including tracing, storage, and algorithm components that work together in a continuous loop. Source: [CLAUDE.md:1-5](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n\nAgents in this framework are built using the `LightningStore` architecture, which synchronizes data between runners, tracers, and algorithms. The tracers emit spans that capture the agent's execution behavior, and these spans are consumed by algorithms to improve the agent's performance over time. Source: [AGENTS.md:1-5](https://github.com/microsoft/agent-lightning/blob/main/AGENTS.md)\n\n## Architecture Overview\n\nThe Agent Lightning framework follows a continuous loop architecture where multiple components interact to enable training of AI agents.\n\n```mermaid\ngraph TD\n A[Agent / Runner] -->|Emits Spans| B[Tracer]\n B -->|Traces| C[LightningStore]\n C -->|Synchronized Data| D[Algorithms]\n D -->|Training Signals| A\n E[Dashboard] -->|Inspect & Debug| C\n```\n\n### Core Components\n\n| Component | Purpose | Location |\n|-----------|---------|----------|\n| `LightningStore` | Central data store for traces and rollouts | `agentlightning/store/` |\n| `OtelTracer` | OpenTelemetry-based span emission | Via `OtelTracer` class |\n| `AgentOpsTracer` | AgentOps integration for tracing | Via `AgentOpsTracer` class |\n| `Span` | Individual trace unit | Data model |\n| `emit_reward` | Reward signal emission | API function |\n\nSource: [examples/minimal/write_traces.py:1-40](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/write_traces.py)\n\n## Writing Your First Agent\n\n### Basic Agent Structure\n\nAn agent in Agent Lightning is built around the tracing and store infrastructure. The minimal component showcase in `examples/minimal/` demonstrates how individual building blocks behave in isolation. Source: [examples/minimal/README.md:1-10](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/README.md)\n\n### Setting Up the Tracer\n\nThe framework supports two primary tracing mechanisms:\n\n1. **OtelTracer**: OpenTelemetry-based tracing that can forward spans to a remote store client\n2. **AgentOpsTracer**: AgentOps integration for agent operations tracking\n\n```python\nfrom agentlightning import OtelTracer, LightningStoreClient, setup_logging\n\n# Initialize logging\nsetup_logging()\n\n# Create tracer with optional remote store client\ntracer = OtelTracer(\n rollout_id=\"ro-001\",\n attempt_id=\"at-001\",\n store_client=None # Or LightningStoreClient(endpoint=\"...\")\n)\n```\n\nSource: [examples/minimal/write_traces.py:40-60](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/write_traces.py)\n\n### Opening Rollouts and Emitting Spans\n\nRollouts represent a single execution attempt of an agent, and attempts within rollouts allow for retry logic and tracking.\n\n```python\n# Open a new rollout\ntracer.open_rollout(rollout_id=\"ro-001\", user_id=\"user-123\")\n\n# Open an attempt within the rollout\ntracer.open_attempt(attempt_id=\"at-001\", sequence_id=1)\n\n# Emit spans during agent execution\ntracer.emit_span(\n name=\"tool_execution\",\n attributes={\n \"tool\": \"web_search\",\n \"query\": \"onboarding summary\"\n }\n)\n\n# Close attempt and rollout\ntracer.close_attempt()\ntracer.close_rollout()\n```\n\nSource: [examples/minimal/write_traces.py:60-85](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/write_traces.py)\n\n## Span Data Model\n\nSpans are the fundamental unit of tracing in Agent Lightning. Each span captures a discrete unit of work within an agent's execution.\n\n### Span Attributes\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `rollout_id` | string | Unique identifier for the rollout |\n| `attempt_id` | string | Unique identifier for the attempt |\n| `sequence_id` | integer | Order of the span within the attempt |\n| `trace_id` | string | Trace grouping identifier |\n| `span_id` | string | Unique span identifier |\n| `parent_id` | string | Parent span ID for hierarchy |\n| `name` | string | Human-readable span name |\n| `status` | TraceStatus | Execution status (OK, ERROR) |\n| `attributes` | dict | Key-value metadata |\n| `start_time` | datetime | Span start timestamp |\n| `end_time` | datetime | Span end timestamp |\n\nSource: [dashboard/test-utils/python-server.py:1-100](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n\n### Example Span Creation\n\n```python\nfrom agentlightning import Span, TraceStatus\nfrom datetime import datetime\n\nspan = Span(\n rollout_id=\"ro-story-001\",\n attempt_id=\"at-story-010\",\n sequence_id=3,\n trace_id=\"trace-001-main\",\n span_id=\"span-003-tool\",\n parent_id=\"span-001-root\",\n name=\"tool_execution\",\n status=TraceStatus(status_code=\"OK\", description=None),\n attributes={\"tool\": \"web_search\", \"query\": \"onboarding summary\"},\n events=[],\n links=[],\n start_time=datetime.now(),\n end_time=datetime.now(),\n context=None,\n parent=None,\n resource=OtelResource(attributes={\"service.name\": \"tool-service\"}, schema_url=\"\")\n)\n```\n\nSource: [dashboard/test-utils/python-server.py:100-130](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n\n## Using Operations\n\nThe framework provides an `operation` decorator for recording synthetic operation spans with additional linking capabilities.\n\n```python\nfrom agentlightning.operation import operation\nfrom agentlightning.utils.otel import make_link_attributes, make_tag_attributes\n\n# Record an operation span\n@operation(name=\"classify_ticket\")\ndef classify_ticket(ticket: str):\n with make_link_attributes(linked_rollout_id=\"ro-001\", linked_attempt_id=\"at-001\"):\n # Operation execution\n result = llm.classify(ticket)\n \n # Tag the reward\n make_tag_attributes(tags={\"accuracy\": 0.95})\n emit_reward(reward=0.95, name=\"classification_accuracy\")\n \n return result\n```\n\nSource: [examples/minimal/write_traces.py:20-35](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/write_traces.py)\n\n## LightningStore Integration\n\nThe `LightningStore` keeps tracers and runners synchronized, serving as the central data repository.\n\n```python\nfrom agentlightning.store import InMemoryLightningStore\n\n# Use in-memory store for local development\nstore = InMemoryLightningStore()\n\n# Or connect to a remote store server\nstore = LightningStoreClient(endpoint=\"http://localhost:45993\")\n```\n\nSource: [examples/minimal/write_traces.py:25-35](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/write_traces.py)\n\n### Store Server CLI\n\nStart a LightningStore server with OTLP enabled:\n\n```bash\nagl store --port 45993 --log-level DEBUG\n```\n\nSource: [examples/minimal/write_traces.py:15-20](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/write_traces.py)\n\n## Workflow Execution Model\n\nAgents in Agent Lightning follow a structured execution model with rollouts, attempts, and spans.\n\n```mermaid\ngraph LR\n subgraph Rollout[Rollout: ro-001]\n subgraph Attempt1[Attempt: at-001]\n S1[Span: root]\n S2[Span: preprocess]\n S3[Span: classify]\n S1 --> S2\n S2 --> S3\n end\n subgraph Attempt2[Attempt: at-002]\n S4[Span: root]\n S5[Span: preprocess]\n S6[Span: classify]\n S4 --> S5\n S5 --> S6\n end\n end\n```\n\n### State Transitions\n\n| State | Description |\n|-------|-------------|\n| `pending` | Rollout/attempt created but not started |\n| `running` | Currently executing |\n| `completed` | Successfully finished |\n| `failed` | Execution failed |\n| `cancelled` | Manually cancelled |\n\nSource: [dashboard/src/components/RolloutTable.component.tsx:1-50](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/RolloutTable.component.tsx)\n\n## Reward Emission\n\nAgents emit reward signals that algorithms consume during training.\n\n```python\nfrom agentlightning import emit_reward\n\n# Emit a reward with metadata\nemit_reward(\n reward=0.85,\n name=\"task_success\",\n attributes={\n \"task_id\": \"classification\",\n \"accuracy\": 0.85,\n \"latency_ms\": 150\n }\n)\n```\n\n### Reward Span Attributes\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `reward.value` | float | Numeric reward value |\n| `reward.name` | string | Reward signal identifier |\n| `reward.attributes` | dict | Additional metadata |\n\n## Dashboard Integration\n\nThe Agent Lightning Dashboard provides real-time inspection of store data and debugging capabilities for running experiments. Source: [dashboard/README.md:1-10](https://github.com/microsoft/agent-lightning/blob/main/dashboard/README.md)\n\n### Drawer Components\n\nThe dashboard uses drawer components to display detailed information:\n\n```typescript\n// Worker detail drawer\nif (content.type === 'worker-detail') {\n const { worker } = content;\n const title = ;\n const body = ;\n return { title, body };\n}\n\n// Trace detail drawer\nif (content.type === 'trace-detail') {\n const { span } = content;\n const title = ;\n const body = ;\n return { title, body };\n}\n```\n\nSource: [dashboard/src/components/AppDrawer.component.tsx:1-50](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/AppDrawer.component.tsx)\n\n## Minimal Examples Reference\n\nThe `examples/minimal/` directory provides documented examples for each building block:\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| LightningStore + OTLP | `write_traces.py` | Shows `OtelTracer` and `AgentOpsTracer` for rollouts and spans |\n| MultiMetrics | `write_metrics.py` | Console and Prometheus metrics backends |\n| LLM Proxying | `llm_proxy.py` | Request routing through `/rollout//attempt/` namespaces |\n| vLLM Lifecycle | `vllm_server.py` | Context manager for vLLM server lifecycle |\n\nSource: [examples/minimal/README.md:10-30](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/README.md)\n\n## Best Practices\n\n1. **Use descriptive span names**: Names like `tool_execution` and `classification_pipeline` make debugging easier in the dashboard.\n2. **Set appropriate parent IDs**: Maintain span hierarchy for better trace visualization.\n3. **Emit rewards consistently**: Use `emit_reward` after each task completion to enable algorithm training.\n4. **Handle failures explicitly**: Set appropriate `TraceStatus` codes and descriptions for failed spans.\n5. **Use operations for complex workflows**: The `@operation` decorator simplifies recording complex multi-step processes.\n\n## Next Steps\n\n- Explore the [API Reference](./api-reference.md) for detailed method signatures\n- Learn about [Training Algorithms](../how-to/training-algorithms.md) that consume traces\n- Set up the [Dashboard](../how-to/dashboard-setup.md) for real-time monitoring\n- Review [Examples](../examples/overview.md) for complete agent implementations\n\n---\n\n\n\n## Trainer Component\n\n### Related Pages\n\nRelated topics: [Runner Component](#runner), [LightningStore](#store), [Algorithm Zoo](#algorithm-zoo)\n\n
\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [agentlightning/trainer/trainer.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/trainer/trainer.py)\n- [agentlightning/trainer/registry.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/trainer/registry.py)\n- [agentlightning/trainer/init_utils.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/trainer/init_utils.py)\n- [examples/apo/apo_custom_algorithm_trainer.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_custom_algorithm_trainer.py)\n- [contrib/recipes/agentos/README.md](https://github.com/microsoft/agent-lightning/blob/main/contrib/recipes/agentos/README.md)\n- [examples/calc_x/legacy_calc_agent.py](https://github.com/microsoft/agent-lightning/blob/main/examples/calc_x/legacy_calc_agent.py)\n
\n\n# Trainer Component\n\nThe Trainer is the core orchestration component in Agent Lightning responsible for managing the reinforcement learning training loop. It coordinates runners, algorithms, and the LightningStore to execute agent training with scalable execution strategies.\n\n## Overview\n\nThe Trainer serves as the central control plane that:\n\n- Manages worker processes for parallel rollout execution\n- Coordinates between the agent runner and learning algorithm\n- Persists training traces to the LightningStore\n- Provides pluggable execution strategies for different deployment scenarios\n\nSource: [agentlightning/trainer/registry.py:1-6](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/trainer/registry.py)\n\n## Architecture\n\n### Component Interactions\n\n```mermaid\ngraph TD\n T[Trainer] --> R[Runner
Agent Execution]\n T --> A[Algorithm
Policy Update]\n T --> S[LightningStore
Trace Storage]\n T --> E[ExecutionStrategy]\n \n E --> SHM[SharedMemory
Local Workers]\n E --> CS[ClientServer
Remote Workers]\n \n R --> S\n A --> S\n```\n\n### Training Loop Flow\n\n```mermaid\nsequenceDiagram\n participant T as Trainer\n participant R as Runner\n participant S as LightningStore\n participant A as Algorithm\n \n T->>R: Initialize with config\n T->>A: Load algorithm\n T->>S: Connect store\n \n loop Training Steps\n T->>R: Execute rollouts\n R->>S: Emit spans\n T->>S: Retrieve traces\n T->>A: Process traces\n A->>T: Policy update\n end\n```\n\n## Core Configuration\n\n### Constructor Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `n_workers` | `int` | `1` | Number of parallel worker processes |\n| `algorithm` | `Algorithm \\| str` | `None` | Learning algorithm (name or instance) |\n| `runner` | `Runner \\| None` | `None` | Agent runner for execution |\n| `reward_fn` | `RewardFn \\| None` | `None` | Reward function for training |\n| `execution_strategy` | `str` | `\"shm\"` | Strategy: `\"shm\"`, `\"cs\"` |\n\nSource: [examples/apo/apo_custom_algorithm_trainer.py:35-37](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_custom_algorithm_trainer.py)\n\n### Execution Strategy Registry\n\nThe Trainer supports multiple execution strategies through a registry pattern:\n\n```python\nExecutionStrategyRegistry = {\n \"shm\": \"agentlightning.execution.shared_memory.SharedMemoryExecutionStrategy\",\n \"cs\": \"agentlightning.execution.client_server.ClientServerExecutionStrategy\",\n}\n```\n\nSource: [agentlightning/trainer/registry.py:1-6](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/trainer/registry.py)\n\n| Strategy | Description | Use Case |\n|----------|-------------|----------|\n| `shm` | Shared Memory - Local multi-process execution | Single-node GPU training |\n| `cs` | Client-Server - Remote worker communication | Distributed deployments |\n\n## Usage Patterns\n\n### Basic Training with GRPO Algorithm\n\n```python\nfrom agentlightning import Trainer\n\ntrainer = Trainer(\n runner=runner,\n reward_fn=reward_fn,\n algorithm=\"GRPO\"\n)\n\ntrainer.train()\n```\n\nSource: [contrib/recipes/agentos/README.md:40-47](https://github.com/microsoft/agent-lightning/blob/main/contrib/recipes/agentos/README.md)\n\n### Custom Algorithm Integration\n\nThe Trainer accepts custom algorithms decorated with the `@algo` decorator:\n\n```python\nfrom agentlightning import Trainer\nfrom agentlightning.algorithm import algo\nfrom agentlightning.store import LightningStore\n\n@algo\nasync def custom_algorithm(*, store: LightningStore):\n # Process traces from store\n return policy_update\n\ntrainer = Trainer(n_workers=1, algorithm=custom_algorithm)\ntrainer.fit(rollout_fn)\n```\n\nSource: [examples/apo/apo_custom_algorithm_trainer.py:28-37](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_custom_algorithm_trainer.py)\n\n### Parallel Training with Multiple Workers\n\n```python\nfrom agentlightning import Trainer\n\ntrainer = Trainer(\n n_workers=4, # 4 parallel workers\n execution_strategy=\"shm\", # Shared memory for local execution\n algorithm=\"PPO\",\n runner=runner\n)\n\ntrainer.train()\n```\n\n## Integration with Agent-OS\n\nThe Trainer integrates with Agent-OS for policy-governed training:\n\n```python\nfrom agentlightning import Trainer\nfrom agentlightning.contrib.runner.agentos import AgentOSRunner\nfrom agentlightning.contrib.reward.agentos import PolicyReward\nfrom agent_os import KernelSpace\nfrom agent_os.policies import SQLPolicy\n\n# Create governed kernel\nkernel = KernelSpace(policy=SQLPolicy(deny=[\"DROP\", \"DELETE\"]))\n\n# Wrap in Agent-OS runner\nrunner = AgentOSRunner(kernel)\n\n# Train with policy-aware rewards\ntrainer = Trainer(\n runner=runner,\n reward_fn=PolicyReward(kernel),\n algorithm=\"GRPO\"\n)\n\ntrainer.train()\n```\n\nSource: [contrib/recipes/agentos/README.md:25-45](https://github.com/microsoft/agent-lightning/blob/main/contrib/recipes/agentos/README.md)\n\n## Workflow Phases\n\n| Phase | Description |\n|-------|-------------|\n| **Initialization** | Load algorithm, connect store, spawn workers |\n| **Rollout** | Execute agent episodes in parallel workers |\n| **Trace Collection** | Retrieve spans from LightningStore |\n| **Algorithm Update** | Process traces and update policy |\n| **Iteration** | Repeat rollout-collect-update cycle |\n\n## LightningStore Integration\n\nThe Trainer maintains bidirectional synchronization with LightningStore:\n\n- **Span Emission**: Workers emit execution traces during rollout\n- **Trace Retrieval**: Algorithm reads completed traces for learning\n- **Persistence**: Training state survives worker restarts\n\nSource: [CLAUDE.md:4-6](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n\n## Command-Line Interface\n\nThe Trainer can be invoked via the `agl` CLI:\n\n```bash\n# Start training\nagl store\npython my_training_script.py algo\npython my_training_script.py runner\n```\n\nOr programmatically:\n\n```bash\npython my_training_script.py\n```\n\nSource: [examples/apo/apo_custom_algorithm_trainer.py:12-20](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_custom_algorithm_trainer.py)\n\n## Extending the Trainer\n\n### Custom Execution Strategy\n\nAdd new strategies to the registry:\n\n```python\n# In agentlightning/trainer/registry.py\nExecutionStrategyRegistry[\"custom\"] = \"mymodule.CustomExecutionStrategy\"\n```\n\n### Custom Algorithm\n\nDecorate async functions with `@algo`:\n\n```python\nfrom agentlightning.algorithm import algo\n\n@algo\nasync def my_algorithm(*, store: LightningStore):\n traces = await store.traces.get_all()\n # Process traces\n return update\n```\n\n## Dependencies\n\n| Dependency | Purpose |\n|------------|---------|\n| `LightningStore` | Trace persistence and retrieval |\n| `Algorithm` | Policy learning logic |\n| `Runner` | Agent execution environment |\n| `ExecutionStrategy` | Worker orchestration |\n| `RewardFn` | Training signal computation |\n\n## See Also\n\n- [Agent Lightning Architecture](AGENTS.md) - System-wide architecture overview\n- [Algorithm Component](algorithm.md) - Learning algorithm details\n- [LightningStore](store.md) - Trace storage system\n- [Execution Strategies](execution.md) - Available execution modes\n\n---\n\n\n\n## Runner Component\n\n### Related Pages\n\nRelated topics: [Trainer Component](#trainer), [Tutorial: Writing Agents](#write-agents)\n\n
\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [agentlightning/runner/base.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/base.py)\n- [agentlightning/runner/agent.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/agent.py)\n- [agentlightning/runner/legacy.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/legacy.py)\n- [agentlightning/runner/__init__.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/__init__.py)\n- [agentlightning/types/core.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n- [agentlightning/trainer/trainer.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/trainer/trainer.py)\n
\n\n# Runner Component\n\nThe Runner component is the core execution engine in Agent Lightning responsible for managing agent lifecycle, task processing, and telemetry collection. Runners serve as the bridge between the high-level `Trainer` orchestration and the underlying `LitAgent` implementation, handling initialization, worker management, and graceful shutdown.\n\n## Overview\n\nRunners execute agents in a continuous loop where they poll the `LightningStore` for tasks, execute agent logic, and emit tracing spans for algorithm consumption. The Runner architecture supports both standard execution through `LitAgentRunner` and legacy compatibility through `LegacyAgentRunner`.\n\nSource: [agentlightning/runner/__init__.py:1-11](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/__init__.py)\n\n```python\nfrom .agent import LitAgentRunner\nfrom .base import Runner\nfrom .legacy import LegacyAgentRunner\n\n__all__ = [\n \"Runner\",\n \"LegacyAgentRunner\",\n \"LitAgentRunner\",\n]\n```\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Trainer] --> B[Runner Fleet]\n B --> C[LitAgentRunner]\n B --> D[LegacyAgentRunner]\n C --> E[LitAgent]\n D --> F[AgentLightningClient]\n E --> G[LightningStore]\n F --> G\n E --> H[Tracer]\n H --> G\n```\n\n### Runner Hierarchy\n\n| Class | Purpose | Source |\n|-------|---------|--------|\n| `Runner` | Abstract base class defining the runner interface | [base.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/base.py) |\n| `LitAgentRunner` | Primary runner implementation for standard agent execution | [agent.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/agent.py) |\n| `LegacyAgentRunner` | Runner for backward compatibility with AgentOps integration | [legacy.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/legacy.py) |\n\n## Runner Base Class\n\nThe `Runner` class defines the core interface that all runner implementations must follow. It establishes the lifecycle methods and execution patterns.\n\nSource: [agentlightning/runner/base.py:1-20](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/base.py)\n\n### Lifecycle Methods\n\nThe runner lifecycle consists of four key phases:\n\n```mermaid\ngraph LR\n A[init] --> B[init_worker]\n B --> C[iter/step]\n C --> D[teardown_worker]\n D --> E[teardown]\n```\n\n| Method | Purpose | Must Implement |\n|--------|---------|----------------|\n| `init(agent, hooks)` | Initialize runner with agent and hooks | Yes |\n| `init_worker(worker_id, store)` | Per-worker initialization with store | Yes |\n| `teardown()` | Release resources from init() | Yes |\n| `teardown_worker(worker_id)` | Release per-worker resources | Yes |\n\n### Context Manager Pattern\n\nRunners support a context manager pattern for automatic resource management:\n\n```python\nwith runner.run_context(agent=agent, store=store, hooks=hooks) as runner:\n # Runner is initialized and ready\n await runner.iter()\n# Automatic teardown on exit\n```\n\nSource: [agentlightning/runner/base.py:52-86](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/base.py)\n\nThe `run_context` helper ensures proper cleanup even when exceptions occur:\n\n```python\ntry:\n self.init(agent=agent, hooks=hooks)\n _initialized = True\n self.init_worker(worker_id=0, store=store)\n _worker_initialized = True\n yield self\nfinally:\n try:\n if _worker_initialized:\n self.teardown_worker(worker_id=worker_id if worker_id is not None else 0)\n except Exception:\n logger.error(\"Error during runner worker teardown\", exc_info=True)\n\n try:\n if _initialized:\n self.teardown()\n except Exception:\n logger.error(\"Error during runner teardown\", exc_info=True)\n```\n\n### Execution Methods\n\n| Method | Description | Behavior |\n|--------|-------------|----------|\n| `iter(event)` | Run continuously until event or no tasks | Abstract - subclasses implement |\n| `step()` | Execute single unit of work | Abstract - subclasses implement |\n| `run()` | Legacy run method | Raises `RuntimeError` - use `iter()` or `step()` |\n\nSource: [agentlightning/runner/base.py:88-102](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/base.py)\n\n> **Warning**: The `run()` method raises `RuntimeError` because its behavior is undefined. Always use `iter()` or `step()` instead.\n\n## LitAgentRunner\n\n`LitAgentRunner` is the primary runner implementation that manages the agent-runner relationship, hook registration, and tracer integration.\n\nSource: [agentlightning/runner/agent.py:1-30](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/agent.py)\n\n### Initialization Flow\n\n```mermaid\nsequenceDiagram\n participant Trainer\n participant LitAgentRunner\n participant LitAgent\n participant Tracer\n participant LightningStore\n\n Trainer->>LitAgentRunner: init(agent, hooks)\n LitAgentRunner->>LitAgent: set_runner(self)\n LitAgentRunner->>Tracer: init()\n Trainer->>LitAgentRunner: init_worker(worker_id, store)\n LitAgentRunner->>Tracer: init_worker(worker_id, store)\n```\n\n### Key Properties\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `agent` | `LitAgent[T_task]` | The agent instance (via `get_agent()`) |\n| `store` | `LightningStore` | The backing store (via `get_store()`) |\n| `worker_id` | `Optional[int]` | Unique worker identifier |\n| `tracer` | `Tracer` | Tracer for span emission |\n\nSource: [agentlightning/runner/agent.py:90-110](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/agent.py)\n\n### Accessor Methods\n\n```python\ndef get_agent(self) -> LitAgent[T_task]:\n \"\"\"Get the agent instance.\"\"\"\n if self._agent is None:\n raise ValueError(\"Agent not initialized. Call init() first.\")\n return self._agent\n\ndef get_store(self) -> LightningStore:\n \"\"\"Get the store instance.\"\"\"\n if self._store is None:\n raise ValueError(\"Store not initialized. Call init_worker() first.\")\n return self._store\n\ndef get_worker_id(self) -> str:\n \"\"\"Get the formatted worker ID string.\"\"\"\n return f\"Worker-{self.worker_id}\" if self.worker_id is not None else \"Worker-Unknown\"\n```\n\n### Logging Prefix\n\nThe `_log_prefix()` method generates consistent log prefixes for traceability:\n\n```python\ndef _log_prefix(self, rollout_id: Optional[str] = None) -> str:\n \"\"\"Generate a standardized log prefix for the current worker.\"\"\"\n # Returns format: \"[Worker-{id}] [{rollout_id}]\"\n```\n\n## LegacyAgentRunner\n\n`LegacyAgentRunner` provides backward compatibility for workflows using the AgentOps integration and `AgentLightningClient` communication pattern.\n\nSource: [agentlightning/runner/legacy.py:1-35](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/legacy.py)\n\n### Attributes\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `agent` | `LitAgent[Any]` | The agent instance |\n| `client` | `AgentLightningClient` | Server communication client |\n| `tracer` | `Tracer` | Tracer instance for span emission |\n| `worker_id` | `Optional[str]` | Worker identifier |\n| `max_tasks` | `Optional[int]` | Maximum tasks before stopping |\n\n### Architecture\n\n```mermaid\ngraph TD\n A[LegacyAgentRunner] --> B[LitAgent]\n A --> C[AgentLightningClient]\n A --> D[Tracer]\n C --> E[Server]\n D --> F[LightningStore]\n B --> F\n```\n\n## Hook System Integration\n\nRunners integrate with the hook system to provide extensibility at key lifecycle points:\n\nSource: [agentlightning/types/core.py:1-30](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n\n| Hook | Timing | Purpose |\n|------|--------|---------|\n| `on_trace_start` | Before tracer enters trace context | Logging, metric collection, resource setup |\n| `on_trace_end` | After rollout completes, before tracer exits | Logging, cleanup |\n| `on_rollout_start` | Before rollout attempt begins | Per-attempt initialization |\n| `on_rollout_end` | After rollout attempt completes | Result processing, cleanup |\n\nHooks are registered during initialization and called by the runner at appropriate points during execution.\n\n## Trainer Integration\n\nRunners are instantiated and managed by the `Trainer` class, which orchestrates the entire training loop:\n\nSource: [agentlightning/trainer/trainer.py:40-60](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/trainer/trainer.py)\n\n```python\nclass Trainer(TrainerLegacy):\n \"\"\"High-level orchestration layer that wires Algorithm <-> Runner <-> Store.\"\"\"\n \n # Runner fleet configuration\n n_runners: int # Number of agent runners to run in parallel\n max_rollouts: Optional[int] # Maximum rollouts per runner\n strategy: ExecutionStrategy # Process management strategy\n tracer: Tracer # Tracer instance for telemetry\n hooks: Sequence[Hook] # Lifecycle callbacks\n```\n\n### Training Configuration\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `n_runners` | `int` | Number of parallel agent runners |\n| `max_rollouts` | `Optional[int]` | Stop after N rollouts (None = unlimited) |\n| `strategy` | `ExecutionStrategy` | Spawning strategy (shared memory, client/server) |\n| `tracer` | `Tracer` | Tracer class or config for span collection |\n| `hooks` | `Sequence[Hook]` | Lifecycle callback instances |\n\n## Execution Flow\n\n```mermaid\ngraph TD\n A[Trainer.fit/dev] --> B[Spawn Runner Fleet]\n B --> C[For each Runner]\n C --> D[runner.run_context]\n D --> E[init + init_worker]\n E --> F[iter/event loop]\n F --> G{Tasks available?}\n G -->|Yes| H[Execute step]\n H --> I[Emit spans to Store]\n I --> F\n G -->|No| J[Exit loop]\n J --> K[teardown_worker]\n K --> L[teardown]\n```\n\n## Context Manager Usage\n\nFor debugging or standalone usage outside the Trainer stack:\n\n```python\nfrom agentlightning import LitAgentRunner, InMemoryLightningStore\n\n# Create store and agent\nstore = InMemoryLightningStore()\nagent = MyLitAgent()\n\n# Use context manager\nrunner = LitAgentRunner(tracer=AgentOpsTracer())\nwith runner.run_context(agent=agent, store=store) as runner:\n # Runner initialized and ready\n worker_id = runner.get_worker_id()\n print(f\"Running on {worker_id}\")\n \n # Run until complete\n await runner.iter()\n# Automatic cleanup\n```\n\nSource: [agentlightning/runner/base.py:88-113](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/base.py)\n\n## Error Handling\n\nRunners implement robust error handling during teardown:\n\n| Phase | Error Behavior | Recovery |\n|-------|----------------|----------|\n| `teardown_worker` | Logged but doesn't propagate | Continue to `teardown` |\n| `teardown` | Logged but doesn't propagate | Context manager completes |\n\nThis ensures that multiple cleanup errors don't mask the original failure and that partial cleanup still occurs.\n\n## Summary\n\nThe Runner component provides:\n\n1. **Lifecycle Management** - Consistent init/teardown patterns via context managers\n2. **Worker Isolation** - Per-worker initialization with dedicated store connections\n3. **Hook Integration** - Extensibility through lifecycle callbacks\n4. **Telemetry** - Built-in tracer integration for span emission\n5. **Trainer Integration** - Seamless orchestration within the training loop\n\nRunners are the execution backbone of Agent Lightning, translating high-level training commands into agent task processing while maintaining observability through distributed tracing.\n\n---\n\n\n\n## LightningStore\n\n### Related Pages\n\nRelated topics: [System Architecture](#architecture), [Trainer Component](#trainer)\n\n
\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [agentlightning/store/base.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/base.py)\n- [agentlightning/store/memory.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/memory.py)\n- [agentlightning/store/client_server.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/client_server.py)\n- [agentlightning/store/threading.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/threading.py)\n- [agentlightning/store/collection_based.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/collection_based.py)\n
\n\n# LightningStore\n\nLightningStore is the central data persistence and synchronization layer in Agent Lightning. It manages the lifecycle of AI agent training workflows, including rollouts, attempts, spans, resources, and worker state. The store serves as the backbone for the training loop, enabling distributed execution, tracing, and experiment tracking.\n\n## Overview\n\nLightningStore provides a unified interface for:\n\n- **Rollout Management**: Tracking agent task executions from enqueue to completion\n- **Span Recording**: Capturing fine-grained traces of agent operations via OpenTelemetry\n- **Resource Management**: Storing and versioning agent configurations, prompts, and model definitions\n- **Worker Coordination**: Managing distributed worker states and heartbeats\n- **Metrics Collection**: Aggregating training metrics through Prometheus integration\n\nSource: [agentlightning/store/base.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/base.py)\n\n## Architecture\n\nLightningStore follows a pluggable backend architecture with a unified async interface.\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n Runner[Runner] --> Tracer[Tracers
OtelTracer
AgentOpsTracer]\n Tracer --> Client[LightningStoreClient]\n end\n \n subgraph \"Server Layer\"\n Client --> |HTTP/gRPC| Server[LightningStoreServer]\n Server --> Collections[LightningCollections]\n end\n \n subgraph \"Storage Backends\"\n Collections --> InMemory[InMemoryLightningStore]\n Collections --> SQLite[SQLiteLightningStore]\n Collections --> Mongo[MongoLightningStore]\n end\n \n subgraph \"Thread Safety\"\n Store[Any Store] --> Threaded[LightningStoreThreaded]\n end\n```\n\n### Core Components\n\n| Component | Purpose |\n|-----------|---------|\n| `LightningStore` | Abstract base class defining the store interface |\n| `LightningStoreClient` | HTTP client for remote store communication |\n| `LightningStoreServer` | FastAPI-based server handling store operations |\n| `LightningCollections` | Organized data collections (rollouts, spans, resources, workers) |\n| `LightningStoreThreaded` | Thread-safe wrapper for concurrent access |\n\nSource: [agentlightning/store/client_server.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/client_server.py)\n\n## Data Models\n\n### Core Types\n\nThe store operates on these fundamental data structures:\n\n| Model | Description |\n|-------|-------------|\n| `Rollout` | A complete task execution with status, timestamps, and metadata |\n| `Attempt` | A single attempt within a rollout (supports retries) |\n| `Span` | Fine-grained trace data for agent operations |\n| `TaskInput` | Input data for a task (prompt, parameters) |\n| `Worker` | Worker node state and heartbeat information |\n| `ResourcesUpdate` | Versioned resource configuration storage |\n| `RolloutConfig` | Configuration for rollout execution |\n\nSource: [agentlightning/types/core.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n\n### Rollout Status Lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending: enqueue_rollout\n Pending --> Running: start_rollout\n Running --> Completed: finish_rollout\n Running --> Failed: fail_rollout\n Completed --> [*]\n Failed --> [*]\n \n Running --> Attempted: start_attempt\n Attempted --> Running: finish_attempt\n```\n\nThe status values are:\n- `pending` - Queued for execution\n- `running` - Currently executing\n- `completed` - Successfully finished\n- `failed` - Execution failed\n\nSource: [agentlightning/store/base.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/base.py)\n\n## API Endpoints\n\nThe server exposes REST endpoints under `/v1/agl`:\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/rollouts` | POST | Enqueue new rollouts |\n| `/rollouts/{id}` | GET | Retrieve rollout by ID |\n| `/rollouts/{id}/start` | POST | Mark rollout as started |\n| `/rollouts/{id}/finish` | POST | Complete a rollout |\n| `/rollouts/{id}/attempt` | POST | Start a new attempt |\n| `/rollouts/{id}/attempt/{aid}/finish` | POST | Finish an attempt |\n| `/spans` | POST | Record span data |\n| `/spans/search` | POST | Query spans with filters |\n| `/resources` | POST | Add new resources |\n| `/resources/{id}` | GET/PUT | Get or update resources |\n| `/workers` | POST | Register worker |\n| `/workers/{id}/heartbeat` | POST | Worker heartbeat |\n| `/statistics` | GET | Store statistics |\n\nSource: [agentlightning/store/client_server.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/client_server.py)\n\n## Implementation Backends\n\n### In-Memory Store\n\nThe `InMemoryLightningStore` provides a lightweight, zero-dependency backend suitable for single-node execution and testing.\n\n**Key characteristics:**\n- All data stored in process memory\n- Supports collections with atomic transactions\n- Built-in size estimation for memory monitoring\n- Fast for development and small-scale experiments\n\n```python\nfrom agentlightning import InMemoryLightningStore\n\nstore = InMemoryLightningStore()\n```\n\nSource: [agentlightning/store/memory.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/memory.py)\n\n### SQLite Store\n\nSQLite backend provides persistent storage with ACID guarantees, suitable for single-node deployments requiring durability.\n\n### MongoDB Store\n\nMongoDB backend supports distributed deployments with horizontal scaling, providing high throughput for large-scale training runs.\n\n## Thread Safety\n\nThe `LightningStoreThreaded` class wraps any store implementation to provide thread-safe access:\n\n```python\nfrom agentlightning.store.threading import LightningStoreThreaded\n\n# Wrap any store with thread safety\nthreaded_store = LightningStoreThreaded(store)\n```\n\n**Thread safety features:**\n- Uses `threading.Lock` for synchronization\n- Guarantees atomic operations across concurrent requests\n- Maintains all original store capabilities\n- Exposes `thread_safe: True` and `async_safe: True` in capabilities\n\nSource: [agentlightning/store/threading.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/threading.py)\n\n## Collection Operations\n\nLightningStore uses a collection-based data organization pattern:\n\n```python\n# Atomic write operation\nasync with store.collections.atomic(mode=\"w\", snapshot=..., labels=[\"resources\"]) as collections:\n await collections.resources.insert([update])\n```\n\n### Supported Collections\n\n| Collection | Purpose |\n|------------|---------|\n| `rollouts` | Task execution records |\n| `attempts` | Individual attempt tracking |\n| `spans` | OpenTelemetry trace spans |\n| `resources` | Versioned configurations |\n| `workers` | Worker state management |\n\nSource: [agentlightning/store/collection_based.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/collection_based.py)\n\n## Decorators and Instrumentation\n\nThe store layer uses several decorators for observability and reliability:\n\n| Decorator | Purpose |\n|-----------|---------|\n| `@tracked` | Records operation metrics and timing |\n| `@healthcheck_before` | Validates store health before operations |\n| `@_with_collections_execute` | Manages collection lifecycle and error handling |\n\n## Integration with Tracers\n\nLightningStore integrates with OpenTelemetry through tracers:\n\n```python\nfrom agentlightning import OtelTracer, AgentOpsTracer\n\ntracer = OtelTracer(store=store)\n```\n\n**Tracing workflow:**\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant Tracer\n participant Store\n participant OTLP\n \n Agent->>Tracer: Create span\n Tracer->>Store: Record span data\n Store->>Store: Persist to backend\n Tracer->>OTLP: Export spans (optional)\n```\n\nSource: [examples/minimal/write_traces.py](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/write_traces.py)\n\n## Usage Examples\n\n### Basic Store Operations\n\n```python\nfrom agentlightning import InMemoryLightningStore\n\n# Create store\nstore = InMemoryLightningStore()\n\n# Enqueue a task\nrollout = await store.enqueue_rollout(\n input={\"prompt\": \"Solve this problem\"},\n mode=\"train\"\n)\n\n# Dequeue for processing\ntask = await store.dequeue_rollout(worker_id=\"worker-1\")\n\n# Complete the rollout\nawait store.finish_rollout(\n rollout_id=task.rollout.rollout_id,\n attempt_id=task.attempt.attempt_id,\n response={\"answer\": \"42\"}\n)\n```\n\n### Server Setup\n\n```bash\n# Start a LightningStore server\nagl store --port 45993 --log-level DEBUG\n```\n\n### Client Connection\n\n```python\nfrom agentlightning import LightningStoreClient\n\nclient = LightningStoreClient(base_url=\"http://localhost:45993\")\n\n# All operations work through the client\nrollouts = await client.list_rollouts()\n```\n\n## Capabilities\n\nThe store reports its capabilities through the `capabilities` property:\n\n| Capability | Description |\n|------------|-------------|\n| `async_safe` | Supports async operations |\n| `thread_safe` | Supports concurrent thread access |\n| `distributed` | Supports multi-node deployment |\n| `persistence` | Data survives restarts |\n\nSource: [agentlightning/store/threading.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/threading.py)\n\n## CLI Commands\n\nThe `agl` CLI provides store management:\n\n```bash\n# Start store server\nagl store --port 45993 --log-level DEBUG\n\n# Prometheus metrics endpoint\nagl prometheus\n```\n\nSource: [agentlightning/cli/__init__.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/cli/__init__.py)\n\n---\n\n\n\n## Algorithm Zoo\n\n### Related Pages\n\nRelated topics: [Tutorial: Train Your First Agent](#train-first-agent)\n\n
\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [examples/apo/apo_custom_algorithm.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_custom_algorithm.py)\n- [examples/apo/apo_custom_algorithm_trainer.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_custom_algorithm_trainer.py)\n- [examples/apo/README.md](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/README.md)\n- [CLAUDE.md](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n- [examples/rag/README.md](https://github.com/microsoft/agent-lightning/blob/main/examples/rag/README.md)\n
\n\n# Algorithm Zoo\n\n## Overview\n\nThe **Algorithm Zoo** is a modular collection of training algorithms that consume execution traces from the Agent Lightning runtime to improve agent behavior through reinforcement learning and prompt optimization. Source: [CLAUDE.md](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n\nAgent Lightning runs through a continuous loop where **runners** and **tracers** emit spans, `LightningStore` keeps them synchronized, and algorithms in `agentlightning/algorithm/` consume those traces to improve behavior. Source: [CLAUDE.md](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n\n## Architecture\n\nThe Algorithm Zoo follows a producer-consumer pattern where the store acts as the central synchronization hub:\n\n```mermaid\ngraph TD\n A[Runners] -->|emit spans| B[LightningStore]\n C[Tracers] -->|emit spans| B\n B -->|traces| D[Algorithm Zoo]\n D -->|policy updates| E[Improved Agent Behavior]\n B -->|traces| F[Dashboard]\n```\n\n## Available Algorithms\n\n### APO (Adaptive Prompt Optimization)\n\nAPO is a prompt optimization algorithm that iteratively refines prompt templates based on reward signals collected from agent rollouts.\n\n#### How APO Works\n\nThe APO algorithm maintains a collection of prompt candidates and evaluates each one against task objectives. Based on the reward signals, it selects and refines the most effective prompts. Source: [examples/apo/apo_custom_algorithm.py:34-37](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_custom_algorithm.py)\n\n```python\nasync def apo_algorithm(*, store: agl.LightningStore):\n \"\"\"\n An example of how a prompt optimization works.\n \"\"\"\n prompt_candidates = [\n \"You are a helpful assistant. {any_question}\",\n \"You are a knowledgeable AI. {any_question}\",\n \"You are a friendly chatbot. {any_question}\",\n ]\n\n prompt_and_rewards: list[tuple[str, float]] = []\n```\n\n#### Custom APO Algorithm\n\nTo create a custom algorithm, wrap your async function with the `@algo` decorator. Source: [examples/apo/apo_custom_algorithm_trainer.py:28-39](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_custom_algorithm_trainer.py)\n\n```python\nfrom agentlightning.algorithm import algo\n\n@algo\nasync def apo_algorithm_usable_in_trainer(*, store: LightningStore):\n \"\"\"\n You need to wrap the apo_algorithm in an algo decorator to make it usable in trainer.\n \"\"\"\n return await apo_algorithm(store=store)\n```\n\n### VERL (Value-Enhanced Reinforcement Learning)\n\nVERL is a full training algorithm that integrates with the VERL library for GPU-accelerated reinforcement learning. Source: [examples/tinker/q20_train.py:43-52](https://github.com/microsoft/agent-lightning/blob/main/examples/tinker/q20_train.py)\n\n```python\nalgo_verl_parser = subparsers.add_parser(\"verl\", help=\"Launch the full training algorithm with VERL.\")\nalgo_verl_parser.add_argument(\"--port\", type=int, default=4747, help=\"Port for the AgentLightning store.\")\nalgo_verl_parser.add_argument(\n \"--model\",\n choices=(\"qwen25\", \"qwen3\"),\n default=\"qwen3\",\n help=\"Model variant to train.\",\n)\nalgo_verl_parser.add_argument(\"--search\", action=\"store_true\", help=\"Enable search tool.\")\n```\n\n### FAST (Fast Algorithm Suite Toolkit)\n\nThe FAST algorithm provides lightweight optimization capabilities for rapid experimentation.\n\n## Running Algorithms\n\n### Option A: Separate Components\n\nStart the store, algorithm, and runner in three separate terminals: Source: [examples/apo/README.md:10-24](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/README.md)\n\n```bash\n# Terminal 1: Start the store\nagl store\n\n# Terminal 2: Run the algorithm\npython apo_custom_algorithm.py algo\n\n# Terminal 3: Run the rollout runner\npython apo_custom_algorithm.py runner\n```\n\n### Option B: Integrated Trainer\n\nUse the integrated trainer that handles all components: Source: [examples/apo/apo_custom_algorithm_trainer.py:47-49](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_custom_algorithm_trainer.py)\n\n```python\nfrom agentlightning import Trainer, setup_logging\n\ntrainer = Trainer(n_workers=1, algorithm=apo_algorithm_usable_in_trainer)\ntrainer.fit(apo_rollout)\n```\n\n### Algorithm Decorator\n\nThe `@algo` decorator transforms any async algorithm function into a component that can be used with the `Trainer`. It injects the `LightningStore` as a keyword argument. Source: [examples/apo/apo_custom_algorithm_trainer.py:28-39](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_custom_algorithm_trainer.py)\n\n## Algorithm Configuration\n\n### Common Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `store` | `LightningStore` | Central store for traces and resources |\n| `n_workers` | `int` | Number of parallel workers |\n| `port` | `int` | Port for store connection (default: 4747) |\n\n### VERL-Specific Options\n\n| Option | Choices | Default | Description |\n|--------|---------|---------|-------------|\n| `--model` | qwen25, qwen3 | qwen3 | Model variant to train |\n| `--port` | int | 4747 | Store connection port |\n| `--search` | flag | False | Enable search tool |\n\n## Workflow\n\n```mermaid\ngraph LR\n A[Define Prompt Candidates] --> B[Loop Through Candidates]\n B --> C[Update Resources in Store]\n C --> D[Run Rollout with Runner]\n D --> E[Collect Reward Signal]\n E --> F[Update Prompt Template]\n F --> B\n```\n\n## Extending the Algorithm Zoo\n\n### Creating Custom Algorithms\n\n1. Define an async function that takes `store: LightningStore` as a keyword argument\n2. Wrap it with the `@algo` decorator\n3. Implement your optimization logic\n4. Use the trainer or run separately\n\nExample pattern: Source: [examples/apo/apo_custom_algorithm.py:54-72](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_custom_algorithm.py)\n\n```python\nasync def apo_algorithm(*, store: agl.LightningStore):\n for prompt in prompt_candidates:\n # 1. The optimization algorithm updates the prompt template\n console.print(f\"[Algo] Updating prompt template to: '{prompt}'\")\n resources: agl.NamedResources = {\n # The \"main_prompt\" can be replaced with any name\n }\n # 2. Update resources in store\n # 3. Collect reward signals\n # 4. Refine prompt based on rewards\n```\n\n### Requirements for Custom Algorithms\n\n- Must be async functions\n- Must accept `store` as keyword argument\n- Should be wrapped with `@algo` decorator for trainer integration\n- Must interact with `LightningStore` for state synchronization\n\n## Integration with RAG\n\nThe Algorithm Zoo can be extended to work with retrieval-augmented generation systems. See the RAG example for integrating FAISS-based retrieval with prompt optimization. Source: [examples/rag/README.md](https://github.com/microsoft/agent-lightning/blob/main/examples/rag/README.md)\n\n## See Also\n\n- [APO Tutorial](../../docs/tutorials/apo.md)\n- [Custom Algorithm Tutorial](../../docs/how-to/write-first-algorithm.md)\n- [Dashboard Documentation](../../dashboard/README.md)\n\n---\n\n---\n\n## Doramagic Pitfall Log\n\nProject: microsoft/agent-lightning\n\nSummary: Found 7 potential pitfall items; 0 are high/blocking. Highest priority: capability - 能力判断依赖假设.\n\n## 1. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | README/documentation is current enough for a first validation pass.\n\n## 2. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | last_activity_observed missing\n\n## 3. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | no_demo; severity=medium\n\n## 4. security_permissions · 存在安全注意事项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: No sandbox install has been executed yet; downstream must verify before user use.\n- User impact: 用户安装前需要知道权限边界和敏感操作。\n- Suggested check: 转成明确权限清单和安全审查提示。\n- Guardrail action: 安全注意事项必须面向用户前置展示。\n- Evidence: risks.safety_notes | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 5. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | no_demo; severity=medium\n\n## 6. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | issue_or_pr_quality=unknown\n\n## 7. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | release_recency=unknown\n\n\n", "markdown_key": "agent-lightning", "pages": "draft", "source_refs": [ { "evidence_id": "art_9b504779cfa046a894eeb7c9d3a298c6", "kind": "docs", "supports_claim_ids": [ "claim_identity", "claim_distribution", "claim_capability" ], "url": "https://github.com/microsoft/agent-lightning#readme" } ], "summary": "DeepWiki/Human Wiki output with a Doramagic pitfall appendix.", "title": "agent-lightning 说明书", "toc": [ "https://github.com/microsoft/agent-lightning Project Manual", "Table of Contents", "Introduction to Agent Lightning", "What is Agent Lightning?", "Architecture Overview", "Core Data Models", "Runner System", "Tracing and Instrumentation", "Doramagic 踩坑日志" ] } }, "quality_gate": { "blocking_gaps": [], "category_confidence": "medium", "compile_status": "ready_for_review", "five_assets_present": true, "install_sandbox_verified": true, "missing_evidence": [], "next_action": "publish to Doramagic.ai project surfaces", "prompt_preview_boundary_ok": true, "publish_status": "publishable", "quick_start_verified": true, "repo_clone_verified": true, "repo_commit": "0b40cb724a0ad4f944810f8514884051777bb38b", "repo_inspection_error": null, "repo_inspection_files": [ "pyproject.toml", "README.md", "uv.lock", "docs/index.md", "docs/changelog.md", "docs/how-to/examples-catalog.md", "docs/how-to/train-first-agent.md", "docs/how-to/write-first-algorithm.md", "docs/how-to/unsloth-sft.md", "docs/how-to/train-sql-agent.md", "docs/reference/algorithm.md", "docs/reference/cli.md", "docs/reference/store.md", "docs/reference/agent.md", "docs/reference/utilities.md", "docs/reference/restful.md", "docs/reference/instrumentation.md", "docs/reference/internal.md", "docs/reference/runner.md", "docs/reference/types.md", "docs/reference/semconv.md", "docs/reference/trainer.md", "docs/macros/source_links.py", "docs/tutorials/debug.md", "docs/tutorials/write-agents.md", "docs/tutorials/installation.md", "docs/tutorials/parallelize.md", "docs/tutorials/traces.md", "docs/tutorials/emitter.md", "docs/community/contributing.md", "docs/community/maintainers.md", "docs/javascripts/charts.js", "docs/javascripts/move-source-file.js", "docs/javascripts/katex.js", "docs/algorithm-zoo/index.md", "docs/algorithm-zoo/apo.md", "docs/algorithm-zoo/verl.md", "docs/deep-dive/store.md", "docs/deep-dive/birds-eye-view.md", "docs/deep-dive/serving-llm.md" ], "repo_inspection_verified": true, "review_reasons": [], "tag_count_ok": true, "unsupported_claims": [] }, "schema_version": "0.1", "user_assets": { "ai_context_pack": { "asset_id": "ai_context_pack", "filename": "AI_CONTEXT_PACK.md", "markdown": "# @example/webshop-training - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @example/webshop-training 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **AI 研究者或研究型 Agent 构建者**：README 明确围绕研究、实验或论文工作流展开。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install agentlightning` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `pip install --upgrade --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ --pre agentlightning` 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做角色匹配试用\n- **为什么**：这个项目更像角色库，核心风险是选错角色或把角色文案当执行能力；先用 Prompt Preview 试角色匹配，再决定是否沙盒导入。\n\n### 30 秒判断\n\n- **现在怎么做**：先做角色匹配试用\n- **最小安全下一步**：先用 Prompt Preview 试角色匹配；满意后再隔离导入\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、宿主 AI 配置\n\n### 现在可以相信\n\n- **适合人群线索：AI 研究者或研究型 Agent 构建者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`AGENTS.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`AGENTS.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0006` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0007` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：569\n- 重要文件覆盖：40/569\n- 证据索引条目：80\n- 角色 / Skill 条目：54\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 @example/webshop-training 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @example/webshop-training 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 @example/webshop-training 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 54 个角色 / Skill / 项目文档条目。\n\n- **Contributing Guide**（project_doc）：Agent Lightning gets better every time someone files a clear bug, polishes docs, improves tests, or lands a new feature. This guide collects the expectations, checklists, and tips that help you go from “I have an idea” to “my pull request just merged.” 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/community/contributing.md`\n- **Repository Guidelines**（project_doc）：Architecture Overview Agent Lightning runs through a continuous loop: runners and tracers emit spans, LightningStore agentlightning/store/ keeps them synchronized, and algorithms in agentlightning/algorithm/ consume those traces to improve behavior. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`AGENTS.md`\n- **Agent Lightning⚡**（project_doc）：! Unit Tests https://github.com/microsoft/agent-lightning/actions/workflows/badge-unit.yml/badge.svg https://github.com/microsoft/agent-lightning/actions/workflows/badge-unit.yml ! Documentation https://img.shields.io/badge/GitHub%20Pages-Documentation-blue https://microsoft.github.io/agent-lightning/ ! PyPI version https://badge.fury.io/py/agentlightning.svg https://badge.fury.io/py/agentlightning ! License https:/… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Contrib Area**（project_doc）：This tree hosts experimental integrations, third-party recipes, and curated recipes that are not ready for the main agentlightning/ , examples/ , or docs/ trees. Treat it as an incubator: keep contributions self-contained, clearly owned, and reproducible so downstream users can vendor them without guesswork. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`contrib/README.md`\n- **Agent-lightning Dashboard**（project_doc）：This is the dashboard for Agent-lightning. It is a web application that allows you to inspect your Agent-lightning store and debug running experiments. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`dashboard/README.md`\n- **⚡ Examples Catalog**（project_doc）：This catalog highlights the examples shipped with Agent-lightning. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/README.md`\n- **Agent-OS Integration for Agent-Lightning**（project_doc）：Agent-OS Integration for Agent-Lightning 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`contrib/recipes/agentos/README.md`\n- **Example of AGL Environments**（project_doc）：This example implements agents across various environments within Agent Lightning. The example is designed to run on a single node with 8 GPUs, each having at least 40 GB of memory. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`contrib/recipes/envs/README.md`\n- **Search-R1 Example**（project_doc）：This example implements Search R1 within Agent Lightning. It also serves as a demonstration of a framework-free agent training pipeline , showing how to run end-to-end RL training without relying on specialized frameworks. It's tested and compatible with Agent-lightning v0.2.x . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`contrib/recipes/search_r1/README.md`\n- **WebShop Example**（project_doc）：This example demonstrates how to train a Vercel AI SDK agent on the WebShop benchmark using Agent Lightning with reinforcement learning VERL/GRPO . The training pipeline uses a headless TypeScript runner that executes agent rollouts and reports traces to the Agent Lightning coordinator. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`contrib/recipes/webshop/README.md`\n- **APO Example**（project_doc）：! apo CI status https://github.com/microsoft/agent-lightning/actions/workflows/examples-apo.yml/badge.svg https://github.com/microsoft/agent-lightning/actions/workflows/examples-apo.yml 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/apo/README.md`\n- **Supervised Fine-tuning with Azure OpenAI**（project_doc）：Supervised Fine-tuning with Azure OpenAI 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/azure/README.md`\n- **Calc-X Example**（project_doc）：! calc x CI status https://github.com/microsoft/agent-lightning/actions/workflows/examples-calc-x.yml/badge.svg https://github.com/microsoft/agent-lightning/actions/workflows/examples-calc-x.yml 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/calc_x/README.md`\n- **ChartQA Example**（project_doc）：! chartqa workflow status https://github.com/microsoft/agent-lightning/actions/workflows/badge-chartqa.yml/badge.svg https://github.com/microsoft/agent-lightning/actions/workflows/examples-chartqa.yml 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/chartqa/README.md`\n- **Training Claude Code with Agent-lightning**（project_doc）：Training Claude Code with Agent-lightning 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/claude_code/README.md`\n- **Minimal Component Showcase**（project_doc）：! minimal CI status https://github.com/microsoft/agent-lightning/actions/workflows/badge-unit.yml/badge.svg https://github.com/microsoft/agent-lightning/actions/workflows/badge-unit.yml 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/minimal/README.md`\n- **RAG Agent Example**（project_doc）：! rag workflow status https://github.com/microsoft/agent-lightning/actions/workflows/examples-rag.yml/badge.svg https://github.com/microsoft/agent-lightning/actions/workflows/examples-rag.yml 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/rag/README.md`\n- **Spider Example**（project_doc）：! spider CI status https://github.com/microsoft/agent-lightning/actions/workflows/examples-spider.yml/badge.svg https://github.com/microsoft/agent-lightning/actions/workflows/examples-spider.yml 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/spider/README.md`\n- **Tinker + Agent-lightning Integration**（project_doc）：Tinker + Agent-lightning Integration 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/tinker/README.md`\n- **Unsloth SFT Example**（project_doc）：! unsloth CI status https://github.com/microsoft/agent-lightning/actions/workflows/examples-unsloth.yml/badge.svg https://github.com/microsoft/agent-lightning/actions/workflows/examples-unsloth.yml 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/unsloth/README.md`\n- **Changelog**（project_doc）：Agent-lightning v0.3.0 is a major release that introduces several new features and bug fixes. The release is a collaborative effort between Agent-lightning core teams and the community. Thanks to all the contributors who made this release possible. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/changelog.md`\n- **Agent Lightning**（project_doc）：Agent Lightning is the absolute trainer to light up AI agents. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/index.md`\n- **APO**（project_doc）：You can use the shortcut agl.APO ... to create an APO instance. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/algorithm-zoo/apo.md`\n- **Algorithm Zoo**（project_doc）：AgentLightning includes several popular and frequently requested algorithms in its built-in library, allowing agent developers to use them directly. These algorithms are designed to be compatible with most agent scenarios. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/algorithm-zoo/index.md`\n- **VERL**（project_doc）：You can use the shortcut agl.VERL ... to create a VERL instance. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/algorithm-zoo/verl.md`\n- **Maintainer Guide**（project_doc）：This guide describes the day-to-day responsibilities for Agent Lightning maintainers—how to bump versions, run release ceremonies, interact with CI, and backport fixes safely. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/community/maintainers.md`\n- **The Bird's Eye View of Agent-lightning**（project_doc）：The Bird's Eye View of Agent-lightning 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/deep-dive/birds-eye-view.md`\n- **Serving LLMs under Agent-lightning**（project_doc）：Agent-lightning focuses on data, learning signals, and control flow — not on running model inference. This deep dive explains how to serve a model alongside Agent-lightning so runners can call it reliably, how the LLM Proxy fits into the loop, and why token IDs matter if you care about correctness in training and evaluation. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/deep-dive/serving-llm.md`\n- **Understanding Store**（project_doc）：The LightningStore agentlightning.LightningStore is the central coordination point for Agent-lightning. It holds the task queue, rollouts, attempts, spans, and versioned resources, and exposes a small API both Runners and Algorithms use to communicate. This document explains what's in the store, how statuses transition, how spans are recorded, and the concurrency model threads & processes . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/deep-dive/store.md`\n- **Examples Catalog**（project_doc）：We welcome contributions to the examples catalog! Please refer to the Contributing ../community/contributing.md guide for more details. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/how-to/examples-catalog.md`\n- **Train the First Agent with Agent-lightning**（project_doc）：Train the First Agent with Agent-lightning 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/how-to/train-first-agent.md`\n- **Train SQL Agent with Agent-lightning and VERL**（project_doc）：Train SQL Agent with Agent-lightning and VERL 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/how-to/train-sql-agent.md`\n- **Fine-tune with Unsloth SFT**（project_doc）：Please make sure you have read Write the First Algorithm ./write-first-algorithm.md . Although that recipe is based on a simple prompt tuning algorithm, it introduces the core concepts of Agent-lightning and you should be familiar with them before proceeding. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/how-to/unsloth-sft.md`\n- **Write the First Algorithm with Agent-lightning**（project_doc）：Write the First Algorithm with Agent-lightning 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/how-to/write-first-algorithm.md`\n- **Agent Developer APIs**（project_doc）：These are convenient helpers for creating agents from functions. First-time users are recommended to use these decorators to create agents. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reference/agent.md`\n- **Algorithm-side References**（project_doc）：This reference covers APIs that are designed to be used at \"Algorithm Side\". For built-in algorithms, see Algorithm Zoo ../algorithm-zoo/index.md . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reference/algorithm.md`\n- **Command Line Interface**（project_doc）：This document is a work in progress and might not be updated with the latest changes. Try to use agl -h to get the latest help message. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reference/cli.md`\n- **Instrumentation API**（project_doc）：::: agentlightning.instrumentation.instrument all 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reference/instrumentation.md`\n- **Internal API References**（project_doc）：The following APIs should be used with extra caution because they are very likely to change in the future. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reference/internal.md`\n- **RESTful API References**（project_doc）：Shown in the following is the RESTful API for Lightning Store. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reference/restful.md`\n- **Runner-side References**（project_doc）：This reference covers APIs that are designed to be used at \"Runner Side\". 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reference/runner.md`\n- **Semantic Conventions**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reference/semconv.md`\n- **Store References**（project_doc）：::: agentlightning.LightningStoreCapabilities 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reference/store.md`\n- **Agent-lightning Trainer**（project_doc）：::: agentlightning.ExecutionStrategy 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reference/trainer.md`\n- **Type References**（project_doc）：::: agentlightning.RolloutRawResult 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reference/types.md`\n- **Utility References**（project_doc）：::: agentlightning.utils.id.generate id 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/reference/utilities.md`\n- **Debugging and Troubleshooting**（project_doc）：When you train your own agent with Agent-lightning, most failures surface because the agent logic is brittle or simply incorrect. Debugging becomes easier when you peel back the stack: start by driving the rollout logic on its own, dry-run the trainer loop, and only then bring the full algorithm and runner topology online. The examples/apo/apo debug.py {{ src \"examples/apo/apo debug.py\" }} script demonstrates these… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/tutorials/debug.md`\n- **Using Emitters**（project_doc）：While returning a single float for the final reward is sufficient for many algorithm-agent combinations, some advanced scenarios require richer feedback. For instance, an algorithm might learn more effectively if it receives intermediate rewards throughout a multi-step task, or if the agent needs to emit additional spans for debugging or analysis. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/tutorials/emitter.md`\n- **Installation Guide**（project_doc）：This guide explains how to install Agent-Lightning . You can install it from PyPI the Python Package Index for general use or directly from the source code if you plan to contribute or need fine-grained control over dependencies. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/tutorials/installation.md`\n- **Scaling out Agent-lightning**（project_doc）：Agent-lightning splits training into an algorithm bundle and a runner bundle that exchange work through the LightningStore agentlightning.LightningStore . This tutorial shows how to increase rollout throughput, place bundles across processes or machines, and keep the algorithm side scalable with external frameworks. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/tutorials/parallelize.md`\n- **Working with Traces**（project_doc）：Tracing is the secret capability that lets Agent-lightning train almost any agent without rewriting its core logic. The idea was born in observability tooling inside LLMOps workflows and, in Agent-lightning, evolved into a first-class primitive inside the learning loop. Beyond helping you understand what happened inside a rollout, traces provide reward spans and other learning signals that power reinforcement learni… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/tutorials/traces.md`\n- **Writing Agents**（project_doc）：This tutorial will focus on the heart of the system: the agent itself, guiding you through the different ways to define an agent's logic in Agent-lightning. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/tutorials/write-agents.md`\n- **Responsible AI Transparency Documentation - Agent Lightning**（project_doc）：Responsible AI Transparency Documentation - Agent Lightning 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`RAI_README.md`\n- **Security**（project_doc）：Microsoft takes the security of our software products and services seriously, which includes all source code repositories in our GitHub organizations. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`SECURITY.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Contributing Guide**（documentation）：Agent Lightning gets better every time someone files a clear bug, polishes docs, improves tests, or lands a new feature. This guide collects the expectations, checklists, and tips that help you go from “I have an idea” to “my pull request just merged.” 证据：`docs/community/contributing.md`\n- **Repository Guidelines**（documentation）：Architecture Overview Agent Lightning runs through a continuous loop: runners and tracers emit spans, LightningStore agentlightning/store/ keeps them synchronized, and algorithms in agentlightning/algorithm/ consume those traces to improve behavior. 证据：`AGENTS.md`\n- **Agent Lightning⚡**（documentation）：! Unit Tests https://github.com/microsoft/agent-lightning/actions/workflows/badge-unit.yml/badge.svg https://github.com/microsoft/agent-lightning/actions/workflows/badge-unit.yml ! Documentation https://img.shields.io/badge/GitHub%20Pages-Documentation-blue https://microsoft.github.io/agent-lightning/ ! PyPI version https://badge.fury.io/py/agentlightning.svg https://badge.fury.io/py/agentlightning ! License https://img.shields.io/badge/license-MIT-blue.svg LICENSE ! Ask DeepWiki https://deepwiki.com/badge.svg https://deepwiki.com/microsoft/agent-lightning ! Discord https://img.shields.io/badge/Discord-Join-5865F2?logo=discord&logoColor=white https://discord.gg/RYk7CdvDR7 证据：`README.md`\n- **Contrib Area**（documentation）：This tree hosts experimental integrations, third-party recipes, and curated recipes that are not ready for the main agentlightning/ , examples/ , or docs/ trees. Treat it as an incubator: keep contributions self-contained, clearly owned, and reproducible so downstream users can vendor them without guesswork. 证据：`contrib/README.md`\n- **Agent-lightning Dashboard**（documentation）：This is the dashboard for Agent-lightning. It is a web application that allows you to inspect your Agent-lightning store and debug running experiments. 证据：`dashboard/README.md`\n- **⚡ Examples Catalog**（documentation）：This catalog highlights the examples shipped with Agent-lightning. 证据：`examples/README.md`\n- **Agent-OS Integration for Agent-Lightning**（documentation）：Agent-OS Integration for Agent-Lightning 证据：`contrib/recipes/agentos/README.md`\n- **Example of AGL Environments**（documentation）：This example implements agents across various environments within Agent Lightning. The example is designed to run on a single node with 8 GPUs, each having at least 40 GB of memory. 证据：`contrib/recipes/envs/README.md`\n- **Search-R1 Example**（documentation）：This example implements Search R1 within Agent Lightning. It also serves as a demonstration of a framework-free agent training pipeline , showing how to run end-to-end RL training without relying on specialized frameworks. It's tested and compatible with Agent-lightning v0.2.x . 证据：`contrib/recipes/search_r1/README.md`\n- **WebShop Example**（documentation）：This example demonstrates how to train a Vercel AI SDK agent on the WebShop benchmark using Agent Lightning with reinforcement learning VERL/GRPO . The training pipeline uses a headless TypeScript runner that executes agent rollouts and reports traces to the Agent Lightning coordinator. 证据：`contrib/recipes/webshop/README.md`\n- **APO Example**（documentation）：! apo CI status https://github.com/microsoft/agent-lightning/actions/workflows/examples-apo.yml/badge.svg https://github.com/microsoft/agent-lightning/actions/workflows/examples-apo.yml 证据：`examples/apo/README.md`\n- **Supervised Fine-tuning with Azure OpenAI**（documentation）：Supervised Fine-tuning with Azure OpenAI 证据：`examples/azure/README.md`\n- **Calc-X Example**（documentation）：! calc x CI status https://github.com/microsoft/agent-lightning/actions/workflows/examples-calc-x.yml/badge.svg https://github.com/microsoft/agent-lightning/actions/workflows/examples-calc-x.yml 证据：`examples/calc_x/README.md`\n- **ChartQA Example**（documentation）：! chartqa workflow status https://github.com/microsoft/agent-lightning/actions/workflows/badge-chartqa.yml/badge.svg https://github.com/microsoft/agent-lightning/actions/workflows/examples-chartqa.yml 证据：`examples/chartqa/README.md`\n- **Training Claude Code with Agent-lightning**（documentation）：Training Claude Code with Agent-lightning 证据：`examples/claude_code/README.md`\n- **Minimal Component Showcase**（documentation）：! minimal CI status https://github.com/microsoft/agent-lightning/actions/workflows/badge-unit.yml/badge.svg https://github.com/microsoft/agent-lightning/actions/workflows/badge-unit.yml 证据：`examples/minimal/README.md`\n- **RAG Agent Example**（documentation）：! rag workflow status https://github.com/microsoft/agent-lightning/actions/workflows/examples-rag.yml/badge.svg https://github.com/microsoft/agent-lightning/actions/workflows/examples-rag.yml 证据：`examples/rag/README.md`\n- **Spider Example**（documentation）：! spider CI status https://github.com/microsoft/agent-lightning/actions/workflows/examples-spider.yml/badge.svg https://github.com/microsoft/agent-lightning/actions/workflows/examples-spider.yml 证据：`examples/spider/README.md`\n- **Tinker + Agent-lightning Integration**（documentation）：Tinker + Agent-lightning Integration 证据：`examples/tinker/README.md`\n- **Unsloth SFT Example**（documentation）：! unsloth CI status https://github.com/microsoft/agent-lightning/actions/workflows/examples-unsloth.yml/badge.svg https://github.com/microsoft/agent-lightning/actions/workflows/examples-unsloth.yml 证据：`examples/unsloth/README.md`\n- **Package**（package_manifest）：{ \"name\": \"agent-lightning-dashboard\", \"type\": \"module\", \"version\": \"0.3.1\", \"scripts\": { \"dev\": \"vite\", \"build\": \"tsc && vite build\", \"preview\": \"vite preview\", \"typecheck\": \"tsc --noEmit\", \"eslint\": \"eslint .\", \"stylelint\": \"stylelint ' / .css'\", \"prettier\": \"prettier --check \\\" / .{ts,tsx,mjs,cjs}\\\"\", \"vitest\": \"vitest run --project unit\", \"vitest-storybook\": \"vitest run --project storybook\", \"storybook\": \"storybook dev -p 6006\", \"build-storybook\": \"storybook build\", \"chromatic\": \"chromatic\" }, \"dependencies\": { \"@mantine/core\": \"8.3.5\", \"@mantine/hooks\": \"8.3.5\", \"@monaco-editor/react\": \"^4.7.0\", \"@reduxjs/toolkit\": \"^2.9.2\", \"@tabler/icons-react\": \"^3.35.0\", \"clsx\": \"^2.1.1\", \"dayjs\":… 证据：`dashboard/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@example/webshop-training\", \"version\": \"0.0.0\", \"private\": true, \"scripts\": { \"build:headless\": \"tsup scripts/headless-runner.ts --format cjs --out-dir dist --clean\", \"headless\": \"node dist/headless-runner.js\" }, \"dependencies\": { \"@ai-sdk/openai\": \"3.0.0-beta.89\", \"@opentelemetry/api\": \"^1.9.0\", \"@opentelemetry/context-async-hooks\": \"^1.30.0\", \"@opentelemetry/exporter-trace-otlp-proto\": \"^0.57.0\", \"@opentelemetry/resources\": \"^1.30.0\", \"@opentelemetry/sdk-trace-base\": \"^1.30.0\", \"@opentelemetry/semantic-conventions\": \"^1.30.0\", \"ai\": \"6.0.0-beta.139\", \"zod\": \"3.25.76\" }, \"devDependencies\": { \"@types/node\": \"20.17.24\", \"tsup\": \"^8.0.0\", \"tsx\": \"^4.19.0\", \"typescript\": \"5.8.3\" } } 证据：`contrib/recipes/webshop/package.json`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **Changelog**（documentation）：Agent-lightning v0.3.0 is a major release that introduces several new features and bug fixes. The release is a collaborative effort between Agent-lightning core teams and the community. Thanks to all the contributors who made this release possible. 证据：`docs/changelog.md`\n- **Agent Lightning**（documentation）：Agent Lightning is the absolute trainer to light up AI agents. 证据：`docs/index.md`\n- **APO**（documentation）：You can use the shortcut agl.APO ... to create an APO instance. 证据：`docs/algorithm-zoo/apo.md`\n- **Algorithm Zoo**（documentation）：AgentLightning includes several popular and frequently requested algorithms in its built-in library, allowing agent developers to use them directly. These algorithms are designed to be compatible with most agent scenarios. 证据：`docs/algorithm-zoo/index.md`\n- **VERL**（documentation）：You can use the shortcut agl.VERL ... to create a VERL instance. 证据：`docs/algorithm-zoo/verl.md`\n- **Maintainer Guide**（documentation）：This guide describes the day-to-day responsibilities for Agent Lightning maintainers—how to bump versions, run release ceremonies, interact with CI, and backport fixes safely. 证据：`docs/community/maintainers.md`\n- **The Bird's Eye View of Agent-lightning**（documentation）：The Bird's Eye View of Agent-lightning 证据：`docs/deep-dive/birds-eye-view.md`\n- **Serving LLMs under Agent-lightning**（documentation）：Agent-lightning focuses on data, learning signals, and control flow — not on running model inference. This deep dive explains how to serve a model alongside Agent-lightning so runners can call it reliably, how the LLM Proxy fits into the loop, and why token IDs matter if you care about correctness in training and evaluation. 证据：`docs/deep-dive/serving-llm.md`\n- **Understanding Store**（documentation）：The LightningStore agentlightning.LightningStore is the central coordination point for Agent-lightning. It holds the task queue, rollouts, attempts, spans, and versioned resources, and exposes a small API both Runners and Algorithms use to communicate. This document explains what's in the store, how statuses transition, how spans are recorded, and the concurrency model threads & processes . 证据：`docs/deep-dive/store.md`\n- **Examples Catalog**（documentation）：We welcome contributions to the examples catalog! Please refer to the Contributing ../community/contributing.md guide for more details. 证据：`docs/how-to/examples-catalog.md`\n- **Train the First Agent with Agent-lightning**（documentation）：Train the First Agent with Agent-lightning 证据：`docs/how-to/train-first-agent.md`\n- **Train SQL Agent with Agent-lightning and VERL**（documentation）：Train SQL Agent with Agent-lightning and VERL 证据：`docs/how-to/train-sql-agent.md`\n- **Fine-tune with Unsloth SFT**（documentation）：Please make sure you have read Write the First Algorithm ./write-first-algorithm.md . Although that recipe is based on a simple prompt tuning algorithm, it introduces the core concepts of Agent-lightning and you should be familiar with them before proceeding. 证据：`docs/how-to/unsloth-sft.md`\n- **Write the First Algorithm with Agent-lightning**（documentation）：Write the First Algorithm with Agent-lightning 证据：`docs/how-to/write-first-algorithm.md`\n- **Agent Developer APIs**（documentation）：These are convenient helpers for creating agents from functions. First-time users are recommended to use these decorators to create agents. 证据：`docs/reference/agent.md`\n- **Algorithm-side References**（documentation）：This reference covers APIs that are designed to be used at \"Algorithm Side\". For built-in algorithms, see Algorithm Zoo ../algorithm-zoo/index.md . 证据：`docs/reference/algorithm.md`\n- **Command Line Interface**（documentation）：This document is a work in progress and might not be updated with the latest changes. Try to use agl -h to get the latest help message. 证据：`docs/reference/cli.md`\n- **Instrumentation API**（documentation）：::: agentlightning.instrumentation.instrument all 证据：`docs/reference/instrumentation.md`\n- **Internal API References**（documentation）：The following APIs should be used with extra caution because they are very likely to change in the future. 证据：`docs/reference/internal.md`\n- **RESTful API References**（documentation）：Shown in the following is the RESTful API for Lightning Store. 证据：`docs/reference/restful.md`\n- **Runner-side References**（documentation）：This reference covers APIs that are designed to be used at \"Runner Side\". 证据：`docs/reference/runner.md`\n- **Semantic Conventions**（documentation）：Semantic Conventions ::: agentlightning.semconv 证据：`docs/reference/semconv.md`\n- **Store References**（documentation）：::: agentlightning.LightningStoreCapabilities 证据：`docs/reference/store.md`\n- **Agent-lightning Trainer**（documentation）：::: agentlightning.ExecutionStrategy 证据：`docs/reference/trainer.md`\n- **Type References**（documentation）：::: agentlightning.RolloutRawResult 证据：`docs/reference/types.md`\n- **Utility References**（documentation）：::: agentlightning.utils.id.generate id 证据：`docs/reference/utilities.md`\n- **Debugging and Troubleshooting**（documentation）：When you train your own agent with Agent-lightning, most failures surface because the agent logic is brittle or simply incorrect. Debugging becomes easier when you peel back the stack: start by driving the rollout logic on its own, dry-run the trainer loop, and only then bring the full algorithm and runner topology online. The examples/apo/apo debug.py {{ src \"examples/apo/apo debug.py\" }} script demonstrates these techniques; this guide expands on each approach and helps you decide when to reach for them. 证据：`docs/tutorials/debug.md`\n- **Using Emitters**（documentation）：While returning a single float for the final reward is sufficient for many algorithm-agent combinations, some advanced scenarios require richer feedback. For instance, an algorithm might learn more effectively if it receives intermediate rewards throughout a multi-step task, or if the agent needs to emit additional spans for debugging or analysis. 证据：`docs/tutorials/emitter.md`\n- **Installation Guide**（documentation）：This guide explains how to install Agent-Lightning . You can install it from PyPI the Python Package Index for general use or directly from the source code if you plan to contribute or need fine-grained control over dependencies. 证据：`docs/tutorials/installation.md`\n- **Scaling out Agent-lightning**（documentation）：Agent-lightning splits training into an algorithm bundle and a runner bundle that exchange work through the LightningStore agentlightning.LightningStore . This tutorial shows how to increase rollout throughput, place bundles across processes or machines, and keep the algorithm side scalable with external frameworks. 证据：`docs/tutorials/parallelize.md`\n- **Working with Traces**（documentation）：Tracing is the secret capability that lets Agent-lightning train almost any agent without rewriting its core logic. The idea was born in observability tooling inside LLMOps workflows and, in Agent-lightning, evolved into a first-class primitive inside the learning loop. Beyond helping you understand what happened inside a rollout, traces provide reward spans and other learning signals that power reinforcement learning and fine-tuning algorithms. 证据：`docs/tutorials/traces.md`\n- **Writing Agents**（documentation）：This tutorial will focus on the heart of the system: the agent itself, guiding you through the different ways to define an agent's logic in Agent-lightning. 证据：`docs/tutorials/write-agents.md`\n- **Responsible AI Transparency Documentation - Agent Lightning**（documentation）：Responsible AI Transparency Documentation - Agent Lightning 证据：`RAI_README.md`\n- **Security**（documentation）：Microsoft takes the security of our software products and services seriously, which includes all source code repositories in our GitHub organizations. 证据：`SECURITY.md`\n- **.Stylelintrc**（structured_config）：{ \"extends\": \"stylelint-config-standard-scss\" , \"rules\": { \"custom-property-pattern\": null, \"selector-class-pattern\": null, \"scss/no-duplicate-mixins\": null, \"declaration-empty-line-before\": null, \"declaration-block-no-redundant-longhand-properties\": null, \"alpha-value-notation\": null, \"custom-property-empty-line-before\": null, \"property-no-vendor-prefix\": null, \"color-function-notation\": null, \"length-zero-no-unit\": null, \"selector-not-notation\": null, \"no-descending-specificity\": null, \"comment-empty-line-before\": null, \"scss/at-mixin-pattern\": null, \"scss/at-rule-no-unknown\": null, \"value-keyword-case\": null, \"media-feature-range-notation\": null, \"selector-pseudo-class-no-unknown\": true,… 证据：`dashboard/.stylelintrc.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"types\": \"node\", \"@testing-library/jest-dom\", \"vitest/globals\" , \"target\": \"ESNext\", \"useDefineForClassFields\": true, \"lib\": \"DOM\", \"DOM.Iterable\", \"ESNext\" , \"allowJs\": false, \"skipLibCheck\": true, \"esModuleInterop\": false, \"allowSyntheticDefaultImports\": true, \"strict\": true, \"forceConsistentCasingInFileNames\": true, \"module\": \"ESNext\", \"moduleResolution\": \"Node\", \"resolveJsonModule\": true, \"isolatedModules\": true, \"noEmit\": true, \"jsx\": \"react-jsx\", \"paths\": { \"@/ \": \"./src/ \" , \"@test-utils\": \"./test-utils\" } }, \"include\": \"src\", \"public\", \"test-utils\", \".storybook/main.ts\", \".storybook/preview.tsx\", \".storybook/modes.ts\", \".storybook/constants.ts\", \".storybook/vi… 证据：`dashboard/tsconfig.json`\n- **Pyrightconfig.Fast**（structured_config）：{ \"include\": \"agentlightning\" , \"exclude\": \" /data\", \" /assets\", \"agentlightning/verl\", \"agentlightning/instrumentation\", \"agentlightning/algorithm/apo\", \"agentlightning/algorithm/verl\", \"agentlightning/cli/vllm.py\", \"agentlightning/store/collection/mongo.py\", \"agentlightning/store/mongo.py\", \"agentlightning/tracer/weave.py\", \"contrib/ \" , 证据：`pyrightconfig.fast.json`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`docs/community/contributing.md`, `AGENTS.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`docs/community/contributing.md`, `AGENTS.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\nThe following material strengthens the Repomix/AI Context Pack body. Human Manual is only a reading skeleton; pitfall logs become hard operating constraints for the host AI.\n\n## Human Manual Skeleton\n\nUsage rule: this is only a reading path and salience signal, not factual authority. Concrete facts must still come from repo evidence / Claim Graph.\n\nHard rules for the host AI:\n- Do not treat page titles, order, summaries, or importance as project facts.\n- When explaining the Human Manual skeleton, state that it is only a reading path / salience signal.\n- Capability, installation, compatibility, runtime status, and risk judgments must cite repo evidence, source paths, or Claim Graph.\n\n- **Introduction to Agent Lightning**：importance `high`\n - source_paths: README.md, agentlightning/__init__.py\n- **Installation Guide**：importance `high`\n - source_paths: docs/tutorials/installation.md, pyproject.toml\n- **System Architecture**：importance `high`\n - source_paths: docs/deep-dive/birds-eye-view.md, agentlightning/trainer/trainer.py, agentlightning/store/base.py\n- **Core Abstractions and Data Models**：importance `high`\n - source_paths: agentlightning/types/core.py, agentlightning/types/resources.py, agentlightning/types/tracer.py\n- **Tutorial: Train Your First Agent**：importance `high`\n - source_paths: docs/how-to/train-first-agent.md, examples/apo/room_selector_apo.py, examples/apo/room_selector.py\n- **Tutorial: Writing Agents**：importance `high`\n - source_paths: docs/tutorials/write-agents.md, agentlightning/litagent/litagent.py, agentlightning/litagent/decorator.py\n- **Trainer Component**：importance `high`\n - source_paths: agentlightning/trainer/trainer.py, agentlightning/trainer/registry.py, agentlightning/trainer/init_utils.py\n- **Runner Component**：importance `high`\n - source_paths: agentlightning/runner/base.py, agentlightning/runner/agent.py, agentlightning/runner/legacy.py\n\n## Repo Inspection Evidence\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `0b40cb724a0ad4f944810f8514884051777bb38b`\n- inspected_files: `pyproject.toml`, `README.md`, `uv.lock`, `docs/index.md`, `docs/changelog.md`, `docs/how-to/examples-catalog.md`, `docs/how-to/train-first-agent.md`, `docs/how-to/write-first-algorithm.md`, `docs/how-to/unsloth-sft.md`, `docs/how-to/train-sql-agent.md`, `docs/reference/algorithm.md`, `docs/reference/cli.md`, `docs/reference/store.md`, `docs/reference/agent.md`, `docs/reference/utilities.md`, `docs/reference/restful.md`, `docs/reference/instrumentation.md`, `docs/reference/internal.md`, `docs/reference/runner.md`, `docs/reference/types.md`\n\nHard rules for the host AI:\n- Without repo_clone_verified=true, do not claim the source code has been read.\n- Without repo_inspection_verified=true, do not turn README/docs/package observations into facts.\n- Without quick_start_verified=true, do not claim the Quick Start has been successfully run.\n\n## Doramagic Pitfall Constraints\n\nThese rules come from Doramagic discovery, validation, or compilation pitfalls. The host AI must treat them as operating constraints, not general background notes.\n\n### Constraint 1: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | README/documentation is current enough for a first validation pass.\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 2: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | last_activity_observed missing\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 3: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | no_demo; severity=medium\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 4: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: risks.safety_notes | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | No sandbox install has been executed yet; downstream must verify before user use.\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 5: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | no_demo; severity=medium\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 6: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | issue_or_pr_quality=unknown\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 7: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | release_recency=unknown\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n", "summary": "Context and operating boundaries for host AI agents.", "title": "AI Context Pack" }, "boundary_risk_card": { "asset_id": "boundary_risk_card", "filename": "BOUNDARY_RISK_CARD.md", "markdown": "# Boundary & Risk Card\n\nProject: microsoft/agent-lightning\n\n## Doramagic Trial Decision\n\nCurrent decision: it can enter pre-publication recommendation checks. First use should still start with least privilege, a temporary directory, and reversible configuration.\n\n## What The User Can Do Now\n\n- Read the Human Manual first to understand the project purpose and main workflows.\n- Use Prompt Preview for pre-install exploration; it validates interaction shape, not real execution.\n- Run official Quick Start commands only inside an isolated environment, not a primary setup.\n\n## Do Not Do Yet\n\n- Do not treat Prompt Preview as a real project execution result.\n- Do not treat metadata-only validation as sandbox installation validation.\n- Do not describe unverified capabilities as supported, working, or safe to install.\n- Do not provide production data, private files, real secrets, or primary host configuration on first trial.\n\n## Pre-Install Checklist\n\n- Host AI match: chatgpt\n- Official installation entry status: official entry point found\n- Isolated temporary directory, temporary host, or container validation: required\n- Configuration rollback path: required\n- API keys, network access, file access, or host configuration changes: treat as high risk until confirmed\n- Installation command, actual output, and failure logs: must be recorded\n\n## Current Blockers\n\n- No blockers.\n\n## Project-Specific Pitfalls\n\n- 能力判断依赖假设 (medium): 假设不成立时，用户拿不到承诺的能力。 Suggested check: 将假设转成下游验证清单。\n- 维护活跃度未知 (medium): 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项 (medium): 下游已经要求复核，不能在页面中弱化。 Suggested check: 进入安全/权限治理复核队列。\n- 存在安全注意事项 (medium): 用户安装前需要知道权限边界和敏感操作。 Suggested check: 转成明确权限清单和安全审查提示。\n- 存在评分风险 (medium): 风险会影响是否适合普通用户安装。 Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n\n## Risk And Permission Notes\n\n- no_demo: medium\n\n## Evidence Gaps\n\n- No structured evidence gaps are currently visible.\n", "summary": "Installation, permission, validation, and pre-recommendation risks.", "title": "Boundary & Risk Card" }, "human_manual": { "asset_id": "human_manual", "filename": "HUMAN_MANUAL.md", "markdown": "# https://github.com/microsoft/agent-lightning Project Manual\n\nGenerated on: 2026-05-21 09:13:59 UTC\n\n## Table of Contents\n\n- [Introduction to Agent Lightning](#introduction)\n- [Installation Guide](#installation)\n- [System Architecture](#architecture)\n- [Core Abstractions and Data Models](#core_abstractions)\n- [Tutorial: Train Your First Agent](#train-first-agent)\n- [Tutorial: Writing Agents](#write-agents)\n- [Trainer Component](#trainer)\n- [Runner Component](#runner)\n- [LightningStore](#store)\n- [Algorithm Zoo](#algorithm-zoo)\n\n\n\n## Introduction to Agent Lightning\n\n### Related Pages\n\nRelated topics: [System Architecture](#architecture), [Installation Guide](#installation)\n\n
\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/microsoft/agent-lightning/blob/main/README.md)\n- [CLAUDE.md](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n- [AGENTS.md](https://github.com/microsoft/agent-lightning/blob/main/AGENTS.md)\n- [examples/minimal/README.md](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/README.md)\n- [examples/claude_code/README.md](https://github.com/microsoft/agent-lightning/blob/main/examples/claude_code/README.md)\n- [agentlightning/types/core.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n- [agentlightning/runner/base.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/base.py)\n- [agentlightning/semconv.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/semconv.py)\n- [agentlightning/cli/__init__.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/cli/__init__.py)\n- [contrib/recipes/agentos/README.md](https://github.com/microsoft/agent-lightning/blob/main/contrib/recipes/agentos/README.md)\n- [dashboard/README.md](https://github.com/microsoft/agent-lightning/blob/main/dashboard/README.md)\n- [mkdocs.yml](https://github.com/microsoft/agent-lightning/blob/main/mkdocs.yml)\n
\n\n# Introduction to Agent Lightning\n\nAgent Lightning is a reinforcement learning framework designed to train any AI agent with RL algorithms. The project provides a unified execution stack, instrumentation capabilities, and training infrastructure that enables researchers and developers to improve agent behavior through reward-based learning. Source: [README.md:1](https://github.com/microsoft/agent-lightning/blob/main/README.md)\n\n## What is Agent Lightning?\n\nAgent Lightning bridges the gap between raw agent execution and RL-based training by providing:\n\n- **Instrumentation Layer**: Transparent tracing and logging of agent interactions\n- **Training Infrastructure**: Built-in support for RL algorithms like GRPO\n- **Distributed Execution**: Multi-worker rollout management with state synchronization\n- **Integration Points**: Adapters for popular agent frameworks and execution environments\n\nThe framework treats agent training as a continuous feedback loop where traces collected from agent execution are consumed by training algorithms to improve policy behavior over time. Source: [CLAUDE.md:3](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n\n## Architecture Overview\n\nThe Agent Lightning architecture follows a producer-consumer pattern centered around trace collection and consumption.\n\n### Core Loop\n\n```mermaid\ngraph TD\n A[Runner] -->|emits spans| B[Tracers]\n B -->|writes traces| C[LightningStore]\n C -->|serves traces| D[Algorithms]\n D -->|updates policy| A\n C -->|serves traces| E[Dashboard]\n```\n\nThe continuous execution loop works as follows:\n\n1. **Runners** execute agents and emit execution spans\n2. **Tracers** capture and format these spans with semantic conventions\n3. **LightningStore** maintains synchronized state across all components\n4. **Algorithms** consume traces to compute rewards and update agent policies\n5. **Dashboard** provides real-time visualization for debugging\n\nSource: [CLAUDE.md:3](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n\n### Component Hierarchy\n\n| Layer | Components | Responsibility |\n|-------|-----------|----------------|\n| Execution | `Runner`, `LitAgent` | Execute agent logic and manage lifecycle |\n| Instrumentation | `Tracer`, `OtelTracer`, `AgentOpsTracer` | Capture execution traces |\n| Storage | `LightningStore`, `LightningStoreClient` | Synchronized state management |\n| Training | Algorithms in `agentlightning/algorithm/` | Process traces, compute rewards |\n| CLI | `agl` command | User-facing interface |\n\nSource: [agentlightning/cli/__init__.py:13-16](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/cli/__init__.py)\n\n## Core Data Models\n\nThe framework defines several fundamental data structures in `agentlightning/types/core.py`.\n\n### Task and Rollout\n\n```mermaid\nclassDiagram\n class Task {\n +str task_id\n +Any input\n +Optional~str~ instance_id\n +Optional~str~ dataset\n }\n class Rollout {\n +str rollout_id\n +str status\n +Optional~str~ worker_id\n +List~Attempt~ attempts\n }\n class Attempt {\n +str attempt_id\n +str status\n +List~Span~ spans\n +Optional~float~ reward\n }\n class Triplet {\n +Any prompt\n +Any response\n +Optional reward\n }\n \n Task \"1\" --> \"*\" Rollout\n Rollout \"1\" --> \"*\" Attempt\n Attempt --> Triplet\n```\n\n### Core Type Exports\n\n| Type | Purpose |\n|------|---------|\n| `Task` | Represents a unit of work to be executed by an agent |\n| `Rollout` | Collection of attempts for a single task execution |\n| `Attempt` | Single execution attempt with spans and reward |\n| `Triplet` | Prompt-response-reward tuple for RL training |\n| `LightningStore` | Synchronized state store for distributed execution |\n\nSource: [agentlightning/types/core.py:1-60](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n\n## Runner System\n\nThe runner system provides the execution context for agents with integrated lifecycle management.\n\n### Runner Lifecycle\n\n```mermaid\nsequenceDiagram\n participant User\n participant Runner\n participant Store\n participant Agent\n \n User->>Runner: async with Runner(agent, store)\n Runner->>Runner: init(agent)\n Runner->>Runner: init_worker(store)\n Runner->>Store: Register worker\n Loop Until event\n Runner->>Agent: Execute task\n Agent-->>Runner: Result\n Runner->>Store: Update state\n end\n Runner->>Runner: teardown_worker()\n Runner->>Runner: teardown()\n```\n\n### Runner Base Class\n\nThe `Runner` class provides context manager support for safe initialization and cleanup:\n\n```python\nasync with runner:\n runner.init(agent=agent, hooks=hooks)\n runner.init_worker(worker_id=0, store=store)\n # Execute tasks...\n```\n\nKey runner responsibilities:\n- **Initialization**: Set up agent and worker state\n- **Execution**: Poll store for tasks and execute them\n- **Cleanup**: Graceful teardown of worker and agent resources\n\nSource: [agentlightning/runner/base.py:1-80](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/base.py)\n\n## Tracing and Instrumentation\n\nAgent Lightning provides multiple tracing backends for capturing agent execution.\n\n### Supported Tracers\n\n| Tracer | Use Case | Backend |\n|--------|----------|---------|\n| `OtelTracer` | OpenTelemetry-compatible tracing | OTLP endpoint |\n| `AgentOpsTracer` | AgentOps platform integration | AgentOps service |\n| Custom Tracer | Framework integration | Pluggable |\n\n### Semantic Conventions\n\nThe framework defines semantic conventions in `agentlightning/semconv.py` for consistent span attributes:\n\n| Attribute | Description |\n|-----------|-------------|\n| `LightningSpanAttributes.REWARD` | Reward values for RL spans |\n| `LightningSpanAttributes.LINK` | Span linking relationships |\n| `LightningSpanAttributes.TAG` | Custom span tagging |\n| `LightningResourceAttributes.ROLLOUT_ID` | Rollout identification |\n| `LightningResourceAttributes.ATTEMPT_ID` | Attempt identification |\n\nSource: [agentlightning/semconv.py:1-40](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/semconv.py)\n\n### Trace Writing Example\n\nThe minimal examples demonstrate trace writing with `LightningStore`:\n\n```python\nfrom agentlightning import AgentOpsTracer, LightningStoreClient, OtelTracer, Span\n\n# Write traces directly to in-memory store\nstore = InMemoryLightningStore()\ntracer = OtelTracer(store=store)\n\n# Or connect to a server-side store\nclient = LightningStoreClient(endpoint=\"http://localhost:45993\")\n```\n\nSource: [examples/minimal/write_traces.py:1-50](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/write_traces.py)\n\n## LightningStore\n\n`LightningStore` is the central state management component that keeps all components synchronized.\n\n### Store Capabilities\n\n```mermaid\ngraph LR\n A[Runners] -->|enqueue/dequeue| B[Rollouts]\n A -->|register| C[Workers]\n D[Tracers] -->|write spans| B\n E[Algorithms] -->|query traces| B\n F[Dashboard] -->|inspect state| B\n```\n\n### Store Collections\n\n| Collection | Data Type | Access Pattern |\n|------------|-----------|----------------|\n| `rollouts` | `Rollout` | Enqueue/dequeue by worker |\n| `attempts` | `Attempt` | Link to rollout |\n| `spans` | `Span` | Query by attempt |\n| `workers` | `Worker` | Heartbeat management |\n| `resources` | `ResourcesUpdate` | Model/prompt versioning |\n\nSource: [dashboard/test-utils/python-server.py:1-100](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n\n## Training Algorithms\n\nAgent Lightning integrates with reinforcement learning algorithms to improve agent behavior.\n\n### Algorithm Integration\n\nThe framework supports pluggable algorithms defined in `agentlightning/algorithm/`. Algorithms consume traces from the LightningStore and compute policy updates.\n\n### Agent-OS Integration\n\nFor production safety-critical deployments, Agent Lightning integrates with Agent-OS:\n\n```python\nfrom agentlightning.contrib.runner.agentos import AgentOSRunner\nfrom agentlightning.contrib.reward.agentos import PolicyReward\n\nrunner = AgentOSRunner(kernel, fail_on_violation=False, emit_violations=True)\nreward_fn = PolicyReward(kernel)\n```\n\nThis integration provides:\n- **Policy enforcement**: Kernel-level safety during training\n- **Violation penalties**: Unsafe actions convert to negative RL rewards\n- **Audit trail**: Complete visibility from training to production\n\nSource: [contrib/recipes/agentos/README.md:1-60](https://github.com/microsoft/agent-lightning/blob/main/contrib/recipes/agentos/README.md)\n\n## Minimal Component Showcase\n\nThe `examples/minimal/` directory provides isolated demonstrations of individual building blocks.\n\n### Available Examples\n\n| Component | File | Demonstrates |\n|-----------|------|--------------|\n| LightningStore + OTLP | `write_traces.py` | `OtelTracer`, `AgentOpsTracer`, rollout/span emission |\n| MultiMetrics backend | `write_metrics.py` | Console and Prometheus metrics simultaneously |\n| LLM proxying | `llm_proxy.py` | Request routing through `/rollout//attempt/` |\n| vLLM lifecycle | `vllm_server.py` | Server startup, readiness monitoring, teardown |\n\nEach example is self-documenting with CLI arguments and environment variables embedded in module docstrings.\n\nSource: [examples/minimal/README.md:1-30](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/README.md)\n\n## Command-Line Interface\n\nThe `agl` CLI provides entry points for all major framework operations.\n\n### Available Subcommands\n\n| Command | Module | Description |\n|---------|--------|-------------|\n| `agl vllm` | `agentlightning.cli.vllm` | vLLM server with instrumentation |\n| `agl store` | `agentlightning.cli.store` | LightningStore server |\n| `agl prometheus` | `agentlightning.cli.prometheus` | Prometheus metrics endpoint |\n| `agl agentops` | `agentlightning.cli.agentops_server` | AgentOps server manager |\n\n### Starting a LightningStore Server\n\n```bash\nagl store --port 45993 --log-level DEBUG\n```\n\nThe store server enables distributed execution where multiple workers can connect and synchronize state.\n\nSource: [agentlightning/cli/__init__.py:1-35](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/cli/__init__.py)\n\n## Dashboard\n\nThe Agent Lightning Dashboard is a React-based web application for inspecting store state and debugging experiments.\n\n### Features\n\n- **Real-time state inspection**: View rollouts, attempts, and spans\n- **Worker monitoring**: Track worker status and heartbeat statistics\n- **Resource visualization**: Inspect model configurations and prompts\n- **Experiment debugging**: Analyze trace sequences and reward flows\n\n### Technology Stack\n\n| Layer | Technology |\n|-------|------------|\n| Framework | React |\n| UI Components | Mantine UI |\n| Documentation | Storybook |\n| Testing | Vitest |\n\nSource: [dashboard/README.md:1-35](https://github.com/microsoft/agent-lightning/blob/main/dashboard/README.md)\n\n## Project Structure\n\n```\nagent-lightning/\n├── agentlightning/ # Core library\n│ ├── algorithm/ # RL training algorithms\n│ ├── cli/ # Command-line interface\n│ ├── contrib/ # Third-party integrations\n│ ├── runner/ # Execution runners\n│ ├── store/ # LightningStore implementations\n│ ├── tracer/ # Tracing backends\n│ ├── types/ # Data models\n│ └── semconv.py # Semantic conventions\n├── contrib/\n│ └── recipes/ # Integration examples (webshop, agentos)\n├── dashboard/ # React web application\n├── docs/ # Documentation (mkdocs)\n├── examples/ # Runnable workflows\n├── scripts/ # Automation scripts\n└── tests/ # Test suite\n```\n\nSource: [CLAUDE.md:5-15](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n\n## Development Workflow\n\n### Setup\n\n```bash\nuv sync --group dev\n```\n\n### Testing\n\n```bash\n# Full test suite\nuv run --no-sync pytest -v\n\n# Specific tests\nuv run --no-sync pytest -v tests/path/to/test.py\nuv run --no-sync pytest -v -k \"test_pattern\"\n```\n\n### Type Checking\n\n```bash\nuv run --no-sync pyright\n```\n\n### Pre-commit Checks\n\n```bash\nuv run --no-sync pre-commit run --all-files --show-diff-on-failure\n```\n\n### Documentation\n\n```bash\nuv run --no-sync mkdocs build --strict\n```\n\nSource: [CLAUDE.md:18-30](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n\n## Contributing\n\nAgent Lightning welcomes contributions through a structured process:\n\n1. **Branch naming**: `feature/`, `fix/`, `docs/`, or `chore/`\n2. **Commits**: Imperative, scoped commits with issue references (e.g., `Fixes #123`)\n3. **Pre-submission**: Run pre-commit hooks and relevant pytest/doc builds\n4. **CLA**: Contributor License Agreement required (automatically prompted by CLA bot)\n\nSource: [README.md:50-70](https://github.com/microsoft/agent-lightning/blob/main/README.md)\n\n## Citation\n\nIf you use Agent Lightning in research, please cite:\n\n```bibtex\n@misc{luo2025agentlightningtrainai,\n title={Agent Lightning: Train ANY AI Agents with Reinforcement Learning},\n author={Xufang Luo and Yuge Zhang and Zhiyuan He and Zilong Wang and Siyun Zhao and Dongsheng Li and Luna K. Qiu and Yuqing Yang},\n year={2025},\n eprint={2508.03680},\n archivePrefix={arXiv},\n primaryClass={cs.AI},\n url={https://arxiv.org/abs/2508.03680},\n}\n```\n\nSource: [README.md:15-25](https://github.com/microsoft/agent-lightning/blob/main/README.md)\n\n## Further Reading\n\n- [Minimal Examples Guide](../examples/minimal/) - Hands-on with individual components\n- [Claude Code Integration](../examples/claude_code/) - Example: Training with SWE-bench\n- [Agent-OS Integration](../contrib/recipes/agentos/) - Safety-critical training\n- [API Reference](../api/) - Detailed type and function documentation\n\n---\n\n\n\n## Installation Guide\n\n### Related Pages\n\nRelated topics: [Introduction to Agent Lightning](#introduction), [Tutorial: Train Your First Agent](#train-first-agent)\n\n
\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [docs/tutorials/installation.md](https://github.com/microsoft/agent-lightning/blob/main/docs/tutorials/installation.md)\n- [pyproject.toml](https://github.com/microsoft/agent-lightning/blob/main/pyproject.toml)\n- [CLAUDE.md](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n- [AGENTS.md](https://github.com/microsoft/agent-lightning/blob/main/AGENTS.md)\n- [contrib/recipes/webshop/agl/requirements.txt](https://github.com/microsoft/agent-lightning/blob/main/contrib/recipes/webshop/agl/requirements.txt)\n- [README.md](https://github.com/microsoft/agent-lightning/blob/main/README.md)\n
\n\n# Installation Guide\n\nThis guide covers all supported methods for installing and configuring Agent Lightning in your environment. Agent Lightning is a reinforcement learning framework for training AI agents, with support for GPU acceleration, distributed training, and various algorithm backends.\n\n## Prerequisites\n\n### System Requirements\n\n| Component | Minimum | Recommended |\n|-----------|---------|-------------|\n| Python | 3.10+ | 3.11 or 3.12 |\n| OS | Linux (Ubuntu 20.04+), macOS | Linux with CUDA |\n| RAM | 8 GB | 32 GB+ |\n| GPU | Optional | NVIDIA GPU with CUDA 11.8+ |\n| Disk Space | 5 GB | 20 GB+ |\n\nSource: [contrib/recipes/webshop/agl/requirements.txt:1-3]()\n\n### Required Tools\n\n- **uv**: Modern Python package manager (recommended)\n- **Git**: For cloning the repository\n- **CUDA Toolkit** (for GPU training): Version 11.8 or later\n\n## Installation Methods\n\n### Method 1: Install from Source\n\nThis is the recommended approach for development and contributing.\n\n```bash\n# Clone the repository\ngit clone https://github.com/microsoft/agent-lightning.git\ncd agent-lightning\n\n# Install all dependencies including development tools\nuv sync --group dev\n\n# Install optional GPU dependencies\nuv sync --group GPU\n```\n\nSource: [CLAUDE.md:20-22]()\n\n### Method 2: Install with Specific Algorithm Backends\n\nAgent Lightning supports multiple reinforcement learning algorithms through optional dependency groups:\n\n```bash\n# Install with VERL backend (recommended for GPU training)\nuv sync --group VERL\n\n# Install with APO backend\nuv sync --group APO\n\n# Install with GPU optimizations\nuv sync --group GPU\n```\n\nSource: [CLAUDE.md:22]()\n\n### Method 3: Using setup.sh for GPU Training\n\nFor GPU-accelerated training with the webshop recipe:\n\n```bash\n# From the contrib/recipes/webshop directory\n./setup.sh\n```\n\nThis script installs VERL extras for GPU training support. Source: [contrib/recipes/webshop/agl/requirements.txt:1-8]()\n\n## Dependency Groups\n\nThe `pyproject.toml` defines several optional dependency groups:\n\n| Group | Purpose | Installation Command |\n|-------|---------|---------------------|\n| `dev` | Development tools (pytest, pyright, pre-commit) | `uv sync --group dev` |\n| `GPU` | GPU acceleration packages | `uv sync --group GPU` |\n| `VERL` | VERL algorithm backend | `uv sync --group VERL` |\n| `APO` | APO algorithm backend | `uv sync --group APO` |\n\nSource: [CLAUDE.md:20-23]()\n\n## Environment Setup\n\n### Creating a Virtual Environment\n\nUsing `uv` (recommended):\n\n```bash\n# Create and activate a new virtual environment\nuv venv\nsource .venv/bin/activate # Linux/macOS\n# or\n.venv\\Scripts\\activate # Windows\n```\n\n### Verifying Installation\n\nRun the test suite to verify your installation:\n\n```bash\n# Run all tests\nuv run --no-sync pytest -v\n\n# Run specific test\nuv run --no-sync pytest -v tests/path/to/test.py\n\n# Run tests matching a pattern\nuv run --no-sync pytest -v -k \"test_pattern\"\n```\n\nSource: [CLAUDE.md:21]()\n\n### Type Checking\n\nVerify type annotations are correct:\n\n```bash\nuv run --no-sync pyright\n```\n\nSource: [CLAUDE.md:22]()\n\n### Pre-commit Hooks\n\nBefore committing code, run pre-commit checks:\n\n```bash\nuv run --no-sync pre-commit run --all-files --show-diff-on-failure\n```\n\nSource: [CLAUDE.md:23]()\n\n## Dashboard Installation\n\nThe Agent Lightning Dashboard is a separate React application:\n\n```bash\ncd dashboard\n\n# Install dependencies\nnpm install\n\n# Start development server\nnpm run dev\n\n# Build for production\nnpm run build\n```\n\nSource: [dashboard/README.md:npm scripts section]()\n\n### Dashboard npm Scripts\n\n| Script | Purpose |\n|--------|---------|\n| `dev` | Start development server |\n| `build` | Build production bundle |\n| `preview` | Preview production build locally |\n| `storybook` | Start Storybook dev server |\n| `build-storybook` | Build Storybook bundle |\n| `eslint` | Run ESLint |\n| `stylelint` | Run Stylelint |\n| `prettier` | Run Prettier |\n| `typecheck` | Run TypeScript typecheck |\n| `vitest` | Run vitest tests |\n\nSource: [dashboard/README.md:npm scripts]()\n\n## Recipe-Specific Installation\n\n### Webshop Recipe\n\nThe webshop recipe has specific dependencies:\n\n```bash\ncd contrib/recipes/webshop/agl\n\n# Install requirements\npip install -r requirements.txt\n\n# For GPU training\n./setup.sh\n```\n\nRequired dependencies include:\n- `pandas>=2.0.0` - Data manipulation\n- `pyarrow>=14.0.0` - Parquet file support\n- `rich>=13.0.0` - Terminal formatting\n- `tqdm>=4.64.0` - Progress bars\n\nSource: [contrib/recipes/webshop/agl/requirements.txt:1-15]()\n\n## Development Workflow\n\n### Branching Conventions\n\nCreate feature branches from a fresh `main`:\n\n| Branch Type | Naming Convention |\n|-------------|-------------------|\n| Feature | `feature/` |\n| Fix | `fix/` |\n| Documentation | `docs/` |\n| Maintenance | `chore/` |\n\nSource: [CLAUDE.md:8](), [AGENTS.md:8]()\n\n### Commit and PR Guidelines\n\n1. Write imperative, scoped commit messages\n2. Reference issues with `Fixes #123`\n3. Rerun pre-commit and relevant pytest/doc builds before pushing\n4. Include verification commands in PR descriptions\n5. Update documentation via `mkdocs.yml` or `examples/README.md`\n\nSource: [CLAUDE.md:9-13](), [AGENTS.md:9-13]()\n\n## GPU Configuration\n\nFor optimal GPU training performance:\n\n1. Install NVIDIA drivers (CUDA 11.8+)\n2. Install the `GPU` dependency group\n3. For VERL-based training, use `uv sync --group GPU`\n\nGPU metrics are tracked via heartbeat statistics in worker nodes:\n\n```python\nheartbeat_stats={\"queue_depth\": 2, \"gpu_utilization\": 0.82}\n```\n\nSource: [dashboard/test-utils/python-server.py:Worker class]()\n\n## Troubleshooting\n\n### Common Issues\n\n| Issue | Solution |\n|-------|----------|\n| `uv` command not found | Install uv: `pip install uv` |\n| CUDA not found | Ensure NVIDIA drivers and CUDA toolkit are installed |\n| Import errors | Run `uv sync` to ensure all dependencies are installed |\n| Type checking failures | Run `uv run --no-sync pyright` to identify issues |\n\nSource: [CLAUDE.md:26-30]()\n\n### Lock File Updates\n\nWhen dependencies change, commit the refreshed `uv.lock`:\n\n```bash\ngit add uv.lock\ngit commit -m \"chore: update lock file\"\n```\n\nSource: [CLAUDE.md:24]()\n\n## Next Steps\n\nAfter installation:\n\n1. Explore [Minimal Component Showcase](examples/minimal/README.md) to understand individual components\n2. Set up the [LightningStore](agentlightning/store/) for trace storage\n3. Configure [tracers](agentlightning/tracer/) for your agent execution\n4. Review the [Algorithm Documentation](docs/tutorials/) for training options\n\n---\n\n\n\n## System Architecture\n\n### Related Pages\n\nRelated topics: [Trainer Component](#trainer), [Runner Component](#runner), [LightningStore](#store)\n\n
\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [dashboard/src/layouts/AppLayout.tsx](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/layouts/AppLayout.tsx)\n- [dashboard/src/pages/Rollouts.page.tsx](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/pages/Rollouts.page.tsx)\n- [dashboard/src/pages/Resources.page.tsx](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/pages/Resources.page.tsx)\n- [dashboard/src/pages/Workers.page.tsx](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/pages/Workers.page.tsx)\n- [dashboard/src/components/TracesTable.component.tsx](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/TracesTable.component.tsx)\n- [dashboard/src/components/WorkersTable.component.tsx](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/WorkersTable.component.tsx)\n- [dashboard/src/components/AppDrawer.component.tsx](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/AppDrawer.component.tsx)\n- [dashboard/test-utils/python-server.py](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n
\n\n# System Architecture\n\n## Overview\n\nAgent Lightning is a reinforcement learning framework for training AI agents, with a distributed system architecture that supports multi-worker training orchestration, resource management, and distributed tracing. The system consists of three primary layers: a **Backend Training Engine**, a **State Store**, and a **Dashboard Frontend**.\n\nThe architecture enables parallel training across multiple workers, centralized resource configuration, and real-time monitoring of training workflows through traces and metrics.\n\nSource: [dashboard/src/layouts/AppLayout.tsx:1-50](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/layouts/AppLayout.tsx)\n\n## High-Level Architecture Components\n\nThe Agent Lightning system comprises the following core entities:\n\n| Component | Description | Key Attributes |\n|-----------|-------------|----------------|\n| **Resources** | Configuration templates for prompts, models, and sampling parameters | `resources_id`, `version`, `resources` (dict with PromptTemplate/LLM) |\n| **Workers** | Runner processes that execute training rollouts | `worker_id`, `status`, `heartbeat_stats`, `current_rollout_id` |\n| **Rollouts** | Complete training episodes with multiple attempts | `rollout_id`, `status`, `mode`, `attempts` |\n| **Attempts** | Individual training attempts within a rollout | `attempt_id`, `status`, `metrics` |\n| **Spans** | Distributed tracing spans for observability | `trace_id`, `span_id`, `status`, `attributes`, `start_time`, `end_time` |\n\nSource: [dashboard/test-utils/python-server.py:1-300](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n\n## Frontend Dashboard Architecture\n\nThe dashboard is a React-based frontend built with **Mantine UI** components that communicates with the backend via REST APIs.\n\n### Navigation Structure\n\nThe application uses a sidebar navigation layout with the following sections:\n\n```mermaid\ngraph TD\n A[AppLayout] --> B[Navbar]\n A --> C[Main Content Area]\n B --> D[Rollouts]\n B --> E[Workers]\n B --> F[Resources]\n B --> G[Traces]\n B --> H[Settings]\n C --> I[Outlet Component]\n```\n\nSource: [dashboard/src/layouts/AppLayout.tsx:20-50](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/layouts/AppLayout.tsx)\n\n### Page Components\n\n| Page | File Path | Purpose |\n|------|-----------|---------|\n| Rollouts | `dashboard/src/pages/Rollouts.page.tsx` | Display and manage training rollouts with status filtering |\n| Workers | `dashboard/src/pages/Workers.page.tsx` | Monitor worker health and current assignments |\n| Resources | `dashboard/src/pages/Resources.page.tsx` | View and manage configuration resources |\n| Traces | `dashboard/src/components/TracesTable.component.tsx` | Analyze distributed tracing spans |\n\nSource: [dashboard/src/pages/Rollouts.page.tsx:1-80](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/pages/Rollouts.page.tsx)\n\n## Data Flow Architecture\n\n### Worker Heartbeat Flow\n\nWorkers periodically send heartbeat signals to indicate their operational state. The dashboard monitors these heartbeats to determine worker availability.\n\n```mermaid\nsequenceDiagram\n participant W as Worker\n participant S as Store\n participant D as Dashboard\n \n W->>S: Heartbeat (status, queue_depth, gpu_utilization)\n S->>S: Update last_heartbeat_time\n D->>S: Poll /workers endpoint\n S-->>D: Worker list with status\n```\n\nSource: [dashboard/test-utils/python-server.py:100-150](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n\n### Rollout Execution Flow\n\nTraining rollouts follow a multi-attempt execution model:\n\n```mermaid\ngraph LR\n A[Rollout Created] --> B[Attempt 1]\n B --> C{Success?}\n C -->|Yes| D[Rollout Complete]\n C -->|No| E[Attempt 2]\n E --> F{Success?}\n F -->|Yes| D\n F -->|No| G[Attempt N]\n G --> H[Max Attempts Reached]\n```\n\nSource: [dashboard/src/components/TracesTable.component.tsx:50-150](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/TracesTable.component.tsx)\n\n## Core Entity Schemas\n\n### Resources Entity\n\nResources define reusable configuration templates used by workers during training.\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `resources_id` | string | Unique identifier for the resource |\n| `version` | integer | Version number for tracking changes |\n| `create_time` | timestamp | Creation timestamp |\n| `update_time` | timestamp | Last modification timestamp |\n| `resources` | dict | Configuration dictionary (PromptTemplate, LLM configs) |\n\nSource: [dashboard/test-utils/python-server.py:50-100](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n\n### Workers Entity\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `worker_id` | string | Unique worker identifier |\n| `status` | enum | Current status: `idle`, `busy`, `offline` |\n| `heartbeat_stats` | dict | Metrics including `queue_depth`, `gpu_utilization` |\n| `last_heartbeat_time` | timestamp | Time of last heartbeat |\n| `current_rollout_id` | string | Currently assigned rollout (if busy) |\n| `current_attempt_id` | string | Currently executing attempt |\n\nSource: [dashboard/src/components/AppDrawer.component.tsx:1-60](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/AppDrawer.component.tsx)\n\n### Spans Entity (Distributed Tracing)\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `rollout_id` | string | Associated rollout |\n| `attempt_id` | string | Associated attempt |\n| `trace_id` | string | Distributed trace identifier |\n| `span_id` | string | Unique span identifier |\n| `parent_id` | string | Parent span ID for hierarchy |\n| `name` | string | Operation name (e.g., `classification_pipeline`) |\n| `status` | TraceStatus | Status with `status_code` (OK, ERROR) and description |\n| `attributes` | dict | Key-value metadata (model, batch_size, accuracy) |\n| `start_time` | timestamp | Span start time |\n| `end_time` | timestamp | Span end time |\n\nSource: [dashboard/src/components/TracesTable.component.tsx:50-120](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/TracesTable.component.tsx)\n\n## Component Architecture (Frontend)\n\n### Table Components Pattern\n\nThe dashboard uses a consistent table component pattern across all pages:\n\n```mermaid\ngraph TD\n A[Page Component] --> B[Table Component]\n B --> C[Column Definitions]\n B --> D[Filtering Logic]\n B --> E[Pagination Controls]\n A --> F[useQuery Hook]\n F --> G[API Endpoints]\n```\n\n| Component | Props | Purpose |\n|-----------|-------|---------|\n| `RolloutTable` | `rollouts`, `totalRecords`, `statusFilters`, `onViewTraces` | Training rollout display |\n| `WorkersTable` | `workers`, `onShowDetails` | Worker monitoring |\n| `ResourcesTable` | `resourcesList`, `renderRowExpansion` | Resource configuration |\n| `TracesTable` | `spans`, `onShowSpanDetail` | Trace analysis |\n\nSource: [dashboard/src/components/WorkersTable.component.tsx:1-80](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/WorkersTable.component.tsx)\n\n### Drawer Container Pattern\n\nThe application uses an `AppDrawerContainer` for displaying detailed information:\n\n```mermaid\ngraph TD\n A[AppDrawerContainer] --> B[Redux State]\n B --> C{Content Type}\n C -->|worker-detail| D[WorkerDrawerTitle]\n C -->|rollout-detail| E[RolloutDrawer]\n C -->|span-detail| F[SpanDetailDrawer]\n D --> G[ConnectionIndicator]\n G --> H[baseUrl, status, isRefreshing]\n```\n\nSource: [dashboard/src/components/AppDrawer.component.tsx:60-120](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/AppDrawer.component.tsx)\n\n## State Management\n\nThe frontend uses Redux for state management with the following key selectors:\n\n| Selector | Purpose |\n|----------|---------|\n| `selectConfig` | Application configuration (baseUrl, autoRefreshMs) |\n| `selectDrawerIsOpen` | Drawer visibility state |\n| `selectDrawerContent` | Current drawer content type and data |\n| `selectConnectionState` | Backend connection status |\n\nSource: [dashboard/src/layouts/AppLayout.tsx:50-80](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/layouts/AppLayout.tsx)\n\n## Connection Management\n\nThe dashboard includes a `ConnectionIndicator` component that displays the connection status to the backend:\n\n| Status | Description |\n|--------|-------------|\n| `connected` | Successfully connected to backend |\n| `disconnected` | Cannot reach backend |\n| `refreshing` | Actively reconnecting |\n\nSource: [dashboard/src/layouts/AppLayout.tsx:40-45](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/layouts/AppLayout.tsx)\n\n## Training Workflow Integration\n\n### Status Lifecycle\n\nRollouts and attempts follow a defined status lifecycle:\n\n| Status | Description |\n|--------|-------------|\n| `pending` | Initial state, not yet started |\n| `running` | Currently executing |\n| `succeeded` | Completed successfully |\n| `failed` | Execution failed |\n| `cancelled` | Manually cancelled |\n\n### Mode Types\n\n| Mode | Description |\n|------|-------------|\n| `train` | Training mode with gradient updates |\n| `eval` | Evaluation mode without updates |\n| `inference` | Production inference mode |\n\nSource: [dashboard/src/pages/Rollouts.page.tsx:30-60](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/pages/Rollouts.page.tsx)\n\n## Observability Architecture\n\n### Trace Hierarchy\n\nTraces are organized in a hierarchical structure:\n\n```\nTrace\n└── Span (root)\n ├── Span (child - preprocess)\n ├── Span (child - classifier)\n └── Span (child - formatter)\n```\n\nEach span captures:\n- Execution timing (`start_time`, `end_time`, `duration`)\n- Status and error information\n- Custom attributes (model, batch_size, accuracy)\n- Resource metadata (service name)\n\nSource: [dashboard/test-utils/python-server.py:200-300](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n\n### Attribute Keys\n\nCommon span attributes include:\n\n| Attribute | Example Value | Description |\n|-----------|---------------|-------------|\n| `type` | `classification` | Operation type |\n| `model` | `bert-classifier` | Model used |\n| `batch_size` | `10` | Processing batch size |\n| `accuracy` | `0.95` | Achieved accuracy |\n| `timeout` | `true` | Whether operation timed out |\n| `retry` | `true` | Whether this was a retry attempt |\n\nSource: [dashboard/src/components/TracesTable.component.tsx:30-50](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/TracesTable.component.tsx)\n\n## Resource Configuration Templates\n\nResources support multiple template engines:\n\n| Engine | Syntax | Example |\n|--------|--------|---------|\n| `f-string` | `{variable}` | `\"Classify: {ticket}\"` |\n| `jinja` | `{{ variable }}` or `{% for %}` | `\"{% for r in results %}{{ r }}{% endfor %}\"` |\n\nSource: [dashboard/test-utils/python-server.py:50-90](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n\n## Summary\n\nThe Agent Lightning system architecture provides:\n\n1. **Distributed Training** - Multiple workers executing rollouts in parallel\n2. **Centralized Configuration** - Versioned resource templates for prompts and models\n3. **Real-time Monitoring** - Worker heartbeat tracking and status dashboards\n4. **Full Observability** - Distributed tracing with hierarchical spans\n5. **State Persistence** - Store-based architecture for maintaining system state\n\nThe architecture is designed for horizontal scalability, allowing additional workers to be added to increase training throughput while maintaining centralized configuration management and monitoring through the dashboard frontend.\n\n---\n\n\n\n## Core Abstractions and Data Models\n\n### Related Pages\n\nRelated topics: [System Architecture](#architecture), [Trainer Component](#trainer)\n\n
\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [agentlightning/types/core.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n- [agentlightning/types/tracer.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/tracer.py)\n- [agentlightning/types/resources.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/resources.py)\n- [agentlightning/emitter/annotation.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/emitter/annotation.py)\n- [agentlightning/tracer/weave.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/tracer/weave.py)\n- [dashboard/test-utils/python-server.py](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n
\n\n# Core Abstractions and Data Models\n\nThe Agent Lightning framework relies on a set of foundational abstractions and data models that enable the coordination between runners, tracers, the LightningStore, and training algorithms. These core types are defined in `agentlightning/types/` and serve as the canonical data structures used throughout the system for representing tasks, rollouts, attempts, traces, and resources.\n\n## Architecture Overview\n\nAgent Lightning operates through a continuous execution loop where multiple components interact. The core abstractions facilitate:\n\n1. **Trace Emission** - Runners and tracers emit spans during execution\n2. **State Synchronization** - `LightningStore` maintains synchronized state\n3. **Algorithm Consumption** - Training algorithms in `agentlightning/algorithm/` consume traces to improve agent behavior\n\n```mermaid\ngraph TD\n A[Runners] -->|emit spans| B[Tracers]\n B --> C[LightningStore]\n C --> D[Algorithms]\n D -->|improve behavior| A\n C --> E[Dashboard]\n F[Resources] -->|configure| A\n```\n\nSource: [CLAUDE.md](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n\n## Task and Rollout Models\n\n### Task Representation\n\nThe `Task` and related classes define the fundamental unit of work in Agent Lightning. Tasks represent the objectives that agents attempt to accomplish during training and evaluation.\n\n| Class | Purpose |\n|-------|---------|\n| `Task` | Core task definition containing input and configuration |\n| `TaskInput` | Input data passed to a task |\n| `TaskIfAny` | Conditional task input supporting optional parameters |\n| `Dataset` | Collection of tasks for batch processing |\n\nSource: [agentlightning/types/core.py:1-50](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n\n### Rollout Lifecycle\n\nRollouts represent complete execution attempts of a task. The rollout model captures the entire lifecycle from enqueue to completion.\n\n```mermaid\nstateDiagram-v2\n [*] --> Enqueued: EnqueueRolloutRequest\n Enqueued --> InProgress: Runner picks up\n InProgress --> Attempted: First attempt completes\n Attempted --> InProgress: Retry triggered\n InProgress --> [*]: Final attempt\n Attempted --> [*]: Success/Failure\n```\n\n| Class | Description |\n|-------|-------------|\n| `Rollout` | Represents a single task execution instance |\n| `RolloutConfig` | Configuration for rollout execution |\n| `RolloutMode` | Execution mode (training, evaluation, etc.) |\n| `RolloutStatus` | Current state of the rollout |\n\nSource: [agentlightning/types/core.py:50-100](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n\n### Attempt Model\n\nAttempts represent individual tries within a rollout, enabling retry mechanisms and granular progress tracking.\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `attempt_id` | `str` | Unique identifier for the attempt |\n| `rollout_id` | `str` | Parent rollout identifier |\n| `status` | `AttemptStatus` | Current attempt status |\n| `sequence_id` | `int` | Order within the rollout |\n\nSource: [agentlightning/types/core.py:100-150](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n\n### AttemptedRollout\n\nThe `AttemptedRollout` class aggregates results from all attempts within a rollout:\n\n```python\nclass AttemptedRollout(BaseModel):\n rollout: Rollout\n attempts: List[Attempt]\n # Aggregated metrics and results\n```\n\nSource: [agentlightning/types/core.py:150-180](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n\n## Tracing Abstractions\n\n### OpenTelemetry Integration\n\nAgent Lightning uses OpenTelemetry for distributed tracing. The tracer types provide serialization and interoperability with the broader observability ecosystem.\n\n| Class | Purpose |\n|-------|---------|\n| `Span` | Single unit of work in a trace |\n| `SpanCoreFields` | Core fields shared across span implementations |\n| `OtelResource` | Serializable OpenTelemetry resource representation |\n| `TraceStatus` | Span completion status with error information |\n\nSource: [agentlightning/types/tracer.py:1-80](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/tracer.py)\n\n### Span Structure\n\nSpans form the atomic tracing unit, capturing timing, status, attributes, and relationships:\n\n```mermaid\ngraph LR\n subgraph Span\n A[name] --> B[status]\n B --> C[attributes]\n C --> D[start_time/end_time]\n D --> E[parent_id/span_id]\n E --> F[resource]\n end\n```\n\n| Attribute | Description |\n|-----------|-------------|\n| `name` | Human-readable span identifier |\n| `status` | `TraceStatus` with status_code and optional description |\n| `attributes` | Key-value metadata dictionary |\n| `parent_id` | Reference to parent span (None for root) |\n| `resource` | `OtelResource` containing service metadata |\n\nSource: [agentlightning/types/tracer.py:80-120](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/tracer.py)\n\n### OtelResource Model\n\nThe `OtelResource` class provides a serializable representation of OpenTelemetry resources:\n\n```python\nclass OtelResource(BaseModel):\n attributes: Attributes\n schema_url: str\n```\n\nThis model avoids confusion with the application's `Resource` class and enables span serialization for store persistence.\n\nSource: [agentlightning/types/tracer.py:120-150](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/tracer.py)\n\n### Span Creation Patterns\n\n#### SpanCoreFields for Lightweight Creation\n\nFor span creators that don't require the full span model, `SpanCoreFields` provides a minimal interface:\n\n```python\nclass SpanCoreFields(BaseModel):\n name: str\n status: TraceStatus\n attributes: Attributes\n start_time: Optional[float]\n end_time: Optional[float]\n```\n\nSource: [agentlightning/types/tracer.py:150-180](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/tracer.py)\n\n#### Weave Tracer Span Creation\n\nThe Weave tracer implementation demonstrates proper span construction with resource attributes:\n\n```python\nresource=OtelResource(\n attributes={\n LightningResourceAttributes.ROLLOUT_ID.value: rollout_id,\n LightningResourceAttributes.ATTEMPT_ID.value: attempt_id,\n LightningResourceAttributes.SPAN_SEQUENCE_ID.value: sequence_id,\n LightningResourceAttributes.TRACER_NAME.value: \"weave\",\n },\n schema_url=\"\",\n)\n```\n\nSource: [agentlightning/tracer/weave.py:1-50](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/tracer/weave.py)\n\n## Resource Management\n\n### ResourcesUpdate Model\n\nResources define configurable components that can be versioned and updated:\n\n```python\nclass ResourcesUpdate(BaseModel):\n resources_id: str\n version: int\n create_time: float\n update_time: float\n resources: Dict[str, Any]\n```\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `resources_id` | `str` | Unique identifier for the resource set |\n| `version` | `int` | Version number for optimistic concurrency |\n| `create_time` | `float` | Unix timestamp of creation |\n| `update_time` | `float` | Unix timestamp of last update |\n| `resources` | `Dict[str, Any]` | Arbitrary resource configuration |\n\nSource: [dashboard/test-utils/python-server.py:1-80](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n\n### Resource Types\n\nResources support flexible configuration through templates and model definitions:\n\n| Resource Type | Description |\n|---------------|-------------|\n| `PromptTemplate` | Templated prompts with jinja2 or f-string engines |\n| `LLM` | Language model configuration with endpoint and sampling parameters |\n| Custom `Dict[str, Any]` | Arbitrary configuration dictionaries |\n\nSource: [dashboard/test-utils/python-server.py:80-150](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n\n## Worker Abstraction\n\nWorkers represent execution agents that process rollouts:\n\n```mermaid\nclassDiagram\n class Worker {\n +worker_id: str\n +status: WorkerStatus\n +heartbeat_stats: Dict\n +last_heartbeat_time: float\n +current_rollout_id: Optional[str]\n +current_attempt_id: Optional[str]\n }\n```\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `worker_id` | `str` | Unique worker identifier |\n| `status` | `WorkerStatus` | Current status (busy, idle, etc.) |\n| `heartbeat_stats` | `Dict` | Runtime metrics (queue_depth, gpu_utilization) |\n| `last_heartbeat_time` | `float` | Last check-in timestamp |\n| `current_rollout_id` | `Optional[str]` | Currently executing rollout |\n\nSource: [agentlightning/types/core.py:180-220](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n\n### Worker Status States\n\n```mermaid\nstateDiagram-v2\n [*] --> Idle: Startup\n Idle --> Busy: Dequeue rollout\n Busy --> Idle: Complete\n Busy --> Busy: Heartbeat\n Idle --> [*]: Shutdown\n Busy --> [*]: Shutdown\n```\n\nSource: [dashboard/test-utils/python-server.py:150-200](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n\n## Filtering and Pagination\n\n### Query Models\n\nThe store supports filtered and paginated queries for efficient data access:\n\n| Class | Purpose |\n|-------|---------|\n| `FilterOptions` | Criteria for filtering results |\n| `FilterField` | Individual filter condition |\n| `SortOptions` | Sorting configuration |\n| `PaginatedResult` | Paginated response wrapper |\n\nSource: [agentlightning/types/core.py:220-260](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n\n## Operation Context\n\nThe `@operation` decorator provides a simplified span creation interface for user code:\n\n```python\n@operation(name=\"my_operation\")\nasync def my_function():\n # Automatically creates and manages a span\n pass\n```\n\n### OperationContext Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `propagate` | `bool` | Whether spans should use active span processor |\n| `name` | `Optional[str]` | Alias populating `OPERATION_NAME` attribute |\n\nThe decorator supports two usage patterns:\n1. As a bare decorator: `@operation`\n2. As a context manager factory: `with operation(name=\"custom\"):`\n\nSource: [agentlightning/emitter/annotation.py:1-60](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/emitter/annotation.py)\n\n## Data Flow Summary\n\n```mermaid\ngraph TD\n subgraph Input\n A[Dataset] --> B[Task]\n B --> C[EnqueueRolloutRequest]\n end\n \n subgraph Execution\n C --> D[Runner]\n D --> E[Worker]\n E --> F[Attempt]\n F --> G[Span]\n end\n \n subgraph Storage\n G --> H[LightningStore]\n H --> I[PaginatedResult]\n end\n \n subgraph Training\n H --> J[Algorithm]\n J --> K[Improved Policy]\n end\n```\n\n## Key Type Exports\n\nThe `agentlightning/types/core.py` module exports the following public API:\n\n```python\n__all__ = [\n \"Triplet\",\n \"RolloutLegacy\",\n \"Task\",\n \"TaskInput\",\n \"TaskIfAny\",\n \"RolloutRawResultLegacy\",\n \"RolloutRawResult\",\n \"RolloutMode\",\n \"GenericResponse\",\n \"ParallelWorkerBase\",\n \"Dataset\",\n \"AttemptStatus\",\n \"RolloutStatus\",\n \"RolloutConfig\",\n \"Rollout\",\n \"Attempt\",\n \"AttemptedRollout\",\n \"EnqueueRolloutRequest\",\n \"Hook\",\n \"Worker\",\n \"WorkerStatus\",\n \"PaginatedResult\",\n \"FilterOptions\",\n \"SortOptions\",\n \"FilterField\",\n]\n```\n\nSource: [agentlightning/types/core.py:40-60](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n\n## Usage Patterns\n\n### Creating a Rollout Request\n\n```python\nrequest = EnqueueRolloutRequest(\n task_id=\"task-001\",\n config=RolloutConfig(mode=RolloutMode.TRAINING),\n priority=1\n)\n```\n\n### Querying with Filters\n\n```python\nfilters = FilterOptions(\n fields=[FilterField(name=\"status\", operator=\"eq\", value=\"completed\")],\n sort=SortOptions(field=\"create_time\", direction=\"desc\"),\n offset=0,\n limit=50\n)\n```\n\nSource: [agentlightning/types/core.py:260-300](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n\n---\n\n\n\n## Tutorial: Train Your First Agent\n\n### Related Pages\n\nRelated topics: [Tutorial: Writing Agents](#write-agents), [Algorithm Zoo](#algorithm-zoo)\n\n
\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [examples/apo/README.md](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/README.md)\n- [examples/apo/apo_debug.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_debug.py)\n- [examples/apo/room_selector.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/room_selector.py)\n- [CLAUDE.md](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n- [agentlightning/types/tracer.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/tracer.py)\n- [examples/minimal/README.md](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/README.md)\n\n**Note:** The file `docs/how-to/train-first-agent.md` referenced in the specification was not present in the retrieved context. The tutorial content below is synthesized from available APO example documentation and source code.\n\n
\n\n# Tutorial: Train Your First Agent\n\n## Overview\n\nThis tutorial guides you through training your first AI agent using Agent Lightning's reinforcement learning framework. You will learn how to set up a training pipeline, define prompts and resources, create a dataset, and run the APO (Agent Prompt Optimization) algorithm to improve your agent's behavior through feedback-driven learning.\n\nAgent Lightning provides a complete training loop where runners and tracers emit spans, `LightningStore` keeps them synchronized, and algorithms consume those traces to improve behavior. Source: [CLAUDE.md](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n\n## Prerequisites\n\nBefore starting this tutorial, ensure you have:\n\n- Python 3.10+ installed\n- Agent Lightning installed following the [installation guide](../../docs/tutorials/installation.md)\n- An OpenAI-compatible API service available\n- APO extra dependencies installed\n\n## Architecture Overview\n\nAgent Lightning trains agents through a continuous feedback loop:\n\n```mermaid\ngraph TD\n A[Runner - Executes Agent] --> B[Tracer - Emits Spans]\n B --> C[LightningStore - Synchronizes Data]\n C --> D[Algorithm - Consumes Traces]\n D --> E[Improved Agent Behavior]\n E --> A\n \n F[Dataset - Training Data] --> D\n G[Resources - Prompts/Models] --> A\n```\n\nSource: [CLAUDE.md](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n\n## Step 1: Create Your Agent\n\nBegin by defining a simple room booking agent that uses function calling. The agent receives a user request and selects an appropriate room from available options.\n\n```python\n# examples/apo/room_selector.py\n\nfrom agentlightning import Runner, DataProto\nfrom typing import Any\nimport json\n\nclass RoomSelector(Runner):\n \"\"\"Room booking agent using function calling.\"\"\"\n\n def run(self, task: str, context: dict | None = None) -> DataProto:\n # Define available rooms\n rooms = [\n {\"id\": \"R001\", \"name\": \"Conference A\", \"capacity\": 10},\n {\"id\": \"R002\", \"name\": \"Meeting Room B\", \"capacity\": 4},\n {\"id\": \"R003\", \"name\": \"Board Room\", \"capacity\": 20},\n ]\n \n # Mock LLM response selecting a room\n selected_room = rooms[1] # Default to Meeting Room B\n \n return DataProto(\n data={\n \"selected_room\": selected_room[\"name\"],\n \"room_id\": selected_room[\"id\"],\n },\n raw_response=json.dumps(selected_room),\n )\n```\n\nSource: [examples/apo/room_selector.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/room_selector.py)\n\n### Supported Agent Components\n\n| Component | Description | Usage |\n|-----------|-------------|-------|\n| `Runner` | Base class for agent execution | Extend to define custom agent logic |\n| `Trainer` | Training orchestration | Manages training loop and workers |\n| `LightningStore` | Data synchronization | Stores traces and spans |\n| `OtelTracer` | OpenTelemetry span emission | Records execution traces |\n\nSource: [examples/apo/apo_debug.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_debug.py)\n\n## Step 2: Prepare Your Dataset\n\nCreate a training dataset with room booking scenarios. Each task should include the user request and expected room selection.\n\n```python\n# examples/apo/room_selector_apo.py\n\nfrom datasets import load_dataset\n\ndef create_room_dataset():\n \"\"\"Create dataset for room booking tasks.\"\"\"\n \n # Example tasks for room booking\n tasks = [\n {\n \"task\": \"I need to schedule a meeting for 3 people tomorrow at 2 PM\",\n \"expected_room\": \"Meeting Room B\",\n },\n {\n \"task\": \"We are hosting a team event for 15 team members\",\n \"expected_room\": \"Board Room\",\n },\n {\n \"task\": \"Quick 1-on-1 sync needed this afternoon\",\n \"expected_room\": \"Meeting Room B\",\n },\n ]\n \n return tasks\n```\n\nSource: [examples/apo/room_selector_apo.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/room_selector_apo.py)\n\n## Step 3: Define Training Resources\n\nResources define the prompts and model configurations used by your agent during training. You can tune any resource—typically prompt templates—using reinforcement learning.\n\n```python\nfrom agentlightning.prompts import PromptTemplate\nfrom agentlightning.models import LLM\n\n# Define a tunable prompt template\nmain_prompt = PromptTemplate(\n template=\"\"\"You are a helpful assistant that helps users book meeting rooms.\n \n Available rooms:\n - Conference A: capacity 10\n - Meeting Room B: capacity 4\n - Board Room: capacity 20\n \n User request: {user_request}\n \n Select the most appropriate room and explain your choice.\"\"\",\n engine=\"f-string\",\n)\n```\n\nSource: [examples/apo/apo_debug.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_debug.py)\n\n### Resource Types\n\n| Type | Description | Tunable |\n|------|-------------|---------|\n| `PromptTemplate` | Text templates with variable substitution | Yes |\n| `LLM` | Model configuration (endpoint, sampling params) | No |\n| `SystemPrompt` | System-level instructions | Yes |\n| `SamplingParameters` | Temperature, top_p, max_tokens | No |\n\nSource: [examples/apo/README.md](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/README.md)\n\n## Step 4: Configure the Trainer\n\nThe `Trainer` class orchestrates the training loop. It manages workers, coordinates with the LightningStore, and applies the optimization algorithm.\n\n```python\nfrom agentlightning import Trainer\n\n# Initialize trainer with one worker\ntrainer = Trainer(\n n_workers=1,\n # Resources to tune - only these will be optimized\n initial_resources={\n \"main_prompt\": main_prompt,\n },\n)\n\n# Configure the APO algorithm\ntrainer.configure(\n algorithm=\"APO\",\n lr=1e-3,\n epochs=10,\n)\n```\n\nSource: [examples/apo/apo_debug.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_debug.py)\n\n### Trainer Configuration Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `n_workers` | int | 1 | Number of parallel training workers |\n| `initial_resources` | dict | Required | Resources to optimize |\n| `algorithm` | str | Required | Optimization algorithm name |\n| `lr` | float | 1e-3 | Learning rate |\n| `epochs` | int | 10 | Number of training epochs |\n\nSource: [examples/apo/apo_debug.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_debug.py)\n\n## Step 5: Implement Reward Function\n\nThe reward function evaluates agent outputs and provides feedback signals for reinforcement learning.\n\n```python\nfrom typing import Any\n\ndef room_booking_reward(output: Any, expected: dict) -> float:\n \"\"\"\n Calculate reward based on room selection accuracy.\n \n Args:\n output: Agent's room selection\n expected: Expected room from dataset\n \n Returns:\n float: Reward score between 0.0 and 1.0\n \"\"\"\n if not output or not output.data:\n return 0.0\n \n selected_room = output.data.get(\"selected_room\", \"\")\n expected_room = expected.get(\"expected_room\", \"\")\n \n # Exact match gets full reward\n if selected_room == expected_room:\n return 1.0\n \n # Partial match gets partial reward\n if expected_room.lower() in selected_room.lower():\n return 0.5\n \n return 0.0\n```\n\nSource: [examples/apo/room_selector_apo.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/room_selector_apo.py)\n\n## Step 6: Run the Training Loop\n\nExecute the training with your runner, dataset, and reward function.\n\n```python\nimport asyncio\nfrom agentlightning import setup_logging\n\nasync def train_room_selector():\n setup_logging()\n \n # Initialize agent and trainer\n agent = RoomSelector()\n dataset = create_room_dataset()\n \n trainer = Trainer(\n n_workers=1,\n initial_resources={\"main_prompt\": main_prompt},\n )\n \n # Run training\n results = await trainer.train(\n runner=agent,\n dataset=dataset,\n reward_fn=room_booking_reward,\n max_iterations=100,\n )\n \n print(f\"Training completed: {results}\")\n\nif __name__ == \"__main__\":\n asyncio.run(train_room_selector())\n```\n\nSource: [examples/apo/apo_debug.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_debug.py)\n\n## Understanding the Training Flow\n\n```mermaid\nsequenceDiagram\n participant User as User Code\n participant Trainer as Trainer\n participant Runner as RoomSelector\n participant Store as LightningStore\n participant Algo as APO Algorithm\n \n User->>Trainer: train(runner, dataset, reward_fn)\n Trainer->>Runner: execute_task(task)\n Runner->>Runner: select_room()\n Runner-->>Trainer: output\n Trainer->>Store: record_span(rollout_id, attempt_id)\n Trainer->>Trainer: calculate_reward(output, expected)\n Trainer->>Algo: optimize_step(rewards, traces)\n Algo-->>Trainer: updated_resources\n Trainer->>Runner: update_resources()\n Note over Trainer,Algo: Repeat for max_iterations\n```\n\n## Debugging Your Training\n\nAgent Lightning provides multiple debugging approaches:\n\n### Approach 1: Runner Mode\n\nDirect execution without training to verify agent logic:\n\n```bash\npython apo_debug.py --mode runner\n```\n\nSource: [examples/apo/apo_debug.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_debug.py)\n\n### Approach 2: Hook Mode\n\nDebug with tracing hooks enabled:\n\n```bash\npython apo_debug.py --mode hook\n```\n\n### Approach 3: Trainer Mode\n\nFull training debug with detailed logging:\n\n```bash\npython apo_debug.py --mode trainer\n```\n\n## Viewing Training Traces\n\nDuring and after training, spans are recorded to the LightningStore. View them in the dashboard:\n\n```mermaid\ngraph LR\n A[Training Run] --> B[Spans Emitted]\n B --> C[LightningStore]\n C --> D[Dashboard]\n D --> E[Trace Visualization]\n D --> F[Span Details]\n```\n\nThe dashboard displays:\n\n| View | Description |\n|------|-------------|\n| Rollouts | Complete training iterations |\n| Spans | Individual function calls and operations |\n| Resources | Tunable prompt templates |\n| Metrics | Reward scores and training statistics |\n\nSource: [examples/minimal/README.md](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/README.md)\n\n## Common Issues and Solutions\n\n### Issue: Tracer Conflicts\n\nRunning multiple modes consecutively in one process may cause tracer conflicts.\n\n**Solution:** Run each mode in a separate process or ensure proper tracer cleanup between runs.\n\nSource: [examples/apo/apo_debug.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_debug.py)\n\n### Issue: Missing Dependencies\n\nAPO requires additional dependencies not in the core installation.\n\n**Solution:** Install with extras:\n```bash\npip install agentlightning[apo]\n```\n\nSource: [examples/apo/README.md](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/README.md)\n\n## Next Steps\n\nAfter completing this tutorial:\n\n1. **Advanced Algorithms**: Explore custom algorithms in `apo_custom_algorithm.py`\n2. **Integration**: Learn Agent-OS integration for policy-aware training\n3. **Dashboard**: Use the dashboard to visualize training progress\n4. **Production**: Scale training with multiple workers and distributed execution\n\n## Summary\n\nThis tutorial covered the essential steps to train your first agent with Agent Lightning:\n\n- Define a `Runner` implementing your agent logic\n- Prepare a dataset with tasks and expected outputs\n- Configure `PromptTemplate` resources for tuning\n- Implement a reward function for RL feedback\n- Use `Trainer` to orchestrate the training loop\n- Debug with multiple modes and visualize traces in the dashboard\n\nThe training loop continuously improves your agent by optimizing prompt resources based on reward signals, enabling agents to learn from feedback without manual prompt engineering.\n\n---\n\n\n\n## Tutorial: Writing Agents\n\n### Related Pages\n\nRelated topics: [Tutorial: Train Your First Agent](#train-first-agent), [Runner Component](#runner)\n\n
\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [CLAUDE.md](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n- [AGENTS.md](https://github.com/microsoft/agent-lightning/blob/main/AGENTS.md)\n- [examples/minimal/README.md](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/README.md)\n- [examples/minimal/write_traces.py](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/write_traces.py)\n- [dashboard/test-utils/python-server.py](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n- [dashboard/src/components/AppDrawer.component.tsx](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/AppDrawer.component.tsx)\n- [agentlightning/store/](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/) (store module referenced via CLAUDE.md)\n
\n\n# Tutorial: Writing Agents\n\nThis tutorial provides a comprehensive guide to building AI agents using the Agent Lightning framework. It covers the core concepts, architecture, and practical implementation patterns for creating agents that can be trained with reinforcement learning.\n\n## Overview\n\nAgent Lightning is a framework designed to train AI agents using reinforcement learning. The framework provides a complete execution stack including tracing, storage, and algorithm components that work together in a continuous loop. Source: [CLAUDE.md:1-5](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n\nAgents in this framework are built using the `LightningStore` architecture, which synchronizes data between runners, tracers, and algorithms. The tracers emit spans that capture the agent's execution behavior, and these spans are consumed by algorithms to improve the agent's performance over time. Source: [AGENTS.md:1-5](https://github.com/microsoft/agent-lightning/blob/main/AGENTS.md)\n\n## Architecture Overview\n\nThe Agent Lightning framework follows a continuous loop architecture where multiple components interact to enable training of AI agents.\n\n```mermaid\ngraph TD\n A[Agent / Runner] -->|Emits Spans| B[Tracer]\n B -->|Traces| C[LightningStore]\n C -->|Synchronized Data| D[Algorithms]\n D -->|Training Signals| A\n E[Dashboard] -->|Inspect & Debug| C\n```\n\n### Core Components\n\n| Component | Purpose | Location |\n|-----------|---------|----------|\n| `LightningStore` | Central data store for traces and rollouts | `agentlightning/store/` |\n| `OtelTracer` | OpenTelemetry-based span emission | Via `OtelTracer` class |\n| `AgentOpsTracer` | AgentOps integration for tracing | Via `AgentOpsTracer` class |\n| `Span` | Individual trace unit | Data model |\n| `emit_reward` | Reward signal emission | API function |\n\nSource: [examples/minimal/write_traces.py:1-40](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/write_traces.py)\n\n## Writing Your First Agent\n\n### Basic Agent Structure\n\nAn agent in Agent Lightning is built around the tracing and store infrastructure. The minimal component showcase in `examples/minimal/` demonstrates how individual building blocks behave in isolation. Source: [examples/minimal/README.md:1-10](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/README.md)\n\n### Setting Up the Tracer\n\nThe framework supports two primary tracing mechanisms:\n\n1. **OtelTracer**: OpenTelemetry-based tracing that can forward spans to a remote store client\n2. **AgentOpsTracer**: AgentOps integration for agent operations tracking\n\n```python\nfrom agentlightning import OtelTracer, LightningStoreClient, setup_logging\n\n# Initialize logging\nsetup_logging()\n\n# Create tracer with optional remote store client\ntracer = OtelTracer(\n rollout_id=\"ro-001\",\n attempt_id=\"at-001\",\n store_client=None # Or LightningStoreClient(endpoint=\"...\")\n)\n```\n\nSource: [examples/minimal/write_traces.py:40-60](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/write_traces.py)\n\n### Opening Rollouts and Emitting Spans\n\nRollouts represent a single execution attempt of an agent, and attempts within rollouts allow for retry logic and tracking.\n\n```python\n# Open a new rollout\ntracer.open_rollout(rollout_id=\"ro-001\", user_id=\"user-123\")\n\n# Open an attempt within the rollout\ntracer.open_attempt(attempt_id=\"at-001\", sequence_id=1)\n\n# Emit spans during agent execution\ntracer.emit_span(\n name=\"tool_execution\",\n attributes={\n \"tool\": \"web_search\",\n \"query\": \"onboarding summary\"\n }\n)\n\n# Close attempt and rollout\ntracer.close_attempt()\ntracer.close_rollout()\n```\n\nSource: [examples/minimal/write_traces.py:60-85](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/write_traces.py)\n\n## Span Data Model\n\nSpans are the fundamental unit of tracing in Agent Lightning. Each span captures a discrete unit of work within an agent's execution.\n\n### Span Attributes\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `rollout_id` | string | Unique identifier for the rollout |\n| `attempt_id` | string | Unique identifier for the attempt |\n| `sequence_id` | integer | Order of the span within the attempt |\n| `trace_id` | string | Trace grouping identifier |\n| `span_id` | string | Unique span identifier |\n| `parent_id` | string | Parent span ID for hierarchy |\n| `name` | string | Human-readable span name |\n| `status` | TraceStatus | Execution status (OK, ERROR) |\n| `attributes` | dict | Key-value metadata |\n| `start_time` | datetime | Span start timestamp |\n| `end_time` | datetime | Span end timestamp |\n\nSource: [dashboard/test-utils/python-server.py:1-100](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n\n### Example Span Creation\n\n```python\nfrom agentlightning import Span, TraceStatus\nfrom datetime import datetime\n\nspan = Span(\n rollout_id=\"ro-story-001\",\n attempt_id=\"at-story-010\",\n sequence_id=3,\n trace_id=\"trace-001-main\",\n span_id=\"span-003-tool\",\n parent_id=\"span-001-root\",\n name=\"tool_execution\",\n status=TraceStatus(status_code=\"OK\", description=None),\n attributes={\"tool\": \"web_search\", \"query\": \"onboarding summary\"},\n events=[],\n links=[],\n start_time=datetime.now(),\n end_time=datetime.now(),\n context=None,\n parent=None,\n resource=OtelResource(attributes={\"service.name\": \"tool-service\"}, schema_url=\"\")\n)\n```\n\nSource: [dashboard/test-utils/python-server.py:100-130](https://github.com/microsoft/agent-lightning/blob/main/dashboard/test-utils/python-server.py)\n\n## Using Operations\n\nThe framework provides an `operation` decorator for recording synthetic operation spans with additional linking capabilities.\n\n```python\nfrom agentlightning.operation import operation\nfrom agentlightning.utils.otel import make_link_attributes, make_tag_attributes\n\n# Record an operation span\n@operation(name=\"classify_ticket\")\ndef classify_ticket(ticket: str):\n with make_link_attributes(linked_rollout_id=\"ro-001\", linked_attempt_id=\"at-001\"):\n # Operation execution\n result = llm.classify(ticket)\n \n # Tag the reward\n make_tag_attributes(tags={\"accuracy\": 0.95})\n emit_reward(reward=0.95, name=\"classification_accuracy\")\n \n return result\n```\n\nSource: [examples/minimal/write_traces.py:20-35](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/write_traces.py)\n\n## LightningStore Integration\n\nThe `LightningStore` keeps tracers and runners synchronized, serving as the central data repository.\n\n```python\nfrom agentlightning.store import InMemoryLightningStore\n\n# Use in-memory store for local development\nstore = InMemoryLightningStore()\n\n# Or connect to a remote store server\nstore = LightningStoreClient(endpoint=\"http://localhost:45993\")\n```\n\nSource: [examples/minimal/write_traces.py:25-35](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/write_traces.py)\n\n### Store Server CLI\n\nStart a LightningStore server with OTLP enabled:\n\n```bash\nagl store --port 45993 --log-level DEBUG\n```\n\nSource: [examples/minimal/write_traces.py:15-20](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/write_traces.py)\n\n## Workflow Execution Model\n\nAgents in Agent Lightning follow a structured execution model with rollouts, attempts, and spans.\n\n```mermaid\ngraph LR\n subgraph Rollout[Rollout: ro-001]\n subgraph Attempt1[Attempt: at-001]\n S1[Span: root]\n S2[Span: preprocess]\n S3[Span: classify]\n S1 --> S2\n S2 --> S3\n end\n subgraph Attempt2[Attempt: at-002]\n S4[Span: root]\n S5[Span: preprocess]\n S6[Span: classify]\n S4 --> S5\n S5 --> S6\n end\n end\n```\n\n### State Transitions\n\n| State | Description |\n|-------|-------------|\n| `pending` | Rollout/attempt created but not started |\n| `running` | Currently executing |\n| `completed` | Successfully finished |\n| `failed` | Execution failed |\n| `cancelled` | Manually cancelled |\n\nSource: [dashboard/src/components/RolloutTable.component.tsx:1-50](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/RolloutTable.component.tsx)\n\n## Reward Emission\n\nAgents emit reward signals that algorithms consume during training.\n\n```python\nfrom agentlightning import emit_reward\n\n# Emit a reward with metadata\nemit_reward(\n reward=0.85,\n name=\"task_success\",\n attributes={\n \"task_id\": \"classification\",\n \"accuracy\": 0.85,\n \"latency_ms\": 150\n }\n)\n```\n\n### Reward Span Attributes\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `reward.value` | float | Numeric reward value |\n| `reward.name` | string | Reward signal identifier |\n| `reward.attributes` | dict | Additional metadata |\n\n## Dashboard Integration\n\nThe Agent Lightning Dashboard provides real-time inspection of store data and debugging capabilities for running experiments. Source: [dashboard/README.md:1-10](https://github.com/microsoft/agent-lightning/blob/main/dashboard/README.md)\n\n### Drawer Components\n\nThe dashboard uses drawer components to display detailed information:\n\n```typescript\n// Worker detail drawer\nif (content.type === 'worker-detail') {\n const { worker } = content;\n const title = ;\n const body = ;\n return { title, body };\n}\n\n// Trace detail drawer\nif (content.type === 'trace-detail') {\n const { span } = content;\n const title = ;\n const body = ;\n return { title, body };\n}\n```\n\nSource: [dashboard/src/components/AppDrawer.component.tsx:1-50](https://github.com/microsoft/agent-lightning/blob/main/dashboard/src/components/AppDrawer.component.tsx)\n\n## Minimal Examples Reference\n\nThe `examples/minimal/` directory provides documented examples for each building block:\n\n| Component | File | Purpose |\n|-----------|------|---------|\n| LightningStore + OTLP | `write_traces.py` | Shows `OtelTracer` and `AgentOpsTracer` for rollouts and spans |\n| MultiMetrics | `write_metrics.py` | Console and Prometheus metrics backends |\n| LLM Proxying | `llm_proxy.py` | Request routing through `/rollout//attempt/` namespaces |\n| vLLM Lifecycle | `vllm_server.py` | Context manager for vLLM server lifecycle |\n\nSource: [examples/minimal/README.md:10-30](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/README.md)\n\n## Best Practices\n\n1. **Use descriptive span names**: Names like `tool_execution` and `classification_pipeline` make debugging easier in the dashboard.\n2. **Set appropriate parent IDs**: Maintain span hierarchy for better trace visualization.\n3. **Emit rewards consistently**: Use `emit_reward` after each task completion to enable algorithm training.\n4. **Handle failures explicitly**: Set appropriate `TraceStatus` codes and descriptions for failed spans.\n5. **Use operations for complex workflows**: The `@operation` decorator simplifies recording complex multi-step processes.\n\n## Next Steps\n\n- Explore the [API Reference](./api-reference.md) for detailed method signatures\n- Learn about [Training Algorithms](../how-to/training-algorithms.md) that consume traces\n- Set up the [Dashboard](../how-to/dashboard-setup.md) for real-time monitoring\n- Review [Examples](../examples/overview.md) for complete agent implementations\n\n---\n\n\n\n## Trainer Component\n\n### Related Pages\n\nRelated topics: [Runner Component](#runner), [LightningStore](#store), [Algorithm Zoo](#algorithm-zoo)\n\n
\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [agentlightning/trainer/trainer.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/trainer/trainer.py)\n- [agentlightning/trainer/registry.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/trainer/registry.py)\n- [agentlightning/trainer/init_utils.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/trainer/init_utils.py)\n- [examples/apo/apo_custom_algorithm_trainer.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_custom_algorithm_trainer.py)\n- [contrib/recipes/agentos/README.md](https://github.com/microsoft/agent-lightning/blob/main/contrib/recipes/agentos/README.md)\n- [examples/calc_x/legacy_calc_agent.py](https://github.com/microsoft/agent-lightning/blob/main/examples/calc_x/legacy_calc_agent.py)\n
\n\n# Trainer Component\n\nThe Trainer is the core orchestration component in Agent Lightning responsible for managing the reinforcement learning training loop. It coordinates runners, algorithms, and the LightningStore to execute agent training with scalable execution strategies.\n\n## Overview\n\nThe Trainer serves as the central control plane that:\n\n- Manages worker processes for parallel rollout execution\n- Coordinates between the agent runner and learning algorithm\n- Persists training traces to the LightningStore\n- Provides pluggable execution strategies for different deployment scenarios\n\nSource: [agentlightning/trainer/registry.py:1-6](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/trainer/registry.py)\n\n## Architecture\n\n### Component Interactions\n\n```mermaid\ngraph TD\n T[Trainer] --> R[Runner
Agent Execution]\n T --> A[Algorithm
Policy Update]\n T --> S[LightningStore
Trace Storage]\n T --> E[ExecutionStrategy]\n \n E --> SHM[SharedMemory
Local Workers]\n E --> CS[ClientServer
Remote Workers]\n \n R --> S\n A --> S\n```\n\n### Training Loop Flow\n\n```mermaid\nsequenceDiagram\n participant T as Trainer\n participant R as Runner\n participant S as LightningStore\n participant A as Algorithm\n \n T->>R: Initialize with config\n T->>A: Load algorithm\n T->>S: Connect store\n \n loop Training Steps\n T->>R: Execute rollouts\n R->>S: Emit spans\n T->>S: Retrieve traces\n T->>A: Process traces\n A->>T: Policy update\n end\n```\n\n## Core Configuration\n\n### Constructor Parameters\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `n_workers` | `int` | `1` | Number of parallel worker processes |\n| `algorithm` | `Algorithm \\| str` | `None` | Learning algorithm (name or instance) |\n| `runner` | `Runner \\| None` | `None` | Agent runner for execution |\n| `reward_fn` | `RewardFn \\| None` | `None` | Reward function for training |\n| `execution_strategy` | `str` | `\"shm\"` | Strategy: `\"shm\"`, `\"cs\"` |\n\nSource: [examples/apo/apo_custom_algorithm_trainer.py:35-37](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_custom_algorithm_trainer.py)\n\n### Execution Strategy Registry\n\nThe Trainer supports multiple execution strategies through a registry pattern:\n\n```python\nExecutionStrategyRegistry = {\n \"shm\": \"agentlightning.execution.shared_memory.SharedMemoryExecutionStrategy\",\n \"cs\": \"agentlightning.execution.client_server.ClientServerExecutionStrategy\",\n}\n```\n\nSource: [agentlightning/trainer/registry.py:1-6](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/trainer/registry.py)\n\n| Strategy | Description | Use Case |\n|----------|-------------|----------|\n| `shm` | Shared Memory - Local multi-process execution | Single-node GPU training |\n| `cs` | Client-Server - Remote worker communication | Distributed deployments |\n\n## Usage Patterns\n\n### Basic Training with GRPO Algorithm\n\n```python\nfrom agentlightning import Trainer\n\ntrainer = Trainer(\n runner=runner,\n reward_fn=reward_fn,\n algorithm=\"GRPO\"\n)\n\ntrainer.train()\n```\n\nSource: [contrib/recipes/agentos/README.md:40-47](https://github.com/microsoft/agent-lightning/blob/main/contrib/recipes/agentos/README.md)\n\n### Custom Algorithm Integration\n\nThe Trainer accepts custom algorithms decorated with the `@algo` decorator:\n\n```python\nfrom agentlightning import Trainer\nfrom agentlightning.algorithm import algo\nfrom agentlightning.store import LightningStore\n\n@algo\nasync def custom_algorithm(*, store: LightningStore):\n # Process traces from store\n return policy_update\n\ntrainer = Trainer(n_workers=1, algorithm=custom_algorithm)\ntrainer.fit(rollout_fn)\n```\n\nSource: [examples/apo/apo_custom_algorithm_trainer.py:28-37](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_custom_algorithm_trainer.py)\n\n### Parallel Training with Multiple Workers\n\n```python\nfrom agentlightning import Trainer\n\ntrainer = Trainer(\n n_workers=4, # 4 parallel workers\n execution_strategy=\"shm\", # Shared memory for local execution\n algorithm=\"PPO\",\n runner=runner\n)\n\ntrainer.train()\n```\n\n## Integration with Agent-OS\n\nThe Trainer integrates with Agent-OS for policy-governed training:\n\n```python\nfrom agentlightning import Trainer\nfrom agentlightning.contrib.runner.agentos import AgentOSRunner\nfrom agentlightning.contrib.reward.agentos import PolicyReward\nfrom agent_os import KernelSpace\nfrom agent_os.policies import SQLPolicy\n\n# Create governed kernel\nkernel = KernelSpace(policy=SQLPolicy(deny=[\"DROP\", \"DELETE\"]))\n\n# Wrap in Agent-OS runner\nrunner = AgentOSRunner(kernel)\n\n# Train with policy-aware rewards\ntrainer = Trainer(\n runner=runner,\n reward_fn=PolicyReward(kernel),\n algorithm=\"GRPO\"\n)\n\ntrainer.train()\n```\n\nSource: [contrib/recipes/agentos/README.md:25-45](https://github.com/microsoft/agent-lightning/blob/main/contrib/recipes/agentos/README.md)\n\n## Workflow Phases\n\n| Phase | Description |\n|-------|-------------|\n| **Initialization** | Load algorithm, connect store, spawn workers |\n| **Rollout** | Execute agent episodes in parallel workers |\n| **Trace Collection** | Retrieve spans from LightningStore |\n| **Algorithm Update** | Process traces and update policy |\n| **Iteration** | Repeat rollout-collect-update cycle |\n\n## LightningStore Integration\n\nThe Trainer maintains bidirectional synchronization with LightningStore:\n\n- **Span Emission**: Workers emit execution traces during rollout\n- **Trace Retrieval**: Algorithm reads completed traces for learning\n- **Persistence**: Training state survives worker restarts\n\nSource: [CLAUDE.md:4-6](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n\n## Command-Line Interface\n\nThe Trainer can be invoked via the `agl` CLI:\n\n```bash\n# Start training\nagl store\npython my_training_script.py algo\npython my_training_script.py runner\n```\n\nOr programmatically:\n\n```bash\npython my_training_script.py\n```\n\nSource: [examples/apo/apo_custom_algorithm_trainer.py:12-20](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_custom_algorithm_trainer.py)\n\n## Extending the Trainer\n\n### Custom Execution Strategy\n\nAdd new strategies to the registry:\n\n```python\n# In agentlightning/trainer/registry.py\nExecutionStrategyRegistry[\"custom\"] = \"mymodule.CustomExecutionStrategy\"\n```\n\n### Custom Algorithm\n\nDecorate async functions with `@algo`:\n\n```python\nfrom agentlightning.algorithm import algo\n\n@algo\nasync def my_algorithm(*, store: LightningStore):\n traces = await store.traces.get_all()\n # Process traces\n return update\n```\n\n## Dependencies\n\n| Dependency | Purpose |\n|------------|---------|\n| `LightningStore` | Trace persistence and retrieval |\n| `Algorithm` | Policy learning logic |\n| `Runner` | Agent execution environment |\n| `ExecutionStrategy` | Worker orchestration |\n| `RewardFn` | Training signal computation |\n\n## See Also\n\n- [Agent Lightning Architecture](AGENTS.md) - System-wide architecture overview\n- [Algorithm Component](algorithm.md) - Learning algorithm details\n- [LightningStore](store.md) - Trace storage system\n- [Execution Strategies](execution.md) - Available execution modes\n\n---\n\n\n\n## Runner Component\n\n### Related Pages\n\nRelated topics: [Trainer Component](#trainer), [Tutorial: Writing Agents](#write-agents)\n\n
\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [agentlightning/runner/base.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/base.py)\n- [agentlightning/runner/agent.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/agent.py)\n- [agentlightning/runner/legacy.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/legacy.py)\n- [agentlightning/runner/__init__.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/__init__.py)\n- [agentlightning/types/core.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n- [agentlightning/trainer/trainer.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/trainer/trainer.py)\n
\n\n# Runner Component\n\nThe Runner component is the core execution engine in Agent Lightning responsible for managing agent lifecycle, task processing, and telemetry collection. Runners serve as the bridge between the high-level `Trainer` orchestration and the underlying `LitAgent` implementation, handling initialization, worker management, and graceful shutdown.\n\n## Overview\n\nRunners execute agents in a continuous loop where they poll the `LightningStore` for tasks, execute agent logic, and emit tracing spans for algorithm consumption. The Runner architecture supports both standard execution through `LitAgentRunner` and legacy compatibility through `LegacyAgentRunner`.\n\nSource: [agentlightning/runner/__init__.py:1-11](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/__init__.py)\n\n```python\nfrom .agent import LitAgentRunner\nfrom .base import Runner\nfrom .legacy import LegacyAgentRunner\n\n__all__ = [\n \"Runner\",\n \"LegacyAgentRunner\",\n \"LitAgentRunner\",\n]\n```\n\n## Architecture\n\n```mermaid\ngraph TD\n A[Trainer] --> B[Runner Fleet]\n B --> C[LitAgentRunner]\n B --> D[LegacyAgentRunner]\n C --> E[LitAgent]\n D --> F[AgentLightningClient]\n E --> G[LightningStore]\n F --> G\n E --> H[Tracer]\n H --> G\n```\n\n### Runner Hierarchy\n\n| Class | Purpose | Source |\n|-------|---------|--------|\n| `Runner` | Abstract base class defining the runner interface | [base.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/base.py) |\n| `LitAgentRunner` | Primary runner implementation for standard agent execution | [agent.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/agent.py) |\n| `LegacyAgentRunner` | Runner for backward compatibility with AgentOps integration | [legacy.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/legacy.py) |\n\n## Runner Base Class\n\nThe `Runner` class defines the core interface that all runner implementations must follow. It establishes the lifecycle methods and execution patterns.\n\nSource: [agentlightning/runner/base.py:1-20](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/base.py)\n\n### Lifecycle Methods\n\nThe runner lifecycle consists of four key phases:\n\n```mermaid\ngraph LR\n A[init] --> B[init_worker]\n B --> C[iter/step]\n C --> D[teardown_worker]\n D --> E[teardown]\n```\n\n| Method | Purpose | Must Implement |\n|--------|---------|----------------|\n| `init(agent, hooks)` | Initialize runner with agent and hooks | Yes |\n| `init_worker(worker_id, store)` | Per-worker initialization with store | Yes |\n| `teardown()` | Release resources from init() | Yes |\n| `teardown_worker(worker_id)` | Release per-worker resources | Yes |\n\n### Context Manager Pattern\n\nRunners support a context manager pattern for automatic resource management:\n\n```python\nwith runner.run_context(agent=agent, store=store, hooks=hooks) as runner:\n # Runner is initialized and ready\n await runner.iter()\n# Automatic teardown on exit\n```\n\nSource: [agentlightning/runner/base.py:52-86](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/base.py)\n\nThe `run_context` helper ensures proper cleanup even when exceptions occur:\n\n```python\ntry:\n self.init(agent=agent, hooks=hooks)\n _initialized = True\n self.init_worker(worker_id=0, store=store)\n _worker_initialized = True\n yield self\nfinally:\n try:\n if _worker_initialized:\n self.teardown_worker(worker_id=worker_id if worker_id is not None else 0)\n except Exception:\n logger.error(\"Error during runner worker teardown\", exc_info=True)\n\n try:\n if _initialized:\n self.teardown()\n except Exception:\n logger.error(\"Error during runner teardown\", exc_info=True)\n```\n\n### Execution Methods\n\n| Method | Description | Behavior |\n|--------|-------------|----------|\n| `iter(event)` | Run continuously until event or no tasks | Abstract - subclasses implement |\n| `step()` | Execute single unit of work | Abstract - subclasses implement |\n| `run()` | Legacy run method | Raises `RuntimeError` - use `iter()` or `step()` |\n\nSource: [agentlightning/runner/base.py:88-102](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/base.py)\n\n> **Warning**: The `run()` method raises `RuntimeError` because its behavior is undefined. Always use `iter()` or `step()` instead.\n\n## LitAgentRunner\n\n`LitAgentRunner` is the primary runner implementation that manages the agent-runner relationship, hook registration, and tracer integration.\n\nSource: [agentlightning/runner/agent.py:1-30](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/agent.py)\n\n### Initialization Flow\n\n```mermaid\nsequenceDiagram\n participant Trainer\n participant LitAgentRunner\n participant LitAgent\n participant Tracer\n participant LightningStore\n\n Trainer->>LitAgentRunner: init(agent, hooks)\n LitAgentRunner->>LitAgent: set_runner(self)\n LitAgentRunner->>Tracer: init()\n Trainer->>LitAgentRunner: init_worker(worker_id, store)\n LitAgentRunner->>Tracer: init_worker(worker_id, store)\n```\n\n### Key Properties\n\n| Property | Type | Description |\n|----------|------|-------------|\n| `agent` | `LitAgent[T_task]` | The agent instance (via `get_agent()`) |\n| `store` | `LightningStore` | The backing store (via `get_store()`) |\n| `worker_id` | `Optional[int]` | Unique worker identifier |\n| `tracer` | `Tracer` | Tracer for span emission |\n\nSource: [agentlightning/runner/agent.py:90-110](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/agent.py)\n\n### Accessor Methods\n\n```python\ndef get_agent(self) -> LitAgent[T_task]:\n \"\"\"Get the agent instance.\"\"\"\n if self._agent is None:\n raise ValueError(\"Agent not initialized. Call init() first.\")\n return self._agent\n\ndef get_store(self) -> LightningStore:\n \"\"\"Get the store instance.\"\"\"\n if self._store is None:\n raise ValueError(\"Store not initialized. Call init_worker() first.\")\n return self._store\n\ndef get_worker_id(self) -> str:\n \"\"\"Get the formatted worker ID string.\"\"\"\n return f\"Worker-{self.worker_id}\" if self.worker_id is not None else \"Worker-Unknown\"\n```\n\n### Logging Prefix\n\nThe `_log_prefix()` method generates consistent log prefixes for traceability:\n\n```python\ndef _log_prefix(self, rollout_id: Optional[str] = None) -> str:\n \"\"\"Generate a standardized log prefix for the current worker.\"\"\"\n # Returns format: \"[Worker-{id}] [{rollout_id}]\"\n```\n\n## LegacyAgentRunner\n\n`LegacyAgentRunner` provides backward compatibility for workflows using the AgentOps integration and `AgentLightningClient` communication pattern.\n\nSource: [agentlightning/runner/legacy.py:1-35](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/legacy.py)\n\n### Attributes\n\n| Attribute | Type | Description |\n|-----------|------|-------------|\n| `agent` | `LitAgent[Any]` | The agent instance |\n| `client` | `AgentLightningClient` | Server communication client |\n| `tracer` | `Tracer` | Tracer instance for span emission |\n| `worker_id` | `Optional[str]` | Worker identifier |\n| `max_tasks` | `Optional[int]` | Maximum tasks before stopping |\n\n### Architecture\n\n```mermaid\ngraph TD\n A[LegacyAgentRunner] --> B[LitAgent]\n A --> C[AgentLightningClient]\n A --> D[Tracer]\n C --> E[Server]\n D --> F[LightningStore]\n B --> F\n```\n\n## Hook System Integration\n\nRunners integrate with the hook system to provide extensibility at key lifecycle points:\n\nSource: [agentlightning/types/core.py:1-30](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n\n| Hook | Timing | Purpose |\n|------|--------|---------|\n| `on_trace_start` | Before tracer enters trace context | Logging, metric collection, resource setup |\n| `on_trace_end` | After rollout completes, before tracer exits | Logging, cleanup |\n| `on_rollout_start` | Before rollout attempt begins | Per-attempt initialization |\n| `on_rollout_end` | After rollout attempt completes | Result processing, cleanup |\n\nHooks are registered during initialization and called by the runner at appropriate points during execution.\n\n## Trainer Integration\n\nRunners are instantiated and managed by the `Trainer` class, which orchestrates the entire training loop:\n\nSource: [agentlightning/trainer/trainer.py:40-60](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/trainer/trainer.py)\n\n```python\nclass Trainer(TrainerLegacy):\n \"\"\"High-level orchestration layer that wires Algorithm <-> Runner <-> Store.\"\"\"\n \n # Runner fleet configuration\n n_runners: int # Number of agent runners to run in parallel\n max_rollouts: Optional[int] # Maximum rollouts per runner\n strategy: ExecutionStrategy # Process management strategy\n tracer: Tracer # Tracer instance for telemetry\n hooks: Sequence[Hook] # Lifecycle callbacks\n```\n\n### Training Configuration\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `n_runners` | `int` | Number of parallel agent runners |\n| `max_rollouts` | `Optional[int]` | Stop after N rollouts (None = unlimited) |\n| `strategy` | `ExecutionStrategy` | Spawning strategy (shared memory, client/server) |\n| `tracer` | `Tracer` | Tracer class or config for span collection |\n| `hooks` | `Sequence[Hook]` | Lifecycle callback instances |\n\n## Execution Flow\n\n```mermaid\ngraph TD\n A[Trainer.fit/dev] --> B[Spawn Runner Fleet]\n B --> C[For each Runner]\n C --> D[runner.run_context]\n D --> E[init + init_worker]\n E --> F[iter/event loop]\n F --> G{Tasks available?}\n G -->|Yes| H[Execute step]\n H --> I[Emit spans to Store]\n I --> F\n G -->|No| J[Exit loop]\n J --> K[teardown_worker]\n K --> L[teardown]\n```\n\n## Context Manager Usage\n\nFor debugging or standalone usage outside the Trainer stack:\n\n```python\nfrom agentlightning import LitAgentRunner, InMemoryLightningStore\n\n# Create store and agent\nstore = InMemoryLightningStore()\nagent = MyLitAgent()\n\n# Use context manager\nrunner = LitAgentRunner(tracer=AgentOpsTracer())\nwith runner.run_context(agent=agent, store=store) as runner:\n # Runner initialized and ready\n worker_id = runner.get_worker_id()\n print(f\"Running on {worker_id}\")\n \n # Run until complete\n await runner.iter()\n# Automatic cleanup\n```\n\nSource: [agentlightning/runner/base.py:88-113](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/runner/base.py)\n\n## Error Handling\n\nRunners implement robust error handling during teardown:\n\n| Phase | Error Behavior | Recovery |\n|-------|----------------|----------|\n| `teardown_worker` | Logged but doesn't propagate | Continue to `teardown` |\n| `teardown` | Logged but doesn't propagate | Context manager completes |\n\nThis ensures that multiple cleanup errors don't mask the original failure and that partial cleanup still occurs.\n\n## Summary\n\nThe Runner component provides:\n\n1. **Lifecycle Management** - Consistent init/teardown patterns via context managers\n2. **Worker Isolation** - Per-worker initialization with dedicated store connections\n3. **Hook Integration** - Extensibility through lifecycle callbacks\n4. **Telemetry** - Built-in tracer integration for span emission\n5. **Trainer Integration** - Seamless orchestration within the training loop\n\nRunners are the execution backbone of Agent Lightning, translating high-level training commands into agent task processing while maintaining observability through distributed tracing.\n\n---\n\n\n\n## LightningStore\n\n### Related Pages\n\nRelated topics: [System Architecture](#architecture), [Trainer Component](#trainer)\n\n
\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [agentlightning/store/base.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/base.py)\n- [agentlightning/store/memory.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/memory.py)\n- [agentlightning/store/client_server.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/client_server.py)\n- [agentlightning/store/threading.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/threading.py)\n- [agentlightning/store/collection_based.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/collection_based.py)\n
\n\n# LightningStore\n\nLightningStore is the central data persistence and synchronization layer in Agent Lightning. It manages the lifecycle of AI agent training workflows, including rollouts, attempts, spans, resources, and worker state. The store serves as the backbone for the training loop, enabling distributed execution, tracing, and experiment tracking.\n\n## Overview\n\nLightningStore provides a unified interface for:\n\n- **Rollout Management**: Tracking agent task executions from enqueue to completion\n- **Span Recording**: Capturing fine-grained traces of agent operations via OpenTelemetry\n- **Resource Management**: Storing and versioning agent configurations, prompts, and model definitions\n- **Worker Coordination**: Managing distributed worker states and heartbeats\n- **Metrics Collection**: Aggregating training metrics through Prometheus integration\n\nSource: [agentlightning/store/base.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/base.py)\n\n## Architecture\n\nLightningStore follows a pluggable backend architecture with a unified async interface.\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n Runner[Runner] --> Tracer[Tracers
OtelTracer
AgentOpsTracer]\n Tracer --> Client[LightningStoreClient]\n end\n \n subgraph \"Server Layer\"\n Client --> |HTTP/gRPC| Server[LightningStoreServer]\n Server --> Collections[LightningCollections]\n end\n \n subgraph \"Storage Backends\"\n Collections --> InMemory[InMemoryLightningStore]\n Collections --> SQLite[SQLiteLightningStore]\n Collections --> Mongo[MongoLightningStore]\n end\n \n subgraph \"Thread Safety\"\n Store[Any Store] --> Threaded[LightningStoreThreaded]\n end\n```\n\n### Core Components\n\n| Component | Purpose |\n|-----------|---------|\n| `LightningStore` | Abstract base class defining the store interface |\n| `LightningStoreClient` | HTTP client for remote store communication |\n| `LightningStoreServer` | FastAPI-based server handling store operations |\n| `LightningCollections` | Organized data collections (rollouts, spans, resources, workers) |\n| `LightningStoreThreaded` | Thread-safe wrapper for concurrent access |\n\nSource: [agentlightning/store/client_server.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/client_server.py)\n\n## Data Models\n\n### Core Types\n\nThe store operates on these fundamental data structures:\n\n| Model | Description |\n|-------|-------------|\n| `Rollout` | A complete task execution with status, timestamps, and metadata |\n| `Attempt` | A single attempt within a rollout (supports retries) |\n| `Span` | Fine-grained trace data for agent operations |\n| `TaskInput` | Input data for a task (prompt, parameters) |\n| `Worker` | Worker node state and heartbeat information |\n| `ResourcesUpdate` | Versioned resource configuration storage |\n| `RolloutConfig` | Configuration for rollout execution |\n\nSource: [agentlightning/types/core.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/types/core.py)\n\n### Rollout Status Lifecycle\n\n```mermaid\nstateDiagram-v2\n [*] --> Pending: enqueue_rollout\n Pending --> Running: start_rollout\n Running --> Completed: finish_rollout\n Running --> Failed: fail_rollout\n Completed --> [*]\n Failed --> [*]\n \n Running --> Attempted: start_attempt\n Attempted --> Running: finish_attempt\n```\n\nThe status values are:\n- `pending` - Queued for execution\n- `running` - Currently executing\n- `completed` - Successfully finished\n- `failed` - Execution failed\n\nSource: [agentlightning/store/base.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/base.py)\n\n## API Endpoints\n\nThe server exposes REST endpoints under `/v1/agl`:\n\n| Endpoint | Method | Description |\n|----------|--------|-------------|\n| `/rollouts` | POST | Enqueue new rollouts |\n| `/rollouts/{id}` | GET | Retrieve rollout by ID |\n| `/rollouts/{id}/start` | POST | Mark rollout as started |\n| `/rollouts/{id}/finish` | POST | Complete a rollout |\n| `/rollouts/{id}/attempt` | POST | Start a new attempt |\n| `/rollouts/{id}/attempt/{aid}/finish` | POST | Finish an attempt |\n| `/spans` | POST | Record span data |\n| `/spans/search` | POST | Query spans with filters |\n| `/resources` | POST | Add new resources |\n| `/resources/{id}` | GET/PUT | Get or update resources |\n| `/workers` | POST | Register worker |\n| `/workers/{id}/heartbeat` | POST | Worker heartbeat |\n| `/statistics` | GET | Store statistics |\n\nSource: [agentlightning/store/client_server.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/client_server.py)\n\n## Implementation Backends\n\n### In-Memory Store\n\nThe `InMemoryLightningStore` provides a lightweight, zero-dependency backend suitable for single-node execution and testing.\n\n**Key characteristics:**\n- All data stored in process memory\n- Supports collections with atomic transactions\n- Built-in size estimation for memory monitoring\n- Fast for development and small-scale experiments\n\n```python\nfrom agentlightning import InMemoryLightningStore\n\nstore = InMemoryLightningStore()\n```\n\nSource: [agentlightning/store/memory.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/memory.py)\n\n### SQLite Store\n\nSQLite backend provides persistent storage with ACID guarantees, suitable for single-node deployments requiring durability.\n\n### MongoDB Store\n\nMongoDB backend supports distributed deployments with horizontal scaling, providing high throughput for large-scale training runs.\n\n## Thread Safety\n\nThe `LightningStoreThreaded` class wraps any store implementation to provide thread-safe access:\n\n```python\nfrom agentlightning.store.threading import LightningStoreThreaded\n\n# Wrap any store with thread safety\nthreaded_store = LightningStoreThreaded(store)\n```\n\n**Thread safety features:**\n- Uses `threading.Lock` for synchronization\n- Guarantees atomic operations across concurrent requests\n- Maintains all original store capabilities\n- Exposes `thread_safe: True` and `async_safe: True` in capabilities\n\nSource: [agentlightning/store/threading.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/threading.py)\n\n## Collection Operations\n\nLightningStore uses a collection-based data organization pattern:\n\n```python\n# Atomic write operation\nasync with store.collections.atomic(mode=\"w\", snapshot=..., labels=[\"resources\"]) as collections:\n await collections.resources.insert([update])\n```\n\n### Supported Collections\n\n| Collection | Purpose |\n|------------|---------|\n| `rollouts` | Task execution records |\n| `attempts` | Individual attempt tracking |\n| `spans` | OpenTelemetry trace spans |\n| `resources` | Versioned configurations |\n| `workers` | Worker state management |\n\nSource: [agentlightning/store/collection_based.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/collection_based.py)\n\n## Decorators and Instrumentation\n\nThe store layer uses several decorators for observability and reliability:\n\n| Decorator | Purpose |\n|-----------|---------|\n| `@tracked` | Records operation metrics and timing |\n| `@healthcheck_before` | Validates store health before operations |\n| `@_with_collections_execute` | Manages collection lifecycle and error handling |\n\n## Integration with Tracers\n\nLightningStore integrates with OpenTelemetry through tracers:\n\n```python\nfrom agentlightning import OtelTracer, AgentOpsTracer\n\ntracer = OtelTracer(store=store)\n```\n\n**Tracing workflow:**\n\n```mermaid\nsequenceDiagram\n participant Agent\n participant Tracer\n participant Store\n participant OTLP\n \n Agent->>Tracer: Create span\n Tracer->>Store: Record span data\n Store->>Store: Persist to backend\n Tracer->>OTLP: Export spans (optional)\n```\n\nSource: [examples/minimal/write_traces.py](https://github.com/microsoft/agent-lightning/blob/main/examples/minimal/write_traces.py)\n\n## Usage Examples\n\n### Basic Store Operations\n\n```python\nfrom agentlightning import InMemoryLightningStore\n\n# Create store\nstore = InMemoryLightningStore()\n\n# Enqueue a task\nrollout = await store.enqueue_rollout(\n input={\"prompt\": \"Solve this problem\"},\n mode=\"train\"\n)\n\n# Dequeue for processing\ntask = await store.dequeue_rollout(worker_id=\"worker-1\")\n\n# Complete the rollout\nawait store.finish_rollout(\n rollout_id=task.rollout.rollout_id,\n attempt_id=task.attempt.attempt_id,\n response={\"answer\": \"42\"}\n)\n```\n\n### Server Setup\n\n```bash\n# Start a LightningStore server\nagl store --port 45993 --log-level DEBUG\n```\n\n### Client Connection\n\n```python\nfrom agentlightning import LightningStoreClient\n\nclient = LightningStoreClient(base_url=\"http://localhost:45993\")\n\n# All operations work through the client\nrollouts = await client.list_rollouts()\n```\n\n## Capabilities\n\nThe store reports its capabilities through the `capabilities` property:\n\n| Capability | Description |\n|------------|-------------|\n| `async_safe` | Supports async operations |\n| `thread_safe` | Supports concurrent thread access |\n| `distributed` | Supports multi-node deployment |\n| `persistence` | Data survives restarts |\n\nSource: [agentlightning/store/threading.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/store/threading.py)\n\n## CLI Commands\n\nThe `agl` CLI provides store management:\n\n```bash\n# Start store server\nagl store --port 45993 --log-level DEBUG\n\n# Prometheus metrics endpoint\nagl prometheus\n```\n\nSource: [agentlightning/cli/__init__.py](https://github.com/microsoft/agent-lightning/blob/main/agentlightning/cli/__init__.py)\n\n---\n\n\n\n## Algorithm Zoo\n\n### Related Pages\n\nRelated topics: [Tutorial: Train Your First Agent](#train-first-agent)\n\n
\nRelevant source files\n\nThe following source files were used to generate this page:\n\n- [examples/apo/apo_custom_algorithm.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_custom_algorithm.py)\n- [examples/apo/apo_custom_algorithm_trainer.py](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_custom_algorithm_trainer.py)\n- [examples/apo/README.md](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/README.md)\n- [CLAUDE.md](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n- [examples/rag/README.md](https://github.com/microsoft/agent-lightning/blob/main/examples/rag/README.md)\n
\n\n# Algorithm Zoo\n\n## Overview\n\nThe **Algorithm Zoo** is a modular collection of training algorithms that consume execution traces from the Agent Lightning runtime to improve agent behavior through reinforcement learning and prompt optimization. Source: [CLAUDE.md](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n\nAgent Lightning runs through a continuous loop where **runners** and **tracers** emit spans, `LightningStore` keeps them synchronized, and algorithms in `agentlightning/algorithm/` consume those traces to improve behavior. Source: [CLAUDE.md](https://github.com/microsoft/agent-lightning/blob/main/CLAUDE.md)\n\n## Architecture\n\nThe Algorithm Zoo follows a producer-consumer pattern where the store acts as the central synchronization hub:\n\n```mermaid\ngraph TD\n A[Runners] -->|emit spans| B[LightningStore]\n C[Tracers] -->|emit spans| B\n B -->|traces| D[Algorithm Zoo]\n D -->|policy updates| E[Improved Agent Behavior]\n B -->|traces| F[Dashboard]\n```\n\n## Available Algorithms\n\n### APO (Adaptive Prompt Optimization)\n\nAPO is a prompt optimization algorithm that iteratively refines prompt templates based on reward signals collected from agent rollouts.\n\n#### How APO Works\n\nThe APO algorithm maintains a collection of prompt candidates and evaluates each one against task objectives. Based on the reward signals, it selects and refines the most effective prompts. Source: [examples/apo/apo_custom_algorithm.py:34-37](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_custom_algorithm.py)\n\n```python\nasync def apo_algorithm(*, store: agl.LightningStore):\n \"\"\"\n An example of how a prompt optimization works.\n \"\"\"\n prompt_candidates = [\n \"You are a helpful assistant. {any_question}\",\n \"You are a knowledgeable AI. {any_question}\",\n \"You are a friendly chatbot. {any_question}\",\n ]\n\n prompt_and_rewards: list[tuple[str, float]] = []\n```\n\n#### Custom APO Algorithm\n\nTo create a custom algorithm, wrap your async function with the `@algo` decorator. Source: [examples/apo/apo_custom_algorithm_trainer.py:28-39](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_custom_algorithm_trainer.py)\n\n```python\nfrom agentlightning.algorithm import algo\n\n@algo\nasync def apo_algorithm_usable_in_trainer(*, store: LightningStore):\n \"\"\"\n You need to wrap the apo_algorithm in an algo decorator to make it usable in trainer.\n \"\"\"\n return await apo_algorithm(store=store)\n```\n\n### VERL (Value-Enhanced Reinforcement Learning)\n\nVERL is a full training algorithm that integrates with the VERL library for GPU-accelerated reinforcement learning. Source: [examples/tinker/q20_train.py:43-52](https://github.com/microsoft/agent-lightning/blob/main/examples/tinker/q20_train.py)\n\n```python\nalgo_verl_parser = subparsers.add_parser(\"verl\", help=\"Launch the full training algorithm with VERL.\")\nalgo_verl_parser.add_argument(\"--port\", type=int, default=4747, help=\"Port for the AgentLightning store.\")\nalgo_verl_parser.add_argument(\n \"--model\",\n choices=(\"qwen25\", \"qwen3\"),\n default=\"qwen3\",\n help=\"Model variant to train.\",\n)\nalgo_verl_parser.add_argument(\"--search\", action=\"store_true\", help=\"Enable search tool.\")\n```\n\n### FAST (Fast Algorithm Suite Toolkit)\n\nThe FAST algorithm provides lightweight optimization capabilities for rapid experimentation.\n\n## Running Algorithms\n\n### Option A: Separate Components\n\nStart the store, algorithm, and runner in three separate terminals: Source: [examples/apo/README.md:10-24](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/README.md)\n\n```bash\n# Terminal 1: Start the store\nagl store\n\n# Terminal 2: Run the algorithm\npython apo_custom_algorithm.py algo\n\n# Terminal 3: Run the rollout runner\npython apo_custom_algorithm.py runner\n```\n\n### Option B: Integrated Trainer\n\nUse the integrated trainer that handles all components: Source: [examples/apo/apo_custom_algorithm_trainer.py:47-49](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_custom_algorithm_trainer.py)\n\n```python\nfrom agentlightning import Trainer, setup_logging\n\ntrainer = Trainer(n_workers=1, algorithm=apo_algorithm_usable_in_trainer)\ntrainer.fit(apo_rollout)\n```\n\n### Algorithm Decorator\n\nThe `@algo` decorator transforms any async algorithm function into a component that can be used with the `Trainer`. It injects the `LightningStore` as a keyword argument. Source: [examples/apo/apo_custom_algorithm_trainer.py:28-39](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_custom_algorithm_trainer.py)\n\n## Algorithm Configuration\n\n### Common Parameters\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `store` | `LightningStore` | Central store for traces and resources |\n| `n_workers` | `int` | Number of parallel workers |\n| `port` | `int` | Port for store connection (default: 4747) |\n\n### VERL-Specific Options\n\n| Option | Choices | Default | Description |\n|--------|---------|---------|-------------|\n| `--model` | qwen25, qwen3 | qwen3 | Model variant to train |\n| `--port` | int | 4747 | Store connection port |\n| `--search` | flag | False | Enable search tool |\n\n## Workflow\n\n```mermaid\ngraph LR\n A[Define Prompt Candidates] --> B[Loop Through Candidates]\n B --> C[Update Resources in Store]\n C --> D[Run Rollout with Runner]\n D --> E[Collect Reward Signal]\n E --> F[Update Prompt Template]\n F --> B\n```\n\n## Extending the Algorithm Zoo\n\n### Creating Custom Algorithms\n\n1. Define an async function that takes `store: LightningStore` as a keyword argument\n2. Wrap it with the `@algo` decorator\n3. Implement your optimization logic\n4. Use the trainer or run separately\n\nExample pattern: Source: [examples/apo/apo_custom_algorithm.py:54-72](https://github.com/microsoft/agent-lightning/blob/main/examples/apo/apo_custom_algorithm.py)\n\n```python\nasync def apo_algorithm(*, store: agl.LightningStore):\n for prompt in prompt_candidates:\n # 1. The optimization algorithm updates the prompt template\n console.print(f\"[Algo] Updating prompt template to: '{prompt}'\")\n resources: agl.NamedResources = {\n # The \"main_prompt\" can be replaced with any name\n }\n # 2. Update resources in store\n # 3. Collect reward signals\n # 4. Refine prompt based on rewards\n```\n\n### Requirements for Custom Algorithms\n\n- Must be async functions\n- Must accept `store` as keyword argument\n- Should be wrapped with `@algo` decorator for trainer integration\n- Must interact with `LightningStore` for state synchronization\n\n## Integration with RAG\n\nThe Algorithm Zoo can be extended to work with retrieval-augmented generation systems. See the RAG example for integrating FAISS-based retrieval with prompt optimization. Source: [examples/rag/README.md](https://github.com/microsoft/agent-lightning/blob/main/examples/rag/README.md)\n\n## See Also\n\n- [APO Tutorial](../../docs/tutorials/apo.md)\n- [Custom Algorithm Tutorial](../../docs/how-to/write-first-algorithm.md)\n- [Dashboard Documentation](../../dashboard/README.md)\n\n---\n\n---\n\n## Doramagic Pitfall Log\n\nProject: microsoft/agent-lightning\n\nSummary: Found 7 potential pitfall items; 0 are high/blocking. Highest priority: capability - 能力判断依赖假设.\n\n## 1. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | README/documentation is current enough for a first validation pass.\n\n## 2. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | last_activity_observed missing\n\n## 3. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | no_demo; severity=medium\n\n## 4. security_permissions · 存在安全注意事项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: No sandbox install has been executed yet; downstream must verify before user use.\n- User impact: 用户安装前需要知道权限边界和敏感操作。\n- Suggested check: 转成明确权限清单和安全审查提示。\n- Guardrail action: 安全注意事项必须面向用户前置展示。\n- Evidence: risks.safety_notes | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 5. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | no_demo; severity=medium\n\n## 6. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | issue_or_pr_quality=unknown\n\n## 7. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | release_recency=unknown\n\n\n", "summary": "DeepWiki/Human Wiki output with a Doramagic pitfall appendix.", "title": "Human Manual" }, "pitfall_log": { "asset_id": "pitfall_log", "filename": "PITFALL_LOG.md", "markdown": "# Pitfall Log\n\nProject: microsoft/agent-lightning\n\nSummary: Found 7 potential pitfall items; 0 are high/blocking. Highest priority: capability - 能力判断依赖假设.\n\n## 1. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | README/documentation is current enough for a first validation pass.\n\n## 2. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | last_activity_observed missing\n\n## 3. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | no_demo; severity=medium\n\n## 4. security_permissions · 存在安全注意事项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: No sandbox install has been executed yet; downstream must verify before user use.\n- User impact: 用户安装前需要知道权限边界和敏感操作。\n- Suggested check: 转成明确权限清单和安全审查提示。\n- Guardrail action: 安全注意事项必须面向用户前置展示。\n- Evidence: risks.safety_notes | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 5. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | no_demo; severity=medium\n\n## 6. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | issue_or_pr_quality=unknown\n\n## 7. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | art_9b504779cfa046a894eeb7c9d3a298c6 | https://github.com/microsoft/agent-lightning#readme | release_recency=unknown\n", "summary": "Identity, installation, configuration, runtime, and safety pitfalls before user trial.", "title": "Pitfall Log" }, "prompt_preview": { "asset_id": "prompt_preview", "filename": "PROMPT_PREVIEW.md", "markdown": "# agent-lightning - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for microsoft/agent-lightning.\n\nProject:\n- Name: agent-lightning\n- Repository: https://github.com/microsoft/agent-lightning\n- Summary:

\n- Host target: chatgpt\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet:

\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1:

\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. introduction: Introduction to Agent Lightning. Produce one small intermediate artifact and wait for confirmation.\n2. architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n3. core_abstractions: Core Abstractions and Data Models. Produce one small intermediate artifact and wait for confirmation.\n4. train-first-agent: Tutorial: Train Your First Agent. Produce one small intermediate artifact and wait for confirmation.\n5. write-agents: Tutorial: Writing Agents. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/microsoft/agent-lightning#readme\n- README.md\n- agentlightning/__init__.py\n- docs/deep-dive/birds-eye-view.md\n- agentlightning/trainer/trainer.py\n- agentlightning/store/base.py\n- agentlightning/types/core.py\n- agentlightning/types/resources.py\n- agentlightning/types/tracer.py\n- docs/how-to/train-first-agent.md\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n", "summary": "不安装项目也能感受能力节奏的安全试用 Prompt。", "title": "Prompt Preview / 安装前试用 Prompt" }, "quick_start": { "asset_id": "quick_start", "filename": "QUICK_START.md", "markdown": "# Quick Start\n\nProject: microsoft/agent-lightning\n\n## Official Entry Points\n\n### Python / pip · 官方安装入口\n\n```bash\npip install agentlightning\n```\n\nSource：https://github.com/microsoft/agent-lightning#readme\n\n## Sources\n\n- docs: https://github.com/microsoft/agent-lightning#readme\n", "summary": "Entry points extracted from official README or installation documentation.", "title": "Quick Start" } }, "validation_id": "dval_7811550190c749da836bb4a10c48be53" }