My First Agent

In this guide, you'll create your first VM0 agent, configure it, and run it to see how agents work.

Prerequisites

Before starting, make sure you have:

VM0 CLI installed (npm install -g @vm0/cli)
Authenticated with VM0 (vm0 auth login)
Model provider configured (vm0 model-provider setup) - see Quick Start if you haven't done this yet

Step 1: Create Your Project

Create a new directory for your research agent:

mkdir research-agent
cd research-agent

Step 2: Initialize Your Agent

Initialize a new VM0 agent project with a descriptive name:

vm0 init -n my-researcher

This command creates two important files:

vm0.yaml - Agent configuration file that defines provider, image, and environment settings
AGENTS.md - Instructions file that describes what your agent should do

Let's look at what was created:

vm0.yaml

version: "1.0"

agents:
  my-researcher:
    framework: claude-code
    # Build agentic workflow using natural language
    instructions: AGENTS.md

AGENTS.md

# Agent Instructions

You are a HackerNews AI content curator.

## Workflow

1. Go to HackerNews and read the top 10 articles
2. Find and extract AI-related content from these articles
3. Summarize the findings into a X (Twitter) post format
4. Write the summary to content.md

The vm0.yaml file includes helpful comments showing you where to add skills. The AGENTS.md file provides a complete example workflow that you can study and customize. We'll modify this in the next part of the tutorial to build our research agent.

Step 3: Run Your First Agent

Now let's run your agent and watch it complete the workflow:

vm0 cook "let's do it"

You'll see output similar to this:

Reading config: vm0.yaml
✓ Config validated: 1 agent, 0 volume(s)

Processing artifact:
> mkdir artifact
> cd artifact
> vm0 artifact init --name artifact
> vm0 artifact push
> cd ..

Composing agent:
> vm0 compose vm0.yaml
Uploading instructions: AGENTS.md
✓ Instructions (unchanged): b2d77a3d
Uploading compose...
✓ Compose version exists: your-username/my-researcher
  Version: e2ec8e50

Running agent:
> vm0 run my-researcher --artifact-name artifact "let's do it"

▶ Run started
  Run ID:   56a0d396-7d95-4cde-a44d-232ad6f8a21f
  Sandbox:  ic63cb57nrddkra94yzg7

[init] Starting Claude Code agent
  Session: 4b5d44f8-2d5f-494d-b8ce-698eb355096d
  Model: claude-sonnet-4-5-20250929

[text] I'll help you curate AI content from HackerNews! Let me create a todo list...
[tool_use] TodoWrite
[tool_use] WebFetch - https://news.ycombinator.com
[tool_use] Write - /home/user/workspace/content.md

[result] ✓ completed successfully
  Duration: 54.0s
  Cost: $0.1166

✓ Run completed successfully

Pulling updated artifact:
> cd artifact
> vm0 artifact pull b5abed3a
> cd ..

Check your results:

ls artifact
# Output: content.md

cat artifact/content.md
# You'll see the AI content summary!

If you see artifact/content.md created with HackerNews AI content, congratulations! Your agent is working correctly.

What Just Happened?

vm0 cook is a convenient command that runs multiple steps automatically. Here's what it did:

1. Prepared Artifact Directory

mkdir artifact
cd artifact
vm0 artifact init --name artifact
vm0 artifact push
cd ..

This creates a workspace where your agent can save output files. The artifact directory is synced between your local machine and the remote agent.

See Artifact for more information about managing agent output.

2. Composed Agent

vm0 compose vm0.yaml

This step binds your instructions and skills together to compose your agent.

3. Ran Agent

vm0 run my-researcher --artifact-name artifact "let's do it"

This step creates a remote sandbox environment and executes your prompt using Claude Code with your configured instructions and skills, streaming real-time logs back to you.

In this step, Claude Code follows your prompt "let's do it" along with the instructions in AGENTS.md to complete the workflow: fetching content from HackerNews, extracting AI-related articles, and generating the X (Twitter) post summary.

4. Downloaded Results

cd artifact && vm0 artifact pull <artifact-version> && cd ..

Any files the agent created or modified are downloaded to your local artifact directory.

Understanding Your Project Structure

After this step, your project should look like this:

research-agent/
├── vm0.yaml       # Agent configuration
├── AGENTS.md      # Agent instructions (system prompt)
└── artifact/      # Output files from agent runs
    └── content.md # HackerNews AI summary created by agent

Next Steps

Continue to the next section to learn how to customize the AGENTS.md instructions and build a deep research agent.

On this page