Quickstart

Step 1: Create Your Agent

Scaffold a new agent project:

circuit new

The CLI prompts you for a template, a language (TypeScript or Python), and an agent name, then generates a project directory with your agent code, circuit.toml config, and installed dependencies. You do not need to log in until you use account-backed commands such as upload or hosted dev runs. Navigate into the project.

cd agent-name

Your generated agent code looks like this:

from circuit_sdk import AgentContext

def run(agent: AgentContext) -> None:
    agent.log("Hello from my agent!")

import type { AgentContext } from "circuit:sdk";

export async function run(agent: AgentContext): Promise<void> {
  await agent.log("Hello from my agent!");
}

Step 2: Test Locally

The fastest loop needs no Circuit account, backend, wallet, or funding:

circuit run --dry-run
circuit unwind --dry-run

Dry run executes the real agent and engine-wire route, but journals signing and fund-moving writes rather than broadcasting them. Provider-backed reads still use the network. Each run receives an empty allocation because dry-run owns no capital allocation; journaled requests never become observed balances or positions. Use the hosted engine to test allocation-dependent behavior against a real running session. The agent’s agent.log() output streams to stdout:

[agent] Hello from my agent!

To sign and broadcast from a self-custodied local wallet, run the one-time setup below, then use plain circuit run:

circuit wallet add
circuit auth login --local
circuit run

To test against the hosted engine instead (Circuit wallet selection, sessions, policy, and KMS signing), use circuit run --hosted engine. See the Development reference.

Step 3: Upload

circuit auth login
circuit upload

If your agent needs API keys or other secrets, create a local .env file before uploading:

YOUR_API_KEY=...

circuit upload reads .env from the agent root, then applies any --var KEY=VALUE overrides, encrypts those values at rest, and injects them into your agent’s hosted runtime as normal environment variables. For more details, see Uploading → Environment Variables. This uploads your agent to Circuit. Once uploaded, users can find and run it through the Circuit app.

Getting Started

Core Concepts

Examples

CLI Reference

SDK Reference

Advanced

Step 1: Create Your Agent

Step 2: Test Locally

Step 3: Upload

​Step 1: Create Your Agent

​Step 2: Test Locally

​Step 3: Upload

Step 1: Create Your Agent

Step 2: Test Locally

Step 3: Upload