TechSetupGuides
IntermediateCoze StudioAIByteDanceReactTypeScriptGoDockerMicroservicesRAGLLMOpenAIAgent DevelopmentNo-CodeWorkflows

Coze Studio: AI Agent Development Platform Setup

Complete setup guide for Coze Studio - ByteDance's open-source all-in-one AI agent development platform. Create, debug, and deploy AI agents with visual no-code/low-code tools. Includes Docker installation, model configuration, workflow builder, RAG knowledge bases, and plugin development with React, TypeScript, Go, and microservices architecture.

  1. Step 1

    System Prerequisites

    Before installing Coze Studio, ensure your system meets the minimum requirements and has Docker installed. Coze Studio is a containerized microservices platform that requires Docker and Docker Compose to run. The platform is designed to be lightweight but provides enterprise-grade AI agent development capabilities.

    # Check minimum requirements
# CPU: 2 cores minimum
# RAM: 4GB minimum

# Verify Docker is installed
docker --version  # Docker 20.10+
docker-compose --version  # Docker Compose 2.0+

# Ensure Docker service is running
sudo systemctl status docker  # Linux
# or check Docker Desktop is running (macOS/Windows)
    ⚠ Heads up: Coze Studio requires Docker and Docker Compose to be installed and running before deployment. The initial deployment may take time retrieving images depending on your network speed.
  2. Step 2

    Clone the Coze Studio Repository

    Clone the official Coze Studio repository from GitHub. This contains the complete platform including frontend (React + TypeScript), backend (Go microservices), and Docker configurations.

    git clone https://github.com/coze-dev/coze-studio.git
cd coze-studio
  3. Step 3

    Deploy with Docker (macOS/Linux)

    For macOS and Linux systems, use the provided Makefile to deploy Coze Studio. The make web command handles environment setup and orchestrates all Docker containers including the web server, database, and microservices.

    # Deploy all services using make
make web

# Wait for deployment to complete
# You'll see "Container coze-server Started" when ready
  4. Step 4

    Deploy with Docker (Windows)

    Windows users should use docker-compose directly. First, copy the environment template, then start all services using docker-compose. The environment file contains configuration for all microservices.

    # Copy environment template
cp ./docker/.env.example ./docker/.env

# Start all services
docker compose -f ./docker/docker-compose.yml up

# Or run in detached mode (background)
docker compose -f ./docker/docker-compose.yml up -d
  5. Step 5

    Verify Deployment

    After the containers start, verify that the deployment was successful by checking the container status and logs. You should see 'Container coze-server Started' in the output when all services are ready.

    # Check container status
docker ps

# View logs (if running in detached mode)
docker compose -f ./docker/docker-compose.yml logs -f

# Look for the success message:
# "Container coze-server Started"
    ⚠ Heads up: Initial deployment may take several minutes to download and start all Docker images. If you encounter startup failures, consult the FAQ section in the official documentation.
  6. Step 6

    Register Your Account

    Once the server is running, navigate to the registration page to create your first admin account. This account will have full access to the platform including model management, agent creation, and system configuration.

    # Open the registration page
# Navigate to: http://localhost:8888/sign

# Create your username and password
# This will be your admin account for the platform
  7. Step 7

    Configure Model Services (Required)

    After registration, you must configure at least one model service before you can create agents or workflows. Coze Studio supports OpenAI, Volcengine, and other LLM providers. Without this configuration, model selection won't function when building agents.

    # Navigate to Model Management
# URL: http://localhost:8888/admin/#model-management

# Add your first model:
# 1. Click "Add Model"
# 2. Select provider (OpenAI, Volcengine, etc.)
# 3. Enter your API key
# 4. Configure model settings (GPT-4, GPT-3.5, etc.)
# 5. Save configuration
    ⚠ Heads up: Model configuration is mandatory. The image version must be ≥0.5.0 for model management features. Keep your API keys secure and never commit them to version control.
  8. Step 8

    Access Coze Studio

    With your account registered and models configured, you can now access the main Coze Studio interface. The platform provides a visual drag-and-drop interface for creating AI agents, workflows, and applications.

    # Open Coze Studio in your browser
open http://localhost:8888/

# Or navigate manually to:
# http://localhost:8888/

# You should see the Coze Studio dashboard
  9. Step 9

    Understanding the Platform Components

    Coze Studio provides four core components for AI development: Agents (conversation-based AI with automatic plugin/workflow execution), Apps (standalone AI applications with defined inputs/outputs), Workflows (drag-and-drop task automation with combinable nodes), and Plugins (custom functionality extensions). The platform also includes RAG knowledge bases, databases, prompt management, and SDK integration capabilities.

  10. Step 10

    Create Your First Agent

    Agents are conversation-based AI projects that can automatically call plugins or workflows to execute business processes. Common use cases include customer service bots, personal assistants, and task automation.

    # In the Coze Studio dashboard:
