Quick Start

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)
Python 3.11+ installed
pip or uv package manager
Basic Python 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
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install AG-Kit dependencies:

pip install ag_kit_py

Create Your Agent

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

import os
from langchain_core.messages import AIMessage, SystemMessage, convert_to_openai_messages
from langchain_core.messages.ai import add_ai_message_chunks
from langchain_core.runnables import RunnableConfig
from langgraph.checkpoint.memory import MemorySaver
from langgraph.config import get_stream_writer
from langgraph.graph import END, START, MessagesState, StateGraph
from langgraph.graph.state import CompiledStateGraph

from ag_kit_py.agents.langgraph import LangGraphAgent
from ag_kit_py.providers import create_provider_from_env
from ag_kit_py.server import AgentCreatorResult


def chat_node(state: dict, config: RunnableConfig = None) -> dict:
    """Generate AI response with streaming support."""
    writer = get_stream_writer()
    try:
        provider = create_provider_from_env("openai")
        chat_model = provider.get_langchain_model()

        if config is None:
            config = RunnableConfig(recursion_limit=25)

        system_message = SystemMessage(content="You are a helpful assistant. Be friendly and concise.")
        messages = [system_message, *convert_to_openai_messages(state["messages"])]

        chunks = []
        for chunk in chat_model.stream(messages, config):
            writer({"messages": [chunk]})
            chunks.append(chunk)

        if chunks:
            from langchain_core.messages import AIMessageChunk
            ai_chunks = [
                chunk if isinstance(chunk, AIMessageChunk) else AIMessageChunk(content=str(chunk))
                for chunk in chunks
            ]
            merged_message = add_ai_message_chunks(*ai_chunks)
            return {"messages": [merged_message]}
        return {"messages": []}
    except Exception as e:
        return {"messages": [AIMessage(content=f"Error: {str(e)}")]}


def build_chat_workflow() -> CompiledStateGraph:
    """Build LangGraph workflow."""
    graph = StateGraph(MessagesState)
    memory = MemorySaver()

    graph.add_node("ai_response", chat_node)
    graph.set_entry_point("ai_response")
    graph.add_edge(START, "ai_response")
    graph.add_edge("ai_response", END)

    return graph.compile(checkpointer=memory)


def create_my_agent() -> AgentCreatorResult:
    """Create agent instance."""
    workflow = build_chat_workflow()
    agent = LangGraphAgent(
        name="my-first-agent",
        description="A helpful AI assistant",
        graph=workflow,
    )
    return {"agent": agent}

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

Create Server

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

from ag_kit_py.server import AgentServiceApp
from src.agent import create_my_agent

if __name__ == "__main__":
    AgentServiceApp().run(
        create_my_agent,
        port=9000,
        enable_openai_endpoint=True,
    )
    print("Server running at http://localhost:9000")

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:The server can be run directly with Python:

python src/server.py

Or add a pyproject.toml for project configuration:

[project]
name = "my-first-agent"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = ["ag_kit_py"]

Start the Server

Start your agent server:

python src/server.py

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)

The AG-Kit CLI will provide a streamlined setup experience:

# Coming soon
agkit create my-first-agent
cd my-first-agent
python src/server.py

Stay tuned for updates!

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

Ensure Python 3.11+ is installed
Verify virtual environment is activated
Check that dependencies are installed correctly
Review Python error messages in console

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

Getting Started

Building Agents

Deploying Agents

Building Agent Apps

Open Protocols

Community

Prerequisites

What You’ve Built

Architecture

Next Steps

Core Concepts

Agent Reference

Tools

Run Agent

UI Components

Deployment

Troubleshooting

Learn More

Getting Started

Building Agents

Deploying Agents

Building Agent Apps

Open Protocols

Community

​Prerequisites

​What You’ve Built

​Architecture

​Next Steps

Core Concepts

Agent Reference

Tools

Run Agent

UI Components

Deployment

​Troubleshooting

​Learn More

Prerequisites

What You’ve Built

Architecture

Next Steps

Troubleshooting

Learn More