Quick Start - AG-Kit Documentation

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)
npm or yarn package manager
Basic TypeScript knowledge

Manual Setup
CLI (Coming Soon)

Create Project Structure

Create a new directory and initialize the project:

mkdir my-first-agent
cd my-first-agent
npm init -y
npm pkg set type=module

Install AG-Kit dependencies:

npm install @ag-kit/agents @ag-kit/adapter-llamaindex @ag-kit/server @llamaindex/workflow @llamaindex/openai llamaindex zod
npm install -D typescript tsx nodemon dotenv @types/node

Initialize TypeScript:

npx tsc --init

Create Your Agent

Create your agent file with a simple OpenAI-based agent:Create src/agent.ts:

import 'dotenv/config';
import { agent } from "@llamaindex/workflow";
import { OpenAI } from "@llamaindex/openai";
import { createMemory } from "llamaindex";

class LLM extends OpenAI {
  constructor(config: ConstructorParameters<typeof OpenAI>[0]) {
    super(config);
  }
  get metadata() {
    const metadata = super.metadata;
    metadata.contextWindow = 64 * 1024;
    return metadata;
  }
}

export function createMyAgent() {
  const llm = new LLM({
    model: process.env.OPENAI_MODEL || "gpt-4o-mini",
    apiKey: process.env.OPENAI_API_KEY,
    baseURL: process.env.OPENAI_BASE_URL
  });

  const workflow = agent({
    llm,
    name: 'my-first-agent',
    description: 'A helpful AI assistant',
    systemPrompt: 'You are a helpful assistant. Be friendly and concise.',
    memory: createMemory({
      tokenLimit: 100 * 1024
    })
  });

  return workflow;
}

For more advanced Agent configuration options, see the LlamaIndex Agent reference.

Create Server

Create your server file to run your agent:Create src/server.ts:

import { run } from '@ag-kit/server';
import { LlamaIndexAgent } from '@ag-kit/adapter-llamaindex';
import { createMyAgent } from './agent.js';

// Start the server
run({
  createAgent: () => {
    return {
      agent: new LlamaIndexAgent({
        workflowFactory: createMyAgent,
      })
    };
  },
  cors: true,
  port: 9000,
});
console.log('Server running at http://localhost:9000');

Note: When using ES modules, you must use the .js extension in imports.For more server configuration options, see Run Agent.

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
Zhipu GLM-4
Qwen
DeepSeek
Local (Ollama)

OPENAI_API_KEY=sk-your_openai_api_key
OPENAI_MODEL=gpt-4o-mini
# OPENAI_BASE_URL is optional for OpenAI

OPENAI_API_KEY=your_zhipu_api_key
OPENAI_MODEL=glm-4-flash
OPENAI_BASE_URL=https://open.bigmodel.cn/api/paas/v4/

OPENAI_API_KEY=sk-your_qwen_api_key
OPENAI_MODEL=qwen-plus
OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

OPENAI_API_KEY=sk-your_deepseek_api_key
OPENAI_MODEL=deepseek-chat
OPENAI_BASE_URL=https://api.deepseek.com/v1

OPENAI_API_KEY=ollama
OPENAI_MODEL=llama3.2
OPENAI_BASE_URL=http://localhost:11434/v1

Add development scripts:Add to package.json:

{
  "scripts": {
    "dev": "nodemon --exec tsx src/server.ts",
    "build": "tsc",
    "start": "node dist/server.js"
  }
}

Start the Server

Start your agent server:

npm run dev

You should see:

✓ Server running at http://localhost:9000

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]

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.

Try It Out

Test your agent with these messages:

“Hello, how are you?” - Basic greeting
“What can you help me with?” - Capability exploration
“Tell me about AI” - Knowledge demonstration
“Write a short poem” - Creative task
“Alert me with a message” - Test the custom tool (TypeScript frontend only)

What You’ve Built

Congratulations! You’ve created:

An Agent with custom tools and state management
A Backend Service that handles Agent requests
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

Server won't start

Check that port 9000 is not in use
Verify your .env file has the API key
Check console for error messages

Frontend can't connect

Ensure the Agent server is running
Check the server URL in your frontend configuration
Verify CORS settings in server config

Agent not responding

Check your OpenAI API key is valid
Verify you have API credits
Check server logs for errors

Setup errors

Learn More

Core Concepts - Deep dive into AG-Kit architecture
Examples - More example applications
API Reference - Complete API documentation
Community - Join our Discord and GitHub

Documentation Index

​Prerequisites

​What You’ve Built

​Architecture

​Next Steps