Quick Start

Build your first Agent in 10 minutes

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

1. 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
   
2. 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.

3. 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.

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

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

   Zhipu GLM-4

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

   Qwen

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

   DeepSeek

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

   Local (Ollama)

   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"]
   
5. Start the Server

   Start your agent server:

   python src/server.py
   

   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)

CLI (Coming Soon)

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:

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

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