Quickstart

The fastest way to create, test, and deploy a Circuit agent. This guide walks you through installing the CLI, setting up a project, writing your first agent, and deploying to production.

Prerequisites

  • TypeScript: Bun ≥ 1.0 (npm will not work)

  • Python: Python ≥ 3.12

Installation

bun install -g @circuitorg/agent-cli

Verify Installation:

circuit --version

Getting Started

# Authenticate your CLI
# Opens a browser window for you to log in
circuit login

# Create a new agent directory
# Prompts you for a language (TypeScript or Python) and name
circuit init

# Navigate into your agent folder
# This folder contains index.ts (or main.py) and configuration files
cd <agent-name>

# Install dependencies
bun install    # for TypeScript
uv sync        # for Python

# Test your agent locally by running your agent's logic in a local sandbox env
# It creates a temporary session wallet and executes your `run()` function
circuit run

# Publish to production
# This pushes your agent to Circuit Cloud so it can be scheduled or triggered automatically
circuit publish

Project Structure

After circuit init, your agent folder will include:

File
Purpose

.circuit.toml

Agent configuration (network, assets, metadata)

index.ts / main.py

Main agent logic

package.json / pyproject.toml

Dependency definitions

Your agent defines two commands:

  • run: executes agent logic

  • stop: handles cleanup when the agent stops

Next Steps

PreviousOverviewNextSample Python Agent

Last updated