Quickstart

Get up and running with Automagent in under 5 minutes

Install the CLI

$ npm install -g automagent

Verify the installation:

$ automagent --version

You can also use npx to run commands without a global install:

$ npx automagent init --quick

Create your first agent

Run init to generate an agent.yaml file in your current directory:

$ automagent init

The interactive prompts will ask for a name, description, model, and instructions. Answer each one, or press Enter to accept the defaults.

If you want to skip the prompts entirely:

$ automagent init --quick --name support-agent --description "Answers customer questions"

Understand the generated file

Here is what a generated agent.yaml looks like:

# yaml-language-server: $schema=https://automagent.dev/schema/v1.json
apiVersion: v1
kind: agent

name: support-agent
version: 0.1.0
description: Answers customer questions

model: claude-sonnet-4-20250514

instructions: |
  You are a helpful assistant.

A quick breakdown of the key fields:

• name — A machine-readable slug. Lowercase letters, numbers, and hyphens only.
• description — A human-readable summary of what your agent does.
• model — The model identifier. Pinned versions like claude-sonnet-4-20250514 are recommended over aliases like claude-sonnet.
• instructions — The system prompt that shapes your agent’s behavior.
• apiVersion and kind — Schema metadata. Leave these as v1 and agent.

The first line is a YAML language server directive that gives you autocomplete and validation in editors like VS Code.

Validate it

Run the validator to make sure your definition is correct:

$ automagent validate

If everything checks out, you will see output like this:

✔ Schema valid
✔ Model check passed
✔ No secrets detected
✔ Context files OK

agent.yaml is valid

The validator runs four checks: schema compliance, model version pinning, secret detection (catches leaked API keys), and context file existence. See the validate reference for full details.

Run it locally

Start an interactive chat session with your agent:

$ automagent run

This requires an API key for the model’s provider. For Claude models, set ANTHROPIC_API_KEY in your environment:

$ export ANTHROPIC_API_KEY=your-key-here
$ automagent run

For OpenAI models (gpt-*, o1, o3), set OPENAI_API_KEY instead.

The CLI starts a chat loop where you type messages and the agent responds using the model and instructions from your agent.yaml. Any tools defined in the file are mocked by default — they return placeholder responses so you can test the conversation flow without connecting real services.

Type exit or press Ctrl+C to end the session.

What’s next

You have a working agent definition. Here are some directions to explore:

• Add tools and context — Define tools your agent can call and context files it can reference. See the field reference for all available options.
• Import existing agents — Already have agents in CrewAI, OpenAI, or LangChain? Use automagent import to convert them. The import guide walks through the process.
• Publish to the Hub — Share agents with your team using automagent push and automagent pull. Use automagent search to discover agents others have published.
• Build multi-agent workflows — Define teams of agents that collaborate using agent-compose.yaml. See the multi-agent guide.
• Explore the schema — Read the schema overview to understand the full power of agent.yaml.