> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fimo.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an agent

> Scaffold an agent bundle from a starter template, write its goal, validate it, and activate it on an environment.

Authoring an agent is local, file-first work: scaffold a bundle, describe the goal, validate, then deploy and activate. Run any command below with `npx fimo@latest <command>` for the latest CLI.

## Scaffold a bundle

Start from one of the bundled starter templates:

```bash theme={null}
fimo agents list-templates          # see the starters and what each one does
fimo agents create <name>           # scaffold agents/<name>/ from the default template
fimo agents create <name> --template seo-audit --description "Nightly SEO audit"
```

`create` writes `agents/<name>/` — including a `config.yaml` and a `GOAL.md` — and requires you to be inside a real Fimo project so it never leaks files into a stray directory. The five bundled templates are `_default`, `seo-audit`, `content-translator`, `broken-link-sweeper`, and `post-deploy-check`.

<Tip>
  `--description` writes a one-line tagline into `config.yaml` that surfaces in Fimo Studio's agents list.
</Tip>

## Write the goal

`GOAL.md` is the heart of the bundle — it states, in plain language, what the agent should accomplish on each run. If the agent needs a secret (say an API key), request it in config and store the value separately:

```bash theme={null}
fimo agents secrets add <name> FIRECRAWL_API_KEY   # record the requested name in config.yaml
fimo secrets set FIRECRAWL_API_KEY --stdin         # store the hidden value in Fimo
```

Integration access is an allowlist in `config.yaml` — anything you don't list is off-limits to the agent.

## Validate, deploy, activate

<Steps>
  <Step title="Validate locally">
    ```bash theme={null}
    fimo agents validate <name>   # parse + policy + composition checks
    fimo validate                 # also confirms requested secrets exist
    ```

    Omit the name to validate every bundle. Add `--json` for CI; the exit code is non-zero on any failure.
  </Step>

  <Step title="Deploy the bundle">
    ```bash theme={null}
    fimo deploy
    ```

    The bundle reaches the server through git, so it must be deployed before it can be activated or run.
  </Step>

  <Step title="Activate its triggers">
    ```bash theme={null}
    fimo agents activate <name>
    ```

    This wires the agent's declared triggers on the environment. Cloud triggers (schedule / webhook) require `notifications.email_recipients` in `fimo-config.json`.
  </Step>
</Steps>

## What's next

<Columns cols={3}>
  <Card title="Schedules" icon="calendar" href="/docs/agents/schedules">
    Put your agent on a cron and trigger manual runs.
  </Card>

  <Card title="Runs, reports & logs" icon="list-check" href="/docs/agents/runs">
    See what each run produced.
  </Card>

  <Card title="Agents overview" icon="robot" href="/docs/agents/overview">
    The bundle format and why agents live in git.
  </Card>
</Columns>