automagent run

Run an agent interactively in a local chat loop

Usage

$ automagent run [path] [options]

If no path is specified, the command looks for ./agent.yaml in the current directory.

Options

Flag	Description
`--model <model>`	Override the model defined in `agent.yaml`

Provider detection

The CLI automatically detects the model provider from the model identifier and uses the corresponding API key from your environment:

Model pattern	Provider	Environment variable
`claude-*`, `anthropic`	Anthropic	`ANTHROPIC_API_KEY`
`gpt-*`, `openai`, `o1`, `o3`	OpenAI	`OPENAI_API_KEY`
Unknown	Anthropic (default)	`ANTHROPIC_API_KEY`

If the required API key is missing, the CLI prints a clear error message telling you exactly which environment variable to set.

API key setup

Set the appropriate key before running:

# For Claude models
$ export ANTHROPIC_API_KEY=your-key-here

# For OpenAI models
$ export OPENAI_API_KEY=your-key-here

The SDKs (@anthropic-ai/sdk and openai) are dynamically imported — they are only loaded when you actually use run, so they don’t slow down other commands.

How tool mocking works

If your agent.yaml defines tools, they are mocked by default during run. When the model attempts a tool call, the CLI intercepts it and returns a placeholder response instead of executing real code.

This lets you test conversation flow and tool-calling behavior without connecting to real APIs or services. The mock response indicates which tool was called and what parameters were passed.

tools:
  - name: search-docs
    description: Search the documentation
    inputSchema:
      type: object
      properties:
        query:
          type: string

When the agent calls search-docs, the CLI returns a mock response rather than performing an actual search. This is useful for iterating on your agent’s instructions and verifying it uses tools appropriately.

Examples

Run the default agent:

$ automagent run

Run a specific agent file:

$ automagent run agents/researcher.yaml

Override the model for testing:

$ automagent run --model claude-haiku-4-5-20251001

This is handy for testing with a faster or cheaper model during development without editing your agent.yaml.

Typical session:

$ automagent run
Loading agent: support-agent (claude-sonnet-4-20250514)
Tools: search-docs (mocked)

You: How do I reset my password?

Agent: To reset your password, follow these steps:
1. Go to the login page
2. Click "Forgot password"
3. Enter your email address
...

You: exit

Notes

The agent’s instructions field is sent as the system prompt.
The chat session maintains conversation history within the session.
Type exit or press Ctrl+C to end the session.
Validation runs automatically before starting the chat — if the agent.yaml is invalid, you will see errors before the REPL starts.