A
Docs
Back to Builder

Running Your Agent

How to set up and run your generated agent.

Prerequisites

  • Node.js 18 or later
  • npm or yarn
  • API key from your chosen provider (Anthropic or OpenAI)

Initial Setup

1. Extract the Project

1unzip my-agent.zip
2cd my-agent

2. Install Dependencies

1npm install

3. Configure Environment

Copy the example environment file and add your API key:

1cp .env.example .env

Edit .env and add your API key:

1# For Claude Agent SDK
2ANTHROPIC_API_KEY=sk-ant-...
3
4# For OpenAI SDK
5OPENAI_API_KEY=sk-...

4. Build the Project

1npm run build

5. Run the Agent

1npm start

Interactive Mode

By default, the agent runs in interactive mode with a prompt:

1✨ My Agent v1.0.0
2Type your message, use /help for commands, or 'exit' to quit.
3
4You:

Basic Usage

Type your message and press Enter. The agent will process your request and stream the response:

1You: What files are in the current directory?
2
3Agent: I'll check the current directory for you.
4
5[Using find-files tool...]
6
7The current directory contains:
8- package.json
9- tsconfig.json
10- src/
11  - cli.ts
12  - agent.ts
13  ...

Special Commands

CommandDescription
/helpShow available commands
/clearClear conversation history
/configShow current configuration
/planEnter planning mode
/plansList saved plans
exitExit the agent

Slash Commands

If you configured slash commands, use them with /command-name:

1You: /review-pr 123
2
3📋 Running /review-pr...
4
5Agent: I'll review pull request #123 for you...

Single Query Mode

Run a single query without entering interactive mode:

1npm start -- --query "What files are in src/"

Or with the built binary:

1./dist/cli.js --query "Analyze package.json"

Development Mode

For development, use watch mode to auto-rebuild on changes:

1# Terminal 1: Watch for changes
2npm run dev
3
4# Terminal 2: Run the agent
5npm start

Global Installation

Install your agent globally to use it from anywhere:

1npm run build
2npm link
3
4# Now use it globally
5my-agent

Troubleshooting

API Key Errors

Invalid API Key

If you see "Invalid API key" errors, verify:

  • The key is correctly set in .env
  • There are no extra spaces or quotes around the key
  • The key matches your selected SDK provider

Build Errors

If TypeScript compilation fails:

  • Ensure Node.js 18+ is installed
  • Delete node_modules and run npm install again
  • Check for syntax errors in any customizations

Permission Errors

If tools are being blocked:

  • Check your permission level in the configuration
  • Verify the tool is enabled
  • Some operations may require user confirmation

MCP Server Errors

If MCP servers fail to connect:

  • Verify required environment variables are set
  • Check that npx can download the server package
  • Review .mcp.json for configuration errors