Setup, end to end: pick a Bot, connect a model, prove it answers

.github/published-images.json

@@ -1 +1,19 @@
-["agent-computer", "supervisor", "agent-bot", "agent-langgraph", "server"]
+[
+  "agent-computer",
+  "supervisor",
+  "agent-bot",
+  "agent-langgraph",
+  "server",
+  "agent-crewai",
+  "agent-llamaindex",
+  "agent-agno",
+  "agent-langgraph-agui",
+  "agent-adk",
+  "agent-pydantic-ai",
+  "agent-microsoft",
+  "agent-claude-sdk",
+  "agent-strands",
+  "agent-ag2",
+  "agent-langroid",
+  "agent-mastra"
+]

agent-adk/Dockerfile

@@ -0,0 +1,19 @@
+# Google ADK, as a Bot. Python rather than Bun because that is what the integration is published in,
+# and the protocol is the only thing a Bot has to share with the others.
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Dependencies before source, so editing the Bot does not re-resolve the framework.
+COPY agent-adk/requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY agent-adk/src ./src
+
+ENV PORT=4208
+EXPOSE 4208
+# 0.0.0.0, not `::`. uvicorn binds `::` as IPv6-only, with no v4-mapped addresses, so a container
+# started that way refuses 127.0.0.1: the Compose healthcheck never passes and the server cannot
+# reach the Bot. Measured, not assumed. Inside a container this is the container's own namespace,
+# and Compose is what decides which host addresses it is published on.
+CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "4208"]

agent-adk/requirements.txt

@@ -0,0 +1,6 @@
+ag-ui-adk
+google-adk
+litellm
+fastapi
+python-multipart
+uvicorn[standard]

agent-adk/src/main.py

@@ -0,0 +1,54 @@
+"""Google ADK as a Bot, through `ag_ui_adk`, which AG-UI maintains.
+
+ADK is Gemini-first and model-agnostic after that, so the provider stays the person's choice: ADK
+reads LiteLLM model strings, and OpenBot writes the one it was told.
+"""
+
+import os
+
+from ag_ui_adk import ADKAgent, add_adk_fastapi_endpoint
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from google.adk.agents import Agent
+from google.adk.models.lite_llm import LiteLlm
+
+TOKEN_HEADER = "x-openbot-agent-token"
+
+
+def _model_id() -> str:
+    provider = (os.environ.get("BOT_PROVIDER") or "openai").strip()
+    model = (os.environ.get("BOT_MODEL") or "gpt-4o-mini").strip()
+    return model if "/" in model else f"{provider}/{model}"
+
+
+app = FastAPI()
+
+
+@app.middleware("http")
+async def refuse_without_the_server_token(request: Request, call_next):
+    if request.url.path != "/health":
+        expected = (os.environ.get("MANAGED_AGENT_TOKEN") or "").strip()
+        offered = (request.headers.get(TOKEN_HEADER) or "").strip()
+        if not expected or offered != expected:
+            return JSONResponse({"error": "unauthorised"}, status_code=401)
+    return await call_next(request)
+
+
+@app.get("/health")
+async def health():
+    return {"ok": True, "harness": "google-adk"}
+
+
+add_adk_fastapi_endpoint(
+    app,
+    ADKAgent(
+        adk_agent=Agent(
+            name="openbot",
+            model=LiteLlm(model=_model_id()),
+            instruction="Answer the question you are asked, briefly and correctly.",
+        ),
+        app_name="openbot",
+        user_id="openbot",
+    ),
+    path="/",
+)

agent-ag2/Dockerfile

@@ -0,0 +1,19 @@
+# AG2, as a Bot. Python rather than Bun because that is what the integration is published in,
+# and the protocol is the only thing a Bot has to share with the others.
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Dependencies before source, so editing the Bot does not re-resolve the framework.
+COPY agent-ag2/requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY agent-ag2/src ./src
+
+ENV PORT=4210
+EXPOSE 4210
+# 0.0.0.0, not `::`. uvicorn binds `::` as IPv6-only, with no v4-mapped addresses, so a container
+# started that way refuses 127.0.0.1: the Compose healthcheck never passes and the server cannot
+# reach the Bot. Measured, not assumed. Inside a container this is the container's own namespace,
+# and Compose is what decides which host addresses it is published on.
+CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "4210"]

agent-ag2/requirements.txt

@@ -0,0 +1,4 @@
+ag2[ag-ui,openai]
+fastapi
+python-multipart
+uvicorn[standard]

agent-ag2/src/main.py