# 1. Click "Create Agent"
# 2. Configure the agent:
#    - Name and description
#    - Select your configured LLM model
#    - Define the agent's role and instructions
#    - Add plugins or workflows (optional)
# 3. Test the agent in the built-in chat interface
# 4. Publish when ready
  11. Step 11

    Build a Workflow

    Workflows enable complex task automation using flexible, combinable nodes. The visual workflow builder supports LLM operations, custom code execution, conditional logic, loops, and data transformations—all through drag-and-drop design.

    # Create a workflow:
# 1. Navigate to Workflows section
# 2. Click "New Workflow"
# 3. Drag and drop nodes from the left panel:
#    - LLM nodes (model inference)
#    - Code nodes (Python execution)
#    - Conditional nodes (if/else logic)
#    - Plugin nodes (external API calls)
#    - Knowledge base nodes (RAG)
# 4. Connect nodes to define execution flow
# 5. Test and debug the workflow
# 6. Save and integrate with agents
  12. Step 12

    Set Up Knowledge Bases (RAG)

    Knowledge bases enable Retrieval-Augmented Generation (RAG) for integrating external knowledge into your AI agents. Upload documents, websites, or structured data to provide agents with domain-specific information beyond their training data.

    # Create a knowledge base:
# 1. Navigate to Knowledge Bases
# 2. Click "Create Knowledge Base"
# 3. Upload your data sources:
#    - PDF documents
#    - Text files
#    - Web pages (URL)
#    - Structured data (JSON, CSV)
# 4. Configure chunking and embedding settings
# 5. Link the knowledge base to your agents
  13. Step 13

    Develop Custom Plugins

    Plugins extend Coze Studio's functionality by integrating external APIs, services, or custom business logic. Plugins can be called automatically by agents or used as nodes in workflows.

    # Plugin development workflow:
# 1. Navigate to Plugin Management
# 2. Click "Create Plugin"
# 3. Define plugin interface:
#    - Input parameters
#    - Output schema
#    - API endpoint or code logic
# 4. Test the plugin independently
# 5. Make it available to agents and workflows
  14. Step 14

    Understanding the Technology Stack

    Coze Studio is built on a modern microservices architecture. The frontend uses React + TypeScript with Rush.js as the monorepo orchestrator and pnpm for package management. The backend is developed in Go following domain-driven design (DDD) principles. The system uses Thrift IDL for defining contracts between components. The entire platform is containerized with Docker for consistent deployment across environments.

    ⚠ Heads up: The architecture follows microservices and DDD principles with a highly scalable framework. For secondary development, review the Project Architecture and Development Standards sections in the official documentation.
  15. Step 15

    Security Considerations for Production

    If you plan to deploy Coze Studio in a public network environment, assess security risks before proceeding. The platform includes features that require careful security hardening in production environments.

    ⚠ Heads up: Security risks to address before public deployment: (1) Account registration functions—consider disabling open registration or implementing verification. (2) Python code execution in workflow nodes—sandbox untrusted code or restrict to internal users. (3) SSRF attack vectors—validate and sanitize all external API calls. Review the official security documentation before production deployment.
  16. Step 16

    Development Environment Setup

    For developers contributing to Coze Studio or building custom extensions, set up the local development environment. The project uses Rush.js for the frontend monorepo and Go workspaces for the backend.

    # Frontend development setup (Rush.js + pnpm)
cd frontend
npm install -g @microsoft/rush
rush install
rush build

# Backend development setup (Go workspace)
cd backend
go mod download
go build ./...

# Run tests
rush test        # Frontend
go test ./...    # Backend
  17. Step 17

    API Integration and SDK

    Coze Studio provides REST APIs and SDKs for integrating agents into your own applications. Use the Conversation API to embed AI agents in web apps, mobile apps, or backend services.

    # Access API documentation
# Navigate to: http://localhost:8888/admin/#api-docs

# Example: Call an agent via REST API
curl -X POST http://localhost:8888/api/v1/conversation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "agent_id": "your-agent-id",
    "message": "Hello, agent!"
  }'
  18. Step 18

    Monitoring and Logs

    Monitor your Coze Studio deployment and troubleshoot issues using Docker logs and the built-in admin dashboard. The platform provides observability features for tracking agent performance and usage.

    # View all container logs
docker compose -f ./docker/docker-compose.yml logs -f

# View logs for a specific service
docker compose logs -f coze-server

# Check resource usage
docker stats

# Access admin dashboard for system monitoring
# URL: http://localhost:8888/admin/#monitoring
  19. Step 19

    Stopping and Managing Services

    Learn how to properly stop, restart, and manage your Coze Studio deployment. Use docker-compose commands to control the lifecycle of all services.

    # Stop all services
docker compose -f ./docker/docker-compose.yml down

# Stop and remove volumes (clean slate)
docker compose -f ./docker/docker-compose.yml down -v

# Restart services
docker compose -f ./docker/docker-compose.yml restart

# Update to latest version
git pull
docker compose -f ./docker/docker-compose.yml pull
docker compose -f ./docker/docker-compose.yml up -d

Feature requests

Sign in to suggest features or vote on existing ones.

No feature requests yet.

Discussion

0 people marked this as worked·Sign in to mark your own.

Sign in to join the discussion.

No comments yet.