Astro

Build a Better Agent app in Astro with a typed client, useAgent(...), durable conversations, approvals, client tools, and stream recovery.

Create the app

Start with a normal Better Agent server module.

src/better-agent/server.ts

import { betterAgent, defineAgent } from "@better-agent/core";
import { createOpenAI } from "@better-agent/providers/openai";

const openai = createOpenAI({
  apiKey: process.env.OPENAI_API_KEY,
});

const assistant = defineAgent({
  name: "assistant",
  model: openai.text("gpt-5-mini"),
  instruction: "You are a concise assistant. Keep replies short and natural.",
});

const app = betterAgent({
  agents: [assistant],
  baseURL: "/agents",
  secret: "dev-secret",
});

export default app;

Mount the route

Create an Astro API route and forward the request to Better Agent.

src/pages/agents/[...path].ts

import type { APIRoute } from "astro";
import app from "../../better-agent/server";

export const ALL: APIRoute = async ({ request }) => app.handler(request);

Keep baseURL and the route path aligned. If the app uses baseURL: "/agents", the route should live under /agents.

Create the typed client

Import the server app type so agent names, context, tools, and output stay aligned.

src/better-agent/client.ts

import { createClient } from "@better-agent/client";
import type app from "./server";

export const client = createClient<typeof app>({
  baseURL: "/agents",
  secret: "dev-secret",
});

Build a basic chat

In Astro, the interactive chat usually lives in a hydrated island.

src/components/chat.tsx

import { useState } from "react";
import { useAgent } from "@better-agent/client/react";
import { client } from "../better-agent/client";

export function Chat() {
  const [input, setInput] = useState("");
  const { messages, status, error, sendMessage, stop } = useAgent(client, {
    agent: "assistant",
  });

  return (
    <div>
      <form
        onSubmit={async (event) => {
          event.preventDefault();
          const value = input.trim();
          if (!value) return;
          setInput("");
          await sendMessage(value);
        }}
      >
        <input
          value={input}
          onChange={(event) => setInput(event.target.value)}
          placeholder="Ask something..."
        />
        <button type="submit" disabled={status !== "ready"}>
          Send
        </button>
        <button
          type="button"
          onClick={() => stop()}
          disabled={status !== "submitted" && status !== "streaming"}
        >
          Stop
        </button>
      </form>

      <p>Status: {status}</p>
      {error && <p>{error.message}</p>}

      <ul>
        {messages.map((message) => (
          <li key={message.localId}>
            {message.role}: {message.parts.map((part) => part.type === "text" ? part.text : "").join("")}
          </li>
        ))}
      </ul>
    </div>
  );
}

Mount the island from an Astro page:

src/pages/index.astro

---
import { Chat } from "../components/chat";
---

<html lang="en">
  <body>
    <Chat client:load />
  </body>
</html>

Keep one conversation across refreshes

When you use server-managed persistence, give the chat a conversationId, hydrate the saved transcript, and resume the active stream on page load.

src/components/chat.tsx

export function Chat() {
  const agent = useAgent(client, {
    agent: "assistant",
    conversationId: "support-demo",
    hydrateFromServer: true,
    resume: true,
  });

  return (
    <div>
      <p>Status: {agent.status}</p>
      <p>Conversation: {agent.conversationId}</p>
      <p>Messages: {agent.messages.length}</p>
    </div>
  );
}

Use resume: true when you want the hook to reconnect to the active conversation stream on init. Use resume: { streamId, afterSeq } when you already track a stream cursor yourself.

For resume: true, Better Agent needs persistence to find the active stream for a conversation. With only a StreamStore, use resume: { streamId }. Add runtime state to enable conversation-based resume. See Persistence.

Pass context and tune a run

Use hook options for stable per-chat defaults like context, modelOptions, and delivery.

src/components/billing-chat.tsx

import { useAgent } from "@better-agent/client/react";
import { client } from "../better-agent/client";

export function BillingChat() {
  const agent = useAgent(client, {
    agent: "assistant",
    context: {
      userId: "user_123",
      plan: "pro",
    },
    modelOptions: {
      reasoningEffort: "medium",
    },
    delivery: "stream",
  });

  return <button onClick={() => agent.sendMessage("Summarize my plan.")}>Ask</button>;
}

Add browser-side tools

src/components/tools-chat.tsx

