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

# Agents

> List, inspect, create, and update agents from the terminal.

`gumloop agents` lets you list, inspect, create, and update your [agents](/core-concepts/agents) without leaving the terminal. Every command accepts `--json` to print the raw response payload.

## List agents

```bash theme={"dark"}
gumloop agents list
gumloop agents list --search support --limit 50
```

Returns a tab-separated table with `ID`, `NAME`, `MODEL`, `TEAM`, and `ACTIVE`. If the response is paginated, the next cursor is printed at the bottom — pass it back with `--cursor`.

| Flag       | Description                                  |
| ---------- | -------------------------------------------- |
| `--search` | Filter agents by name or description.        |
| `--limit`  | Maximum number of agents to return.          |
| `--cursor` | Pagination cursor from a previous list call. |
| `--json`   | Print the raw response payload.              |

The `--team-id` global flag scopes the listing to a single team.

## Get an agent

```bash theme={"dark"}
gumloop agents get agent_abc
```

Prints the agent's name as a header followed by `id`, `model_name`, `team_id`, `is_active`, `folder_id`, `description`, `created_at`, and the system prompt (if set).

<Tip>Grab the agent ID from the first column of `gumloop agents list`.</Tip>

## Create an agent

```bash theme={"dark"}
gumloop agents create --name "Support bot" --model auto
```

| Flag                   | Required | Description                                                                             |
| ---------------------- | -------- | --------------------------------------------------------------------------------------- |
| `--name`               | yes      | Display name for the new agent.                                                         |
| `--model`              | yes      | Model name (for example `auto`, `anthropic/claude-sonnet-4`).                           |
| `--description`        |          | Short description.                                                                      |
| `--system-prompt`      |          | Inline system prompt text.                                                              |
| `--system-prompt-file` |          | Path to a file containing the system prompt. Mutually exclusive with `--system-prompt`. |
| `--tools-json`         |          | Inline JSON array of tool config objects.                                               |
| `--tools-file`         |          | Path to a JSON file containing the tools array. Mutually exclusive with `--tools-json`. |
| `--json`               |          | Print the raw response payload.                                                         |

Pass the system prompt from a file:

```bash theme={"dark"}
gumloop agents create --name "Sales research" --model auto \
  --system-prompt-file ./prompts/sales.md
```

Attach tools (each entry in the array is one tool config; the shape varies by type):

```bash theme={"dark"}
gumloop agents create --name "Email reader" --model auto \
  --tools-json '[{"type":"gumcp_server","server":"gmail"}]'
```

<Tip>To see the exact tool config shape an agent uses, run `gumloop agents get <id> --json` on an existing agent and copy the `tools` array out of the response.</Tip>

## Update an agent

```bash theme={"dark"}
gumloop agents update agent_abc --name "Better bot"
gumloop agents update agent_abc --system-prompt-file new-prompt.md
gumloop agents update agent_abc --inactive
```

Only the flags you pass are changed; everything else is left untouched. The flag surface matches `agents create` and adds:

| Flag                         | Description                                   |
| ---------------------------- | --------------------------------------------- |
| `--is-active` / `--inactive` | Toggle whether the agent runs when triggered. |