AG-UI

Connect an endpoint

Install @ag-ui/client@1.0.3 plus Ghost's React view dependencies. Your server must expose AG-UI, not arbitrary SSE. Create one client and runtime per conversation owner; the application supplies endpoint authentication and thread identity.

12345678910111213141516171819202122232425import { useState } from "react";
import { HttpAgent } from "@ag-ui/client";
import { createAgUiRuntime } from "@ghost-ui/core/chat-adapter-ag-ui";
import { useChatRuntimeStore } from "@ghost-ui/core/chat-runtime-react";
import { Button } from "@ghost-ui/core/components/button";
import { Message, MessageBody } from "@ghost-ui/core/components/message";
import { MessageParts } from "@ghost-ui/core/components/message-parts";
export function AgUiConversation({ url, threadId }: { url: string; threadId: string }) {
  const [owner] = useState(() => {
    const client = new HttpAgent({ url, threadId });
    return { client, store: createAgUiRuntime(client, { identity: { threadId, revision: 0 } }) };
  });
  const runtime = useChatRuntimeStore(owner.store);
  const [error, setError] = useState<unknown>();
  return <>
    {runtime.messages.map(message => <Message key={message.id} actor={message.actor}><MessageBody>
      <MessageParts parts={message.parts} />
    </MessageBody></Message>)}
    <Button disabled={runtime.capabilities.send.support !== "supported" || !runtime.capabilities.send.available}
      onClick={() => { setError(undefined); void Promise.resolve().then(() => runtime.controller.send({ text: "Review the brief", attachments: [] })).catch(setError); }}>Review</Button>
    {runtime.capabilities.stop.support === "supported" && runtime.capabilities.stop.available &&
      <Button onClick={() => { void Promise.resolve().then(() => runtime.controller.stop?.()).catch(setError); }}>Stop</Button>}
    {(error || runtime.controller.error) ? <p role="alert">The request could not complete.</p> : null}
  </>;
}

Mount with key={threadId + ":" + revision} when replacing its owner. useState intentionally creates the client once; changing props does not retarget it. Use a caller-created HttpAgent with headers or custom fetch when authentication needs application context.

Shared state and advanced runs

The native client reconstructs messages and client.state; Ghost does not parse a second event stream or mirror that store. The bridge shares one native subscription across its subscribers and releases it when the last subscriber leaves. A native state notification also publishes a Ghost update, so read and validate owner.client.state alongside the runtime in an application panel.

createAgUiRuntime(client, { identity, run: native => native.runAgent({ forwardedProps, context, tools }) }) can customize a run using the actual client type. Schema validation, tool execution and access policy stay with the application. Use native pendingInterrupts and runAgent({ resume }) for protocol-specific resumption; an interrupt is not automatically a boolean approval.

Boundaries and failures

Text send adds a native user message before running; if the run fails, that message remains native history for deliberate retry/reconciliation. Stop calls abortRun; it is a cancellation request. Ghost's generic retry/edit/tool approval are not guessed from AG-UI events. Use native commands or a deliberate application adapter when equivalent semantics exist.

For protocol schemas, state events and tools see the AG-UI client reference. Pydantic AI, Agno and CrewAI can expose this same protocol.