# The agency agent

Agency ships with a built-in coding agent. Start it using:

```bash
agency agent
```

This is a general purpose agent. You can ask it to write code, do research, et cetera. It can also provide Agency-specific help. It can review and debug your code, or teach you about Agency's features. You can also use it to get help with different CLI commands.

## One-shot mode

Running `agency agent` runs the agent in interactive mode. You can also run it in one shot mode in these ways:

```bash
# passing it a prompt on the command line
agency agent "explain the error in foo.agency"

# passing a prompt with the `-p` flag
agency agent -p "write a hello-world node"

# piping input to it
cat error.log | agency agent "what went wrong here?"
echo "summarize this file" | agency agent
```

In this case, the agent will autonomously do the work and then exit.

## Web search

The agent offers at most one Brave or Tavily search tool. It uses Brave
when `BRAVE_API_KEY` is set, otherwise Tavily when `TAVILY_API_KEY` is set.
Empty values count as missing keys. With neither key set, the agent has
no Brave or Tavily tool; supported models can still use hosted search.

The code subagent keeps an explicit `/search` choice, including Tavily
when both keys are set. `/search` also lets you choose hosted search or
turn search off for that subagent.

## Tool output

```text
✓ Tasks updated  todoWrite
  │ 1/3 complete
  │ ✓ Verify rankings
  │ › Check availability · in progress
  │ ○ Compare hardware

⌕ Web search  web_search
  │ openai-responses · 2 queries
  │ · site.example.com "release notes"
  │ · downloadable model weights
```

Each task update prints only the current list, without a generic tool-call block. Completed tasks have a check mark
and crossed-out text when terminal styling is enabled. Active tasks have
an arrow and an explicit status label. Pending tasks have an open circle.

All search providers share the same display. Queries appear in full; returned
sources show titles and URLs, up to five with a count of any remaining ones.
Hosted records appear with the model response. Tavily and Brave show a start
block followed by their results.

Starts are blue; completed calls have green check marks and dim result
previews. Failures are red. Hosted searches have a neutral heading because
their records do not report success or failure. Markers and words distinguish
these states when color is disabled. Subagent dispatches have one named
announcement. Other tools show named arguments and result previews. Long
lines wrap to fit the terminal.

Interactive sessions show tool output by default. Add `--verbose` to show
it in one-shot mode. `--debug` also enables tracing and retains additional
diagnostics.

## Safety features
Agency comes with great support for making agents safer, and the Agency agent takes full advantage of it. Before taking most actions, the agent will pause and ask you for approval. You can also pre-approve actions by using [Agency's policies feature](/guide/policies).

The first time you start the agent, it will ask you to pick a policy:

```
Welcome to the agency agent. Please pick a policy to start.

    Don't worry, you can change this later. The policy just controls how the agent asks for your approval when it wants to do something. You can also create your own custom policy file at /Users/adityabhargava/.agency-agent/policy.json and the agent will use it automatically.


? Do you want to continue? ›
❯   minimal - minimal default policy, you do most approvals manually
    recommended - recommended default policy, allow reading files and browsing the web, no writes
```

A policy defines what actions the agent takes without asking, and it will prompt you for everything else. When it prompts you for action, you can also choose to modify the policy so that it doesn't ask you for the same action next time.

You can also run the agent with a specific policy like so:

```bash
agency agent --policy myPolicy.json
```

Here you can give it a path to a policy file, or use one of the built-in policies:

```bash
# approves everything, fully autonomous but unsafe
agency agent --policy approve-all
```

You can also approve or reject a named effect set for one session. For example, `agency agent --approve GithubRead` lets the agent read pull requests and issues without asking, while every GitHub write still prompts. `agency effects` lists the sets you can name.

## The agent home directory

The agent keeps the policy, as well as any settings and other data, in its home directory. By default, the directory is at `~/.agency-agent`. You can point it somewhere else with `--agent-home` or the `AGENCY_AGENT_HOME` environment variable:

```bash
agency agent --agent-home ./my-profile
AGENCY_AGENT_HOME=./my-profile agency agent
```

## Slash commands

Inside an interactive session, press `/` to run a slash command:

| Command | What it does |
|---|---|
| `/help` | List the available commands. |
| `/exit`, `/quit` | Leave the session. |
| `/clear` | Clear the conversation transcript. |
| `/clear-history` | Clear the saved input history. |
| `/cost` | Show cumulative cost and tokens so far, broken down by model. |
| `/model` | Switch the model. See [Models](/agent/models). |
| `/models` | List the hosted model catalog. |
| `/local` | Switch to a local model. |
| `/search` | Choose the web search backend. |
| `/settings` | View and change settings for the current model. |
| `/mcp` | List configured [MCP servers](/agent/mcp) and their tools. |
| `/paste` | Enter multi-line paste mode (Ctrl+D submits, Ctrl+C cancels). |

I want to call out that last one. If you want to enter multiple lines into the Agency agent, you'll need to enter paste mode first, by running `/paste`.

You can add your own commands too. See
[Project context and slash commands](/agent/project-context).

## Useful flags

A few flags help when debugging or scripting. The [CLI reference](/cli/agent)
lists them all.

- `--verbose` — show tool calls, results, and LLM diagnostics in one-shot mode.
- `--debug` — enable tracing and additional debug diagnostics.
- `--max-tool-call-rounds <n>` — cap the LLM tool-call rounds before a turn
  stops. Defaults to 10 interactive, 50 in one-shot mode.
- `--log <path>` — write logs to a file.
- `--max-cost` - stop the agent if the session cost gets higher than this.
- `--max-time` - stop the agent if the session takes longer than this.