Run The Demo API¶

This tutorial uses the self-contained project under demo/api. It serves several LangGraph graphs through the OpenAI-compatible /v1 interface.

Prerequisites¶

• Python 3.11 or newer
• uv
• PostgreSQL (the included Compose service requires Docker)
• An OpenAI-compatible upstream model only if you call the LLM-backed graphs

Start PostgreSQL And The API¶

cd demo
cp .env.example .env
docker compose -f compose.yaml up -d lgos-db

make run-api-local

make run-api

The direct lgos-a base URL is http://localhost:3004/v1. Compose also runs the same image as independently addressable lgos-b on port 3005; the two services intentionally expose the same graph set today.

Inspect registered graphs:

curl http://localhost:3004/v1/models

Each demo graph publishes its API-owned description in the lightweight langgraph_openai_serve list extension.

The complete model and requirement matrix is in Example Graphs.

Call A Graph¶

from openai import OpenAI

client = OpenAI(base_url="http://localhost:3004/v1", api_key="DUMMY")

response = client.chat.completions.create(
    model="custom-input-output-context",
    messages=[{"role": "user", "content": "Show me the custom adapter."}],
    user="demo-user",
)

print(response.choices[0].message.content)

Try the citation custom-event graph:

response = client.chat.completions.create(
    model="citation-events",
    messages=[{"role": "user", "content": "Show me a cited answer."}],
)

print(response.choices[0].message.content)
print(response.choices[0].message.annotations)

The deterministic answer combines portable Markdown resources with structured citations. See Citation Events for the graph helper and Citation ownership for transport and client behavior.

Ask the RAG graph about the packaged LGOS overview and demo documentation with real-time token streaming:

stream = client.chat.completions.create(
    model="lgos-rag",
    messages=[{"role": "user", "content": "How does LGOS streaming work?"}],
    stream=True,
)

for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

lgos-rag follows an agentic RAG loop: it decides when retrieval is needed, searches chunked documentation through a tool, grades relevance, and rewrites once when retrieval misses. Social and conversation-history turns skip retrieval. Grounded answers use exact source-backed Markdown links rather than citation annotations; source-provided image Markdown is preserved, while audio and video remain ordinary links.

Try the async mock MCP graph:

response = client.chat.completions.create(
    model="advanced-mcp-tools",
    messages=[{"role": "user", "content": "What is the weather in Istanbul?"}],
)

Try the deterministic status-event showcase:

stream = client.chat.completions.create(
    model="status-events",
    messages=[
        {
            "role": "user",
            "content": "Prepare the media workflow.",
        }
    ],
    stream=True,
    user="demo-user",
    metadata={"langgraph_stream_events": "v1"},
)

for chunk in stream:
    extension = (chunk.model_extra or {}).get("langgraph_openai_serve")
    if isinstance(extension, dict):
        print("Event:", extension["event"])

    if text := chunk.choices[0].delta.content:
        print(text, end="", flush=True)

The graph emits Generating audio, Calculating embeddings, and a final Media ready status with done=True. The separate custom-event-showcase graph demonstrates application-defined progress and artifact events interleaved with assistant text.

Try A Demo Client¶

The demo includes optional Chainlit and Open WebUI clients. The Compose stack routes both through the bundled Bifrost gateway. The dynamic clients use the gateway catalog for provider-qualified discovery and raw pass-through for LGOS model metadata and inference. The fixed-model Open WebUI example uses Bifrost pass-through without catalog discovery.

Next Steps¶

• Run the complete stack with Docker Compose
• Register custom graphs in your own FastAPI app
• Connect OpenAI clients