@@ -0,0 +1,39 @@
+"""AG2 as a Bot. AG-UI is an extra in AG2's own package, so `ag2[ag-ui]` is the dependency."""
+
+import os
+
+from ag2 import Agent
+from ag2.ag_ui import AGUIStream
+from ag2.config import OpenAIConfig
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+
+TOKEN_HEADER = "x-openbot-agent-token"
+
+agent = Agent(
+    name="openbot",
+    prompt="Answer the question you are asked, briefly and correctly.",
+    config=OpenAIConfig(model=(os.environ.get("BOT_MODEL") or "gpt-4o-mini").strip()),
+)
+stream = AGUIStream(agent)
+
+app = FastAPI()
+
+
+@app.middleware("http")
+async def refuse_without_the_server_token(request: Request, call_next):
+    if request.url.path != "/health":
+        expected = (os.environ.get("MANAGED_AGENT_TOKEN") or "").strip()
+        offered = (request.headers.get(TOKEN_HEADER) or "").strip()
+        if not expected or offered != expected:
+            return JSONResponse({"error": "unauthorised"}, status_code=401)
+    return await call_next(request)
+
+
+@app.get("/health")
+async def health():
+    return {"ok": True, "harness": "ag2"}
+
+
+# `build_asgi` rather than a helper: AG2 hands back a plain ASGI app to mount.
+app.mount("/", stream.build_asgi())

agent-agno/Dockerfile

@@ -0,0 +1,19 @@
+# Agno, as a Bot. Python rather than Bun because that is what the integration is published in,
+# and the protocol is the only thing a Bot has to share with the others.
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Dependencies before source, so editing the Bot does not re-resolve the framework.
+COPY agent-agno/requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY agent-agno/src ./src
+
+ENV PORT=4203
+EXPOSE 4203
+# 0.0.0.0, not `::`. uvicorn binds `::` as IPv6-only, with no v4-mapped addresses, so a container
+# started that way refuses 127.0.0.1: the Compose healthcheck never passes and the server cannot
+# reach the Bot. Measured, not assumed. Inside a container this is the container's own namespace,
+# and Compose is what decides which host addresses it is published on.
+CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "4203"]

agent-agno/requirements.txt

@@ -0,0 +1,5 @@
+agno[agui]
+litellm
+fastapi
+python-multipart
+uvicorn[standard]

agent-agno/src/main.py

@@ -0,0 +1,59 @@
+"""Agno as a Bot.
+
+The AG-UI support is an extra in Agno's own package rather than a separate bridge, so `agno[agui]`
+is the whole dependency and `AGUIApp` is the whole integration. Nothing of the protocol is written
+here, which is the rule.
+"""
+
+import os
+
+from agno.agent import Agent
+from agno.db.in_memory import InMemoryDb
+from agno.models.litellm import LiteLLM
+from agno.os import AgentOS
+from agno.os.interfaces.agui import AGUI
+from fastapi import Request
+from fastapi.responses import JSONResponse
+
+TOKEN_HEADER = "x-openbot-agent-token"
+
+
+def _model_id() -> str:
+    """`provider/model`, which is how litellm addresses one and how OpenBot stores the choice."""
+    provider = (os.environ.get("BOT_PROVIDER") or "openai").strip()
+    model = (os.environ.get("BOT_MODEL") or "gpt-5.5").strip()
+    return model if "/" in model else f"{provider}/{model}"
+
+
+agent = Agent(
+    # In memory, because a Bot's history lives in OpenBot's database and not in the harness. Two
+    # places remembering the same conversation is how they come to disagree.
+    db=InMemoryDb(),
+    model=LiteLLM(id=_model_id()),
+    # No role, goal or backstory invented on somebody's behalf. A Bot answers the question it is
+    # asked, and anybody who wants a persona sets one in OpenBot where the rest of them live.
+    instructions="Answer the question you are asked, briefly and correctly.",
+)
+
+app = AgentOS(agents=[agent], interfaces=[AGUI(agent=agent)]).get_app()
+
+
+@app.middleware("http")
+async def refuse_without_the_server_token(request: Request, call_next):
+    """Everything but `/health` carries the server's token.
+
+    `/health` is exempt because Compose polls it before any token exists, and a healthcheck that
+    authenticates is a container that never reports healthy.
+    """
+    if request.url.path != "/health":
+        expected = (os.environ.get("MANAGED_AGENT_TOKEN") or "").strip()
+        offered = (request.headers.get(TOKEN_HEADER) or "").strip()
+        # Unset means unconfigured, not open.
+        if not expected or offered != expected:
+            return JSONResponse({"error": "unauthorised"}, status_code=401)
+    return await call_next(request)
+
+
+@app.get("/health")
+async def health():
+    return {"ok": True, "harness": "agno"}

agent-bot/src/index.ts

@@ -5,6 +5,7 @@ import OpenAI from "openai";
 import { hasManagedAgentToken } from "../../shared/agent-authorisation";
 import { listenPort } from "../../shared/listen-port";
 import { toProviderMessages } from "./history";
+import { apiKeyOrPlaceholder, keyIsRequired } from "./model-key";
 
 /**
  * The built-in Bot is an AG-UI HTTP service registered the same way as any customer-provided Bot.
@@ -80,15 +81,26 @@ const BASE_URL = process.env.OPENAI_BASE_URL?.trim() || undefined;
  * should fail in front of whoever is deploying, not in front of whoever is asking.
  */
 const API_KEY = process.env.OPENAI_API_KEY?.trim();
