Deployment Guide

Deployment Guide

LightAgent is a Python library. Most production deployments wrap it in an application service such as FastAPI, Flask, a worker process, or an internal automation job.

Configuration

Use environment variables for provider credentials:

export OPENAI_API_KEY="your_api_key"
export OPENAI_BASE_URL="https://api.openai.com/v1"

Avoid hardcoding keys in code, examples, or Wiki pages.

Basic Service Shape

from fastapi import FastAPI
from pydantic import BaseModel
from LightAgent import LightAgent

app = FastAPI()

agent = LightAgent(
    model="gpt-4.1",
    api_key=None,
    base_url=None,
)

class ChatRequest(BaseModel):
    query: str
    user_id: str = "default_user"

@app.post("/chat")
def chat(req: ChatRequest):
    result = agent.run(req.query, user_id=req.user_id, result_format="object")
    return {
        "content": result.content,
        "trace_id": result.trace_id,
        "error": result.error,
    }

Streaming APIs

Use stream=True when building a streaming endpoint:

def generate(query: str, user_id: str):
    for chunk in agent.run(query, stream=True, user_id=user_id):
        yield chunk

For typed events, use result_format="event" and serialize each StreamEvent.

Production Checklist

• Pin package versions.
• Use environment variables or secret managers.
• Add request timeouts at the application layer.
• Keep tool outputs compact.
• Add memory namespace policies for shared backends.
• Disable or isolate built-in code execution tools for untrusted users.
• Enable trace only where data handling is approved.
• Add rate limits and concurrency controls.
• Log trace_id, user id, tool names, and status metadata.

Stateless vs Stateful

LightAgent itself can be used in stateless request handlers, but memory backends, logs, trace exports, and application histories are stateful. Decide where each state type lives:

• conversation history: application database
• long-term memory: memory backend
• trace and logs: observability stack
• files and artifacts: object storage