The Frontend API Client is a TypeScript-based communication layer that bridges the React Web UI with the FastAPI-powered Agent Service. It provides a type-safe interface for CRUD operations on agents, sessions, and workspaces, while also handling the complex AGUI protocol transformation for streaming agent events.
The core of the frontend communication is the client object defined in examples/web_ui/frontend/src/api/client.ts124-145 It is built on the standard Web fetch API and provides a structured way to handle request options, headers, and errors.
The client relies on localStorage to persist connection settings across sessions:
getBaseUrl(), which reads the server_url key examples/web_ui/frontend/src/api/client.ts3X-User-ID header, retrieved via getUserId() from the username key examples/web_ui/frontend/src/api/client.ts4-41The client uses a custom ApiError class to wrap non-2xx HTTP responses examples/web_ui/frontend/src/api/client.ts10-20
silent option is set to true, errors are automatically displayed to the user via sonner toasts examples/web_ui/frontend/src/api/client.ts104-111TIMEOUT_STATUS (408) is reported if a request exceeds its timeoutMs examples/web_ui/frontend/src/api/client.ts38-99The following diagram illustrates how a frontend action (e.g., creating an agent) flows through the client to the FastAPI routers.
Diagram: API Request Lifecycle
Sources: examples/web_ui/frontend/src/api/client.ts124-145 examples/web_ui/frontend/src/api/agent.ts11-23 src/agentscope/app/_router/_agent.py165-175
The API is partitioned into modules mirroring the backend router structure src/agentscope/app/_router/__init__.py3-17
| Module | Purpose | Key Functions |
|---|---|---|
agentApi | Agent CRUD and Schema | list(), getSchema(), create(), update() |
sessionApi | Chat session management | list(), create(), delete(), stream() |
workspaceApi | Filesystem, MCP, and Skills | directories(), mcp.add(), skill.upload() |
healthApi | Service readiness probes | check(baseUrl, userId) |
knowledgeBaseApi | RAG document management | list(), upload(), delete() |
channelApi | External platform channels | list(), create(), update(), getTypes() |
TypeScript interfaces in types.ts mirror the Pydantic schemas defined in the backend src/agentscope/app/_router/_schema/__init__.py4-85
AgentData examples/web_ui/frontend/src/api/types.ts43-50 includes ContextConfig, ReActConfig, and InviteConfig examples/web_ui/frontend/src/api/types.ts23-39SessionConfig examples/web_ui/frontend/src/api/types.ts116-132 defines the model, TTS, and knowledge base settings for a specific chat.DirectoryEntry examples/web_ui/frontend/src/api/types.ts228-235 provides metadata for the sandboxed filesystem.Sources: examples/web_ui/frontend/src/api/types.ts3-235 src/agentscope/app/_router/_schema/__init__.py1-173 examples/web_ui/frontend/src/api/index.ts1-14
The frontend consumes agent events via a Server-Sent Events (SSE) stream. To ensure compatibility with the Web UI's rendering logic, the backend employs AGUIProtocolMiddleware to transform internal AgentEvent objects into the AGUI protocol format.
The middleware intercepts text/event-stream responses src/agentscope/app/middleware/_protocol/_base.py69-81 It iterates through the SSE frames, extracts the JSON data: payload, and converts it using _convert_to_protocol src/agentscope/app/middleware/_protocol/_base.py142-160
Key Mappings (Internal Event -> AGUI Protocol):
ReplyStartEvent -> RUN_STARTED src/agentscope/app/middleware/_protocol/_agui.py96-100TextBlockDeltaEvent -> TextMessageContentEvent src/agentscope/app/middleware/_protocol/_agui.py138-142ToolCallStartEvent -> ToolCallStartEvent src/agentscope/app/middleware/_protocol/_agui.py171-176ReplyEndEvent -> RUN_FINISHED or RUN_ERROR src/agentscope/app/middleware/_protocol/_agui.py102-112ThinkingBlockDeltaEvent -> ReasoningMessageContentEvent src/agentscope/app/middleware/_protocol/_agui.py160-164The following diagram shows how the AGUIProtocolMiddleware sits between the ChatService and the Frontend Client.
Diagram: AGUI Protocol Transformation
Sources: src/agentscope/app/middleware/_protocol/_agui.py44-228 tests/agui_protocol_test.py73-87 examples/web_ui/frontend/src/api/client.ts59-116 src/agentscope/event/_event.py26-68
The healthApi is unique because it allows probing a server before the connection settings are persisted in localStorage examples/web_ui/frontend/src/api/health.ts7-18
The backend get_health handler inspects the app.state to ensure all critical components (storage, message bus, chat service) are initialized src/agentscope/app/_router/_health.py64-80 If any lifespan component is missing, it returns a 503 Service Unavailable src/agentscope/app/_router/_health.py83-89
During the setup phase in SetupPage:
handleSubmit calls healthApi.check with these explicit values examples/web_ui/frontend/src/pages/setup/index.tsx78-82HealthResponse with a version string, the settings are saved to localStorage examples/web_ui/frontend/src/pages/setup/index.tsx88-90Sources: src/agentscope/app/_router/_health.py29-89 examples/web_ui/frontend/src/pages/setup/index.tsx67-96 examples/web_ui/frontend/src/api/health.ts7-19
Refresh this wiki