-if (!API_KEY) {
+/*
+ * UNLESS AN ENDPOINT WAS NAMED, in which case the endpoint is the model and the key belongs to it.
+ *
+ * Ollama, vLLM, LM Studio and llama.cpp all serve this API with no key at all, and the setup window
+ * offers exactly those by name. Requiring one here refused the whole keyless half of that feature:
+ * the person filled in an address, the app raised this Bot, and it exited on startup with
+ * "OPENAI_API_KEY is not set" about a key their endpoint does not have. The two ends of one feature
+ * disagreeing.
+ *
+ * The check still holds for plain OpenAI, which is the case it was written for.
+ */
+if (!API_KEY && keyIsRequired(BASE_URL)) {
   console.error(
-    "OPENAI_API_KEY is not set. This Bot cannot answer without a model.",
+    "OPENAI_API_KEY is not set, and no OPENAI_BASE_URL names an endpoint that needs no key. This Bot cannot answer without a model.",
   );
   process.exit(1);
 }
 
 const openai = new OpenAI({
-  apiKey: API_KEY,
+  apiKey: apiKeyOrPlaceholder(API_KEY),
   baseURL: BASE_URL,
 });
 
@@ -241,4 +253,4 @@ serve({
   },
 });
 
-console.info(`agent-bot listening on http://localhost:${PORT}/ag-ui`);
+console.info(`agent-bot listening on http://127.0.0.1:${PORT}/ag-ui`);

agent-bot/src/model-key.ts

@@ -0,0 +1,26 @@
+/**
+ * Whether this Bot needs a model key, checked before it starts.
+ *
+ * Its own module because `index.ts` serves at module scope, so importing it to reach one pure
+ * function binds a port.
+ */
+
+/**
+ * A key is required unless an endpoint was named to answer instead.
+ *
+ * `OPENAI_BASE_URL` set means any endpoint speaking that API, and Ollama, vLLM, LM Studio and
+ * llama.cpp all serve it with no key. The setup window offers exactly those by name and accepts a
+ * blank key for them, so requiring one here exited this Bot on startup for every one of them.
+ */
+export function keyIsRequired(baseUrl: string | undefined): boolean {
+  return !baseUrl?.trim();
+}
+
+/**
+ * What to hand the SDK, which insists on a string even when the endpoint ignores it.
+ *
+ * A placeholder rather than an empty string: empty is a client that cannot be constructed.
+ */
+export function apiKeyOrPlaceholder(apiKey: string | undefined): string {
+  return apiKey?.trim() || "no-key-needed";
+}

agent-bot/tests/model-key.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+import { apiKeyOrPlaceholder, keyIsRequired } from "../src/model-key";
+
+/**
+ * A named endpoint is a model, and its key belongs to it.
+ *
+ * The failure this pins: the setup window's "any OpenAI-compatible endpoint" row takes an address
+ * with no key, because Ollama and vLLM have none. This Bot then refused to start, saying
+ * OPENAI_API_KEY was not set, so the keyless half of that feature produced a dead container and a
+ * red line on the last screen about a key the person's own server does not have.
+ */
+describe("whether a model key is required", () => {
+  test("plain OpenAI still needs its key", () => {
+    expect(keyIsRequired(undefined)).toBe(true);
+    expect(keyIsRequired("")).toBe(true);
+    expect(keyIsRequired("   ")).toBe(true);
+  });
+
+  test("an endpoint named instead of OpenAI answers without one", () => {
+    expect(keyIsRequired("http://127.0.0.1:11434/v1")).toBe(false);
+  });
+
+  test("the SDK is always handed a string", () => {
+    expect(apiKeyOrPlaceholder(undefined)).toBe("no-key-needed");
+    expect(apiKeyOrPlaceholder("  ")).toBe("no-key-needed");
+    expect(apiKeyOrPlaceholder("sk-real")).toBe("sk-real");
+  });
+});

agent-claude-sdk/Dockerfile

@@ -0,0 +1,19 @@
+# Claude Agent SDK, as a Bot. Python rather than Bun because that is what the integration is published in,
+# and the protocol is the only thing a Bot has to share with the others.
+FROM python:3.12-slim
+
+WORKDIR /app
+
+# Dependencies before source, so editing the Bot does not re-resolve the framework.
+COPY agent-claude-sdk/requirements.txt ./
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY agent-claude-sdk/src ./src
+
+ENV PORT=4212
+EXPOSE 4212
+# 0.0.0.0, not `::`. uvicorn binds `::` as IPv6-only, with no v4-mapped addresses, so a container
+# started that way refuses 127.0.0.1: the Compose healthcheck never passes and the server cannot
+# reach the Bot. Measured, not assumed. Inside a container this is the container's own namespace,
+# and Compose is what decides which host addresses it is published on.
+CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "4212"]

agent-claude-sdk/requirements.txt

@@ -0,0 +1,4 @@
+ag-ui-claude-sdk
+fastapi
+python-multipart
+uvicorn[standard]