Web UI Agent and Transports
Relevant source files
The following files were used as context for generating this wiki page:
The @mariozechner/pi-web-ui package provides a core Agent class and pluggable Transport layers for building AI chat interfaces. The Agent acts as a central state manager for the conversation, handling message history, tool execution, and streaming responses. The Transport components are responsible for the actual communication with AI provider APIs, offering flexibility in how requests are sent.
This system is designed to be platform-agnostic, enabling its use in standard web applications, browser extensions, and desktop applications. The separation of the agent's state logic from the communication logic (transports) allows developers to choose the appropriate communication strategy for their environment, such as calling APIs directly from the browser or proxying them through a backend server.
Sources: packages/web-ui/README.md
Agent Architecture
The Agent is the central class that manages the entire lifecycle of a chat session. It holds the conversation state, processes user inputs, orchestrates tool calls, and emits events that the UI can subscribe to for rendering updates.
Sources: packages/web-ui/README.md, packages/coding-agent/src/main.ts:1003-1033
Core Concepts
- State Management: The agent's state includes the system prompt, the selected model, message history, and available tools. This state is managed internally and updated as the conversation progresses.
- Event-Driven Updates: The agent uses a subscription model. UI components can subscribe to the agent to receive events like
message_start,message_update, andmessage_end. This allows for real-time updates, such as rendering streaming responses. - Tool Integration: The agent can be configured with a set of tools. It uses tool descriptions to construct a system prompt that instructs the AI model on how and when to use them.
The diagram below shows the class structure of the Agent and its relationship with the Transport layer.
This class diagram illustrates the Agent's composition, highlighting its dependency on a Transport implementation to handle communication.
Sources: packages/web-ui/README.md, packages/mom/src/agent.ts:400-412
Key Methods
The Agent class exposes several methods for controlling the chat session.
| Method | Description |
|---|---|
subscribe(callback) | Subscribes to agent events for UI updates. Returns an unsubscribe function. |
send(message) | Sends a user message to the AI. This initiates a new turn in the conversation. |
abort() | Aborts any ongoing AI request or tool execution. |
setModel(model) | Changes the active AI model for the session. |
setThinkingLevel(level) | Adjusts the reasoning level for models that support it. |
replaceMessages(messages) | Replaces the entire message history, useful for loading a previous session. |
reset() | Clears the message history and resets the agent to its initial state. |
Sources: packages/web-ui/README.md, packages/coding-agent/src/main.ts:1003-1033
Message Flow
When a user sends a message, the Agent orchestrates a series of steps, including calling the transport layer, handling tool calls, and emitting events.
The following sequence diagram shows the typical flow when a user sends a prompt.
This diagram shows how a user's message flows from the UI through the Agent and Transport to the AI provider, with events being streamed back to update the UI.
Sources: packages/web-ui/README.md, packages/mom/src/agent.ts:654-681
Transport Layer
Transports are responsible for the communication between the agent and the AI provider's API. The pi-web-ui package provides two main transport implementations to support different application architectures.
Sources: packages/web-ui/README.md
ProviderTransport
The ProviderTransport communicates directly with the AI provider's API from the client (e.g., the browser). This is the default and simplest mode of operation. It requires the user to provide API keys, which are typically stored in the browser's local storage.
This approach is suitable for web applications where users manage their own API keys and there is no backend server to proxy requests.
Sources: packages/web-ui/README.md, packages/web-ui/src/agent/transports/ProviderTransport.ts, packages/mom/src/agent.ts:408-412
AppTransport
The AppTransport proxies all AI requests through a custom backend server. Instead of calling the AI provider's API directly, it sends a request to a local endpoint (e.g., /api/proxy/stream), which then forwards the request to the AI provider.
This is useful for:
- Avoiding CORS issues in the browser.
- Keeping API keys secure on the server instead of exposing them on the client.
- Adding custom logic, caching, or logging on the backend.
Sources: packages/web-ui/README.md, packages/web-ui/src/agent/transports/AppTransport.ts
Transport Comparison
The following diagram illustrates the data flow for both ProviderTransport and AppTransport.
This diagram visually contrasts the direct API call of ProviderTransport with the proxied call of AppTransport.
The table below summarizes the key differences.
| Feature | ProviderTransport | AppTransport |
|---|---|---|
| Communication | Direct client-to-API | Client -> Proxy Server -> API |
| API Keys | Stored on the client (e.g., localStorage) | Stored on the proxy server |
| Use Case | Simple web apps, browser extensions where user provides keys. | Web apps with a backend, securing API keys. |
| CORS | May require a CORS proxy for some providers. | Solved by the backend proxy. |
Sources: packages/web-ui/README.md, packages/web-ui/src/agent/transports/AppTransport.ts, packages/web-ui/src/agent/transports/ProviderTransport.ts
Tool Integration
The agent's ability to use tools is configured via the system prompt. The pi-web-ui package includes a centralized module for generating tool descriptions that are injected into the system prompt. These descriptions guide the AI model on the purpose, usage, and parameters of each available tool.
For example, the JAVASCRIPT_REPL_TOOL_DESCRIPTION provides detailed instructions on how to use the JavaScript REPL, including available APIs, helper functions, and examples.
// Source: packages/web-ui/src/prompts/prompts.ts:8-11
export const JAVASCRIPT_REPL_TOOL_DESCRIPTION = (runtimeProviderDescriptions: string[]) => `# JavaScript REPL
## Purpose
Execute JavaScript code in a sandboxed browser environment with full Web APIs.
`;
This structured approach to defining tool behavior within the prompt is fundamental to how the agent framework enables reliable tool use. The agent constructs the final system prompt by combining a base prompt with these detailed tool descriptions.
Sources: packages/web-ui/src/prompts/prompts.ts, packages/coding-agent/src/main.ts:318-323
Conclusion
The Web UI Agent and Transport system provides a robust and flexible foundation for building sophisticated AI chat applications. By separating state management (Agent) from communication (Transport), it allows developers to adapt the architecture to different security and deployment models. The event-driven nature of the Agent ensures that UIs can be built to be responsive and reflect the real-time state of the AI's processing, including streaming text and tool execution steps.