Skip to main content

​
Creating Agents

This guide walks you through creating an Action Llama agent from scratch.

​
Prerequisites

  • An Action Llama project (created with al new <name>)
  • Credentials configured in ~/.action-llama/credentials/ (see Credentials)

​
Steps

​
1. Create the agent directory

Inside your project directory, create a folder for your agent under the agents/ directory: 
mkdir -p agents/my-agent

​
2. Write agent-config.toml

Create agents/my-agent/agent-config.toml: 
credentials = ["github_token", "git_ssh"]
schedule = "*/5 * * * *"

[params]
repos = ["your-org/your-repo"]

[model]
provider = "anthropic"
model = "claude-sonnet-4-20250514"
thinkingLevel = "medium"
authType = "api_key"
Supported providers: anthropic, openai, groq, google, xai, mistral, openrouter, custom. See agent-config.toml Reference for all available fields and provider examples.

​
3. Write ACTIONS.md

Create agents/my-agent/ACTIONS.md — this is the system prompt that defines your agent’s behavior: 
# My Agent

You are an automation agent. Your job is to ...

Your configuration is in the `<agent-config>` block at the start of your prompt.

`GITHUB_TOKEN` is already set in your environment. Use `gh` CLI and `git` directly.

## Workflow

1. **Step one** — ...
2. **Step two** — ...

## Rules

- ...
The ACTIONS.md is injected as the agent’s system prompt at runtime. Write it as instructions to the LLM.

​
4. (Optional) Add preflight steps

If your agent needs external context (repo contents, API data, issue lists), add [[preflight]] steps to agent-config.toml. Preflight runs after credentials are loaded but before the LLM session starts, so the agent begins with everything it needs: 
[[preflight]]
provider = "git-clone"
[preflight.params]
repo = "your-org/your-repo"
dest = "/tmp/repo"
depth = 1

[[preflight]]
provider = "shell"
[preflight.params]
command = "gh issue list --repo your-org/your-repo --label bug --json number,title --limit 20"
output = "/tmp/context/issues.json"
Then reference the staged files in your ACTIONS.md: 
## Context
- The repo is cloned at `/tmp/repo`
- Open bug issues are at `/tmp/context/issues.json`
See Preflight for the full reference.

​
5. Verify with al stat

al stat -p .
This should show your agent with its schedule and credentials.

​
6. Run with al start

al start -p .
Your agent will run on its configured schedule and/or respond to webhooks.

​
7. (Optional) Customize the project Dockerfile

Every project has a Dockerfile at the root (created by al new) that defines the shared base image for all agents. If your agents need extra system packages, edit it: 
FROM al-agent:latest

# Shared tools for all agents
RUN apk add --no-cache github-cli python3
If only one specific agent needs extra tools, add a Dockerfile to that agent’s directory instead: 
FROM al-agent:latest
USER root
RUN apk add --no-cache github-cli
USER node
See Docker docs for the full reference.

​
8. (Cloud only) Re-run al doctor -c

If you’re running agents on cloud infrastructure, re-run al doctor -c after adding a new agent. This creates the per-agent IAM resources (service account for Cloud Run, task role for ECS) and grants the new agent access to its declared secrets. 
al doctor -c -p .
Without this step, the new agent will fail to access its credentials at runtime.

​
Tips

  • Agent name is derived from the directory name — no need to put it in the config
  • Use al-rerun in your ACTIONS.md to tell the agent to run al-rerun when it did work and there may be more in the backlog
  • Params in the config are injected into the agent prompt as an <agent-config> XML block
  • See Examples for complete working agents