import { useAgent } from "@better-agent/client/react";
import { client } from "../better-agent/client";

export function ToolsChat() {
  const agent = useAgent(client, {
    agent: "assistant",
    toolHandlers: {
      show_confetti: async ({ color }) => {
        console.log("Confetti color:", color);
        return { shown: true };
      },
    },
  });

  return <button onClick={() => agent.sendMessage("Celebrate the upgrade.")}>Run</button>;
}

Use onToolCall instead when you want one per-run function instead of a handler map.

Handle approvals in the UI

When a tool needs human approval, useAgent(...) exposes pending requests and a helper to answer them.

src/components/approvals-chat.tsx

import { useAgent } from "@better-agent/client/react";
import { client } from "../better-agent/client";

export function ApprovalsChat() {
  const { pendingToolApprovals, approveToolCall } = useAgent(client, {
    agent: "assistant",
  });

  return (
    <div>
      {pendingToolApprovals.map((approval) => (
        <div key={approval.toolCallId}>
          <div>{approval.toolName}</div>
          <pre>{JSON.stringify(approval.meta, null, 2)}</pre>

          <button
            onClick={() =>
              approveToolCall({
                toolCallId: approval.toolCallId,
                decision: "approved",
              })
            }
          >
            Approve
          </button>

          <button
            onClick={() =>
              approveToolCall({
                toolCallId: approval.toolCallId,
                decision: "denied",
              })
            }
          >
            Deny
          </button>
        </div>
      ))}
    </div>
  );
}

Watch events and final results

Use callbacks when you want analytics, data parts, disconnect handling, or typed final output.

src/components/observability-chat.tsx

import { useAgent } from "@better-agent/client/react";
import { client } from "../better-agent/client";

export function ObservabilityChat() {
  useAgent(client, {
    agent: "assistant",
    onResponse: (response) => {
      console.log("HTTP status", response.status);
    },
    onEvent: (event) => {
      console.log("Event", event.type);
    },
    onData: (part) => {
      console.log("Data part", part.data);
    },
    onDisconnect: ({ error, streamId }) => {
      console.error("Stream disconnected", streamId, error);
    },
    onError: (error) => {
      console.error("Run failed", error);
    },
    onFinish: ({ finishReason, response }) => {
      console.log("Finished", finishReason);
      console.log(response?.output);
    },
  });

  return null;
}

If your agent has a default outputSchema, onFinish also receives typed structured output.

Shape local replay

Use these options when you want to control how local message history is turned back into model input.

src/components/local-state-chat.tsx

import { useAgent } from "@better-agent/client/react";
import { client } from "../better-agent/client";

export function LocalStateChat() {
  const agent = useAgent(client, {
    agent: "assistant",
    initialMessages: [
      {
        role: "assistant",
        parts: [{ type: "text", text: "Welcome back." }],
      },
    ],
    prepareMessages: ({ messages, input }) => {
      return [
        {
          type: "message",
          role: "system",
          content: `Reuse the important context from the last ${messages.length} local messages.`,
        },
        { type: "message", role: "user", content: [{ type: "text", text: String(input) }] },
      ];
    },
  });

  return (
    <div>
      <button onClick={() => agent.regenerate()}>Regenerate last turn</button>
      <button
        onClick={() =>
          agent.setMessages((messages) => messages.filter((message) => message.role !== "assistant"))
        }
      >
        Hide assistant messages
      </button>
    </div>
  );
}

Use retryMessage(localId) when you want to rerun one earlier user turn, and resumeStream(...) or resumeConversation(...) when you want to reconnect manually instead of using resume on init.

Optimistic UI

Use optimistic insertion when you want the user message to appear in the chat before the request finishes.

src/components/optimistic-chat.tsx

import { useAgent } from "@better-agent/client/react";
import { client } from "../better-agent/client";

export function OptimisticChat() {
  const agent = useAgent(client, {
    agent: "assistant",
    optimisticUserMessage: {
      enabled: true,
      onError: "remove",
    },
    onOptimisticUserMessageError: ({ error }) => {
      console.error("Optimistic message failed", error);
    },
  });

  return (
    <div>
      <button onClick={() => agent.clearError()}>Clear error</button>
      <button onClick={() => agent.reset()}>Reset chat</button>
    </div>
  );
}

Astro

On this page