Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.ag-kit.dev/llms.txt

Use this file to discover all available pages before exploring further.

Build a complete Agent application from scratch in just 10 minutes. You’ll create an Agent, start the service, and integrate it into a web application.

​
Prerequisites

  • API key for your chosen LLM provider
  • Basic programming knowledge
  • Node.js 20+ installed (required for frontend development)
1

Create Project Structure

Create a new directory and initialize the project:
2

Create Your Agent

Create your agent file with a simple OpenAI-based agent:
3

Create Server

Create your server file to run your agent:
4

Configure Environment

Create a .env file with your API key:AG-Kit supports multiple LLM providers through OpenAI-compatible APIs. Choose your preferred model:
OPENAI_API_KEY=sk-your_openai_api_key
OPENAI_MODEL=gpt-4o-mini
# OPENAI_BASE_URL is optional for OpenAI
Add development scripts:
5

Start the Server

Start your agent server:You should see:
✓ Server running at http://localhost:9000
6

Test with cURL

Test your agent with a simple request:
curl --request POST \
  --url http://localhost:9000/send-message \
  --header 'Accept: text/event-stream' \
  --header 'Content-Type: application/json' \
  --data '{
    "messages": [
      {
        "role": "user",
        "content": "Hello, how are you?"
      }
    ],
    "conversationId": "test-conversation"
  }'
You should get a streaming response with events like:
data: {"type":"text","content":"Hello"}

data: {"type":"text","content":"!"}

data: {"type":"text","content":" I"}

data: {"type":"text","content":"'m"}

data: {"type":"text","content":" doing"}

data: {"type":"text","content":" well"}

data: {"type":"text","content":","}

data: {"type":"text","content":" thank"}

data: {"type":"text","content":" you"}

data: {"type":"text","content":" for"}

data: {"type":"text","content":" asking"}

data: {"type":"text","content":"."}

data: {"type":"text","content":" How"}

data: {"type":"text","content":" can"}

data: {"type":"text","content":" I"}

data: {"type":"text","content":" help"}

data: {"type":"text","content":" you"}

data: {"type":"text","content":" today"}

data: {"type":"text","content":"?"}

data: [DONE]
7

Create Frontend

Create a new directory for the frontend and set it up:
# Create frontend directory (in a separate terminal/location)
mkdir my-agent-frontend
cd my-agent-frontend

# Initialize npm project
npm init -y

# Install dependencies
npm install react react-dom @ag-kit/example-ui-web-shared @ag-kit/ui-react zod
npm install -D typescript @types/react @types/react-dom vite @vitejs/plugin-react
Create index.html:
<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>My Agent Chat</title>
</head>
<body>
  <div id="root"></div>
  <script type="module" src="/src/main.tsx"></script>
</body>
</html>
Create src/main.tsx:
import React from 'react';
import { createRoot } from 'react-dom/client';
import { AgKitChat } from '@ag-kit/example-ui-web-shared';
import { useChat, clientTool } from '@ag-kit/ui-react';
import z from 'zod';
import '@ag-kit/example-ui-web-shared/style.css';

const suggestions = [
  { id: "1", text: "Hello, how are you?", category: "Greeting" },
  { id: "2", text: "What can you help me with?", category: "Help" },
  { id: "3", text: "Tell me a joke", category: "Fun" },
];

function App() {
  const { sendMessage, uiMessages, streaming } = useChat({
    url: 'http://localhost:9000/send-message',
    clientTools: [
      clientTool({
        name: "alert",
        description: "Alert the user",
        parameters: z.object({ message: z.string() }),
        handler: async ({ message }) => {
          await new Promise((resolve) => setTimeout(resolve, 1000));
          alert(message);
          return "done";
        },
      }),
    ],
  });

  return (
    <AgKitChat
      title="My First Agent"
      suggestions={suggestions}
      welcomeMessage="Welcome! Try selecting a suggestion or type your own message."
      uiMessages={uiMessages}
      onMessageSend={sendMessage}
      status={streaming ? "streaming" : "idle"}
    />
  );
}

const root = createRoot(document.getElementById('root')!);
root.render(<App />);
Create vite.config.ts:
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
  server: { port: 5173 }
});
Add to package.json:
{
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  }
}
Start the frontend:
npm run dev
Open http://localhost:5173 in your browser!For more UI component options, see the UI Components reference.
8

Try It Out

Test your agent with these messages:
  1. “Hello, how are you?” - Basic greeting
  2. “What can you help me with?” - Capability exploration
  3. “Tell me about AI” - Knowledge demonstration
  4. “Write a short poem” - Creative task
  5. “Alert me with a message” - Test the custom tool (TypeScript frontend only)

​
What You’ve Built

Congratulations! You’ve created:
  1. An Agent with custom tools and state management
  2. A Backend Service that handles Agent requests
  3. A Frontend Application with real-time chat

​
Architecture

​
Next Steps

Now that you have a working Agent, explore more features:

Core Concepts

Understand Agents, State, and Tools

Agent Reference

Complete Agent API documentation

Tools

Add more capabilities with tools

Run Agent

Server configuration and deployment

UI Components

Build custom user interfaces

Deployment

Deploy to production

​
Troubleshooting

  • Check that port 9000 is not in use
  • Verify your .env file has the API key
  • Check console for error messages
  • Ensure the Agent server is running
  • Check the server URL in your frontend configuration
  • Verify CORS settings in server config
  • Check your OpenAI API key is valid
  • Verify you have API credits
  • Check server logs for errors

​
Learn More