Migration guide¶

This document explains what changed when multi_agent_testbed and prometheus_platform were merged into the combined Prometheus platform, and why.

Summary of changes¶

The merge replaced the old FastAPI backend in prometheus_platform with the multi-agent orchestration system from multi_agent_testbed. The Chainlit frontend now communicates directly with the client-agent via the A2A JSON-RPC protocol, eliminating the backend as a middleman.

What was removed¶

The backend/ directory has been deleted.

What was merged from multi_agent_testbed¶

The contents of multi_agent_testbed/ were moved into prometheus_platform/, creating a single unified project:

What was added to the frontend¶

What was preserved unchanged¶

• Custom React elements: ExodusViewer.jsx, IFCViewer.jsx, MermaidViewer.jsx, DynamicForm.jsx, FollowUpSuggestions.jsx -- no protocol dependency, receive props from Python
• File upload handling: Exodus, IFC, and PDF uploads are still processed locally in the frontend before any agent call
• Chainlit authentication: Password-based auth via config.yml local-users, independent of agent auth
• Settings panel: Debug toggles, agent name display, auto-approve setting
• VTK/IFC build tooling: public/js/ bundles for 3D viewers

Why these changes were made¶

Eliminating the backend middleman¶

The old FastAPI backend was a pass-through: it received chat messages from the frontend, forwarded them to a basic LLM, and returned responses. It added latency and maintenance burden without meaningful logic. The client-agent in multi_agent_testbed already handled query classification, agent discovery, planning, and execution -- duplicating this in the backend served no purpose.

Multi-agent orchestration¶

The old backend had a single LLM endpoint. The new architecture routes queries to specialist agents based on capability metadata, supports multi-step execution plans with user approval, and chains agent outputs across workflow steps. This required the client-agent's LangGraph workflow, LiteLLM-backed agent discovery/routing, and the A2A protocol for inter-agent communication.

Artifact management¶

The old backend used hardcoded demo endpoints (/api/demo/ifc, /api/demo/exodus) to serve static artifacts. The new system has a conversation-scoped artifact registry where any agent can produce artifacts (JSON, files, references) that are tracked across conversation turns and rendered by appropriate frontend viewers.

Configuration changes¶

Old configuration (config.yml)¶

platform-url: "http://localhost:8001"   # FastAPI backend
model: "gpt-oss-120B"                   # Direct model selection
openai_api_key: "..."                   # Direct API key

New configuration (config.yml)¶

agent-url: "http://localhost:8001"      # Client-agent A2A endpoint
agent-secret: ""                        # Bearer token (use AGENT_SECRET env var)
redis-url: "redis://localhost:6379"     # Redis for conversation state/status
debug: true
auto-approve-steps: false

Model selection and API keys are now configured on the client-agent and specialist agents, not the frontend.

Environment variables¶

Protocol change: HTTP REST to A2A JSON-RPC¶

Before (old backend)¶

# Frontend → Backend
requests.post(
    "http://backend:8001/api/chat",
    json={"message": "Analyze SS316...", "user_id": "user_123"},
    headers={"Authorization": "Bearer <hardcoded-token>"},
)
# Response: {"type": "workflow", "response": "...", "workflow_id": "..."}

After (A2A client-agent)¶

# Frontend → Client-Agent
client = A2AClient(agent_url="http://client-agent:8001", agent_secret=os.getenv("AGENT_SECRET"))
response = await client.send(
    query="Analyze SS316...",
    conversation_id=conv_id,
    artifacts=artifact_catalog,
)
# Response: ConversationResponse(status="completed", report="...", artifacts=[...])

The key differences:

1. Protocol: Plain HTTP POST with flat JSON body becomes JSON-RPC 2.0 with nested message/send envelope
2. State: No conversation tracking becomes conversation_id + Redis-backed state
3. Response model: {type, response} becomes ConversationResponse with lifecycle states (needs_info, plan_ready, completed, answer)
4. Auth: Hardcoded token becomes configurable AGENT_SECRET env var
5. Artifacts: Ephemeral demo URLs become conversation-scoped registry with typed rendering

Known limitations¶

• Status polling instead of streaming: The client-agent uses blocking mode (blocking: true). The A2A client polls /status/{conversation_id} every 3 seconds for progress updates, but there is no real-time streaming from specialist agents.
• Conversation state has no TTL: Redis conversation keys persist indefinitely. A 24-48 hour TTL should be added to prevent unbounded memory growth.

Docker Compose changes¶

The deployment moved from a frontend-only Docker setup to a full multi-agent stack defined in docker-compose.yml at the project root:

All containers share the agent-network bridge. Specialist agents register with LiteLLM on startup, and the client-agent discovers them dynamically through LiteLLM's /v1/agents directory.