AG-UI

Connect your UI to a Harnest agent through POST /agui. Harnest adapts the AG-UI protocol to its shared runtime, so the same integration works with Google ADK and LangGraph. You can use CopilotKit or another client that supports Harnest’s AG-UI contract. Your agent stays in Harnest. Your frontend owns the conversation UI, browser tool handlers, and approval controls. Authentication, session ownership, request limits, concurrency, timeouts, and cancellation follow the same runtime policy as the neutral API.

What Harnest supports

Capability	What your UI receives or sends
Conversations	Client-created threads, streamed assistant text, and tool calls/results
Custom UI events	Application-named `CUSTOM` events from `await ui.emit(name, value)`
Shared state	Session-state patches from the client and authored graph state from ADK or LangGraph
Application context	Client context, tool descriptions, and forwarded properties available to your agent’s context providers
Browser tools	A handoff to a registered frontend handler, followed by resuming the original invocation
Human approval	An interrupt that your UI can approve, decline, or cancel
Structured results	Final output in `RUN_FINISHED.result`
External waits	A status event and response ID for polling work that remains in progress

Configure and author events

AG-UI is enabled by default. Set server.agui: false in config.yaml to remove POST /agui and its entry in /agent. Use true or an exact environment reference such as ${AGUI_ENABLED} to enable it at startup. Studio’s AG-UI transport component previews this source change; rebuild and restart after applying it. Studio also uses AG-UI internally to stream its builder’s progress. That authoring connection is independent of your agent’s server.agui setting. Disabling the agent endpoint does not disable Studio’s builder. Author display events inside async tools or graph nodes:

from harnest import ui
from harnest.agent import tool

@tool
async def show_status(message: str) -> dict:
    """Show a public progress message in the caller's interface.

    Args:
        message: Public display text, excluding credentials and private input.
    """
    await ui.emit("app.progress", {"message": message, "percent": 50})
    return {"status": "displayed"}

The frontend receives {"type":"CUSTOM","name":"app.progress","value":{"message":"...","percent":50}}. Register a handler for that name in your client to update a widget. Harnest sends JSON data; it does not execute HTML, JavaScript, or an arbitrary frontend component supplied by the agent. Playground displays named events as expandable JSON. UI events are separate from model history and session state. For durable shared state in a graph, return Event(state_delta={"progress": 50}) from a node; Harnest emits the corresponding STATE_DELTA. See the UI API for payload limits, lifetime, and native transport behavior.

Choose your next step

Connect a client

Start a thread, send a turn, handle failures, and cancel a run.

Share state and context

Pass application data to your agent and keep your UI in sync.

Handle interactions

Resume human approvals, browser tools, and external waits.

Try CopilotKit

Run the local React demo and test both agent frameworks.

Current boundaries

The AG-UI endpoint accepts text input. For typed or media input, use the neutral API and multimodal contracts. Pending approvals and client-tool exchanges belong to the serving process holding the suspended invocation. Resume them on that process; they are not portable across restarts or replicas. Client context and advertised tools do not grant authority or register executable capabilities.

Overview

Get started

Harnest Studio

Guides

API reference

What Harnest supports

Configure and author events

Choose your next step

Connect a client

Share state and context

Handle interactions

Try CopilotKit

Current boundaries

​What Harnest supports

​Configure and author events

​Choose your next step

Connect a client

Share state and context

Handle interactions

Try CopilotKit

​Current boundaries

What Harnest supports

Configure and author events

Choose your next step

Current boundaries