| title | Quickstart |
|---|---|
| description | Build, run, and test your first Tilde agent. |
Building chat directly into your own frontend? Follow Frontend chat with your own authentication to set up identities, an organization proxy token, and a same-origin streaming proxy.
Tilde is designed for agents to build more agents. Choose **Agentic workflow** to work through your coding agent, or **For humans** to follow the same steps yourself.This guide shows you how to build and test a signed ChatKit endpoint using Next.js and the Vercel AI SDK. A completed Hello World agent is available for reference.
Connect the client where your coding agent runs to Tilde's global MCP server. <Card title="Connect your coding agent" icon="plug" href="/connect-your-agent" horizontal>
Choose your client and complete its setup.
</Card>
</Step>
<Step title="Ask it to build the example">
Send this prompt to the connected agent.
<Prompt description="Build the Hello World agent" icon="sparkles" actions={["copy", "cursor"]}>
Start by reading https://trytilde.ai/llms.txt and use https://trytilde.ai/docs/llms.txt to open the production-hosted agent guides. Use https://github.com/trytilde/examples/tree/main/hello-world-agent only as a reference and create the app and files in my project. Explain the route before changing it, then ask what I want my agent to do. Keep Tilde webhook verification, ChatKit history, and server-side secrets intact. Register the local endpoint at /api/hello-world as a ChatKit agent, save the returned Tilde API key and webhook signing key in .env.local, sign in with tilde auth login, run the app through a Tilde Dev Tunnel, and test it in ChatKit workspace.
Use the <span style={{ display: "inline-flex", alignItems: "center", verticalAlign: "middle", marginBlock: 0, marginInline: "0.2rem", cursor: "default", textDecoration: "none" }}><img src="https://api.trytilde.ai/deploy-button.svg" alt="Deploy with Tilde" noZoom style={{ display: "block", width: "128px", height: "auto", margin: 0, pointerEvents: "none", userSelect: "none" }} /></span> button in a project's `README.md`, or import the file manually. See [Terraform](/terraform) to learn more.
<Steps>
<Step title="Create the app">
You need Node.js 22 or newer, pnpm 10, a Tilde account, and an OpenAI API key.
```bash
pnpm create next-app@16.2.12 hello-world-agent --ts --eslint --app --no-src-dir --no-tailwind --use-pnpm
cd hello-world-agent
pnpm add @ai-sdk/openai ai @trytilde/sdk @trytilde/sdk-vercel-ai-node
pnpm add -D openbot
touch .env.local
```
</Step>
<Step title="Create the agent endpoint">
Create `app/api/hello-world/route.ts`. You can compare it with the [completed route](https://github.com/trytilde/examples/blob/main/hello-world-agent/app/api/hello-world/route.ts) in the examples repository.
```typescript app/api/hello-world/route.ts
import { openai } from "@ai-sdk/openai";
import {
chatKitEndpoint,
convertToAiSdkMessages,
createClient,
} from "@trytilde/sdk-vercel-ai-node";
import {
consumeStream,
convertToModelMessages,
streamText,
} from "ai";
export const POST = chatKitEndpoint({
client: createClient({
apiKey: process.env.TILDE_API_KEY!,
orgId: process.env.TILDE_ORG_ID!,
teamId: process.env.TILDE_TEAM_ID!,
}),
webhookSigningKey: process.env.TILDE_WEBHOOK_SIGNING_KEY!,
async handler(request, context) {
const history = await context.session.history();
const messages = await convertToAiSdkMessages({
messages: [...history.items, ...context.messages],
chatkit: context.chatkit,
});
const result = streamText({
abortSignal: request.signal,
messages: await convertToModelMessages(messages),
model: openai("gpt-5.5"),
system: "You are a helpful assistant. Keep your answers concise.",
});
return result.toUIMessageStreamResponse({
consumeSseStream: consumeStream,
originalMessages: messages,
});
},
});
```
Change the `system` instruction to change what your agent does. Keep the signed `chatKitEndpoint` wrapper and ChatKit history conversion.
</Step>
<Step title="Create the agent in Tilde">
1. Open Tilde, select your workspace, and go to **ChatKit** → **Agents**.
2. Click **Register agent** and name it `Hello World`.
3. Enable **Local running endpoint** and enter `api/hello-world` as the endpoint path.
4. Click **Register**, then copy the one-time API key and webhook signing key.
</Step>
<Step title="Configure the environment">
Set these values in `.env.local`.
Find the organization and team IDs under **Settings** → **Team settings** → **General information**.
```dotenv .env.local
TILDE_API_KEY=
TILDE_ORG_ID=
TILDE_TEAM_ID=
TILDE_WEBHOOK_SIGNING_KEY=
```
</Step>
<Step title="Run your app through a Dev Tunnel">
Sign in to Tilde before opening the tunnel. The login flow asks you to select the workspace containing **Hello World**. Then start your app's development process through the tunnel. Replace `pnpm dev` with the command you normally use to run your app locally.
The tunnel gives your local agent a public HTTPS endpoint, allowing Tilde to deliver messages, webhooks, and tool invocations while you develop. For ChatKit, `chatKitEndpoint` verifies Tilde's webhook signature and rejects requests without a valid signature.
```bash
pnpm exec openbot auth login
pnpm exec openbot tunnel -- pnpm dev
```
<Warning>
The Dev Tunnel exposes every page and API route served by your local app—not only the agent endpoint—to the public internet. Disable any unneeded or unsecured routes before starting the tunnel, or protect them with authentication and use the tunnel with caution.
</Warning>
</Step>
<Step title="Test the agent">
Open [**ChatKit workspace**](https://api.trytilde.ai/chatkit-workspace), select the workspace where you registered **Hello World**, start a session with the agent, and send:
```text
Say hello in one sentence.
```
</Step>
</Steps>