Background Agents
A background agent is an AI worker that runs without you. It has its own instructions, its own model, and its own files, and it can carry a conversation across runs so it can build up work over time.
Background agents are one half of Automation. Read that page first if you haven’t, because an agent on its own never runs.
An agent is not the same thing as a job. An agent run is one-off: it wakes, does a run’s worth of work, writes its notes and stops. A job is a piece of work with an end to it, and it plans itself, keeps going across days, checks its own result before calling it done, and asks you when it needs something. Use an agent for work that keeps happening, and a job for work that finishes.
Agents have no trigger
Section titled “Agents have no trigger”An agent doesn’t listen for anything. A reflex is what wakes it, and the reflex passes along whatever it decided the agent needs to know.
This means:
- An agent with no reflex pointed at it is dormant. That’s fine, and it’s how you’d park one you’re not using.
- Several reflexes can wake the same agent.
- A reflex with no agent is completely normal, and is the right shape for most automation.
What an agent has
Section titled “What an agent has”| Piece | What it’s for |
|---|---|
| Instructions | What the agent is meant to do on each run, what to record, and when to contact you |
| Model | The AI model it runs on, which you can ask Alfred to change |
| Files | Its own workspace of Cards, including state.md for its notes and runs.md for the log of its runs |
| Thread settings | How long a thread gets before it rolls over (its window), how many of the last messages carry over when it does, how many recent runs a run with no thread is briefed with, and how many steps one run may take. Each has a sensible default |
| Inbox | Notes it leaves for Alfred to bring up with you later |
An agent can be given access to tools and to cards outside its usual jurisdiction when Alfred decides it needs them to do its job.
What an agent remembers
Section titled “What an agent remembers”Each run is its own conversation, and you can read every one in the Agents history on the Dashboard.
A reflex can put a run on a thread, which is the conversation the agent is having with someone or something: a channel, a DM, a ticket. Every run on the same thread sees the runs before it, so the agent remembers that conversation instead of starting over. Runs on different threads don’t see each other, and a run with no thread starts from nothing. Automation shows how a reflex names one.
A thread doesn’t grow forever. Once it gets past its window, the next run starts a fresh conversation that opens with a summary of the thread so far and the last few messages. The summary is kept up to date after every run by a separate summariser, not by the agent, so nothing depends on the agent remembering to write it.
Two files hold the rest:
state.mdis the agent’s own notes: what it decided, what it’s watching for. This is where anything that should outlast a thread belongs.runs.mdis the log of what each run did, keeping the last 50. A run with no thread is shown a line for each of its last few entries so it knows what it did recently; how many is one of the settings, and 0 turns it off.
Writing good instructions
Section titled “Writing good instructions”Agent instructions are the whole personality of the thing, so vague instructions produce vague runs. A good set of instructions says:
- What to look at on each run.
- What to write down, and where.
- When to contact you, and when to stay quiet.
That last one matters more than people expect. An agent that reports every run is an agent you’ll mute within a week.
Talking to your agents
Section titled “Talking to your agents”You can ask Alfred to list your agents, show what one has been doing, change its instructions or its thread settings, pause it, or delete it. Every run shows up as its own entry in the Agents history on the Dashboard, so you can read exactly what an agent did on a run instead of guessing.
Every agent run is a real AI run and it comes out of your usage allowance, same as a normal message. An agent woken every minute on a strong model will eat through allowance quickly.
If an agent is costing more than it’s worth, the usual fixes are to move the cheap parts of the job into the reflex, run it less often, or put it on a cheaper model. See Usage.