Quick Start

Create your first AI Agent in 5 minutes.

Prerequisites

Node.js 16+ installed
npm or yarn package manager
A code editor (VS Code recommended)

Step 1: Install ZGI CLI

npm install -g @zgi/cli

Verify installation:

zgi --version

Step 2: Create a New Project

zgi init my-first-agent
cd my-first-agent

This creates a new project with:

Example agent code
Configuration files
Package dependencies
Development server setup

Step 3: Install Dependencies

npm install

Step 4: Create Your First Agent

Open src/agents/example.ts and replace with:

import { Agent } from '@zgi/core';

const agent = new Agent({
  name: 'assistant',
  model: 'gpt-4',
  systemPrompt: 'You are a helpful AI assistant that provides clear and concise answers.'
});

export default agent;

Step 5: Execute a Task

Create src/index.ts:

import agent from './agents/example';

async function main() {
  const result = await agent.execute({
    task: 'Introduce yourself and explain what you can help with'
  });

  console.log('Agent Response:');
  console.log(result.output);
  console.log('\nExecution Time:', result.executionTime, 'ms');
  console.log('Tokens Used:', result.tokensUsed);
}

main().catch(console.error);

Step 6: Run Your Agent

npm run dev

You should see output like:

Agent Response:
Hello! I'm an AI assistant powered by GPT-4. I'm here to help you with a wide range of tasks...

Execution Time: 1234 ms
Tokens Used: 156

What's Next?

Add Tools to Your Agent

import { Agent } from '@zgi/core';

const agent = new Agent({
  name: 'assistant',
  model: 'gpt-4',
  systemPrompt: 'You are a helpful AI assistant'
});

// Add a web search tool
agent.registerTool({
  name: 'web_search',
  description: 'Search the web for information',
  parameters: {
    query: {
      type: 'string',
      description: 'Search query',
      required: true
    }
  },
  handler: async (params) => {
    // Implement search logic
    return `Search results for: ${params.query}`;
  }
});

export default agent;

Create a Workflow

import { Workflow } from '@zgi/core';
import agent1 from './agents/researcher';
import agent2 from './agents/writer';

const workflow = new Workflow({
  name: 'content-creation'
});

workflow.addStep({
  name: 'research',
  agent: agent1,
  input: { topic: 'AI trends' }
});

workflow.addStep({
  name: 'write',
  agent: agent2,
  input: { research: '$research.output' },
  dependsOn: ['research']
});

export default workflow;

Query a Knowledge Base

import { KnowledgeBase } from '@zgi/core';

const kb = new KnowledgeBase({
  name: 'company-docs'
});

// Add documents
await kb.addDocument({
  path: 'docs/user-guide.pdf'
});

// Query
const results = await kb.query({
  query: 'How do I reset my password?',
  topK: 5
});

console.log(results);

Common Tasks

Task 1: Create Multiple Agents

zgi create agent researcher
zgi create agent writer
zgi create agent editor

Task 2: Add Environment Variables

Create .env:

OPENAI_API_KEY=sk_your_key_here
ZGI_API_KEY=zgi_sk_your_key_here
LOG_LEVEL=info

Task 3: Deploy to Production

# Build for production
npm run build

# Deploy to Vercel
vercel deploy

# Or deploy to your own server
npm run start

Project Structure

my-first-agent/
├── src/
│   ├── agents/
│   │   └── example.ts          # Your agent code
│   ├── tools/
│   │   └── example.ts          # Custom tools
│   ├── workflows/
│   │   └── example.ts          # Workflows
│   └── index.ts                # Entry point
├── .env                        # Environment variables
├── .env.example                # Example env file
├── package.json                # Dependencies
├── tsconfig.json               # TypeScript config
├── zgi.config.json             # ZGI config
└── README.md                   # Project readme

Useful Commands

# Development
npm run dev              # Start development server

# Building
npm run build            # Build for production
npm run start            # Start production server

# Testing
npm run test             # Run tests
npm run test:watch      # Run tests in watch mode

# Linting
npm run lint             # Lint code
npm run lint:fix         # Fix linting issues

# ZGI CLI Commands
zgi create agent         # Create new agent
zgi create tool          # Create new tool
zgi create workflow      # Create new workflow
zgi list agents          # List all agents
zgi models list          # List available models
zgi status              # Check API status

Troubleshooting

Issue: "API key not found"

Solution: Set your API key:

export ZGI_API_KEY=your-api-key
# or add to .env file

Issue: "Module not found"

Solution: Install dependencies:

npm install

Issue: "Port 3000 already in use"

Solution: Use a different port:

npm run dev -- --port 3001

Issue: "Agent execution timeout"

Solution: Increase timeout in zgi.config.json:

{
  "agents": {
    "timeout": 60000
  }
}

Next Steps

Guides - Learn about each module in detail
API Reference - Explore complete API documentation
Examples - See more examples and use cases
Deployment - Deploy your agent to production

Resources

Getting Help

If you get stuck:

Check the Guides for detailed explanations
Search the API Reference
Ask in the Community Forum
Contact Support

Congratulations! 🎉 You've created your first ZGI agent. Now explore the guides to learn more!