# uip agent context

> `uip agent context` manages **context resources** on an agent project — the RAG (retrieval-augmented generation) index bindings that the agent consults at runtime. Each context is a named reference to an index, plus a retrieval mode and scoring parameters. The command writes directly to the agent project on disk (purely local — no login required).

`uip agent context` manages **context resources** on an agent project — the RAG (retrieval-augmented generation) index bindings that the agent consults at runtime. Each context is a named reference to an index, plus a retrieval mode and scoring parameters. The command writes directly to the agent project on disk (purely local — no login required).

## Synopsis

```
uip agent context add    <name> --index <indexName>
                                [--retrieval-mode <mode>] [--threshold <n>] [--result-count <n>]
                                [--path <dir>]
uip agent context list                                    [--path <dir>]
uip agent context remove <name>                           [--path <dir>]
```

All `uip agent context` subcommands honor the [global options](./global-options.md) (`--output`, `--output-filter`, `--log-level`, `--log-file`). Exit codes follow the [standard contract](./exit-codes.md).

## uip agent context add

Add a RAG context resource to the agent.

### Arguments

- `<name>` *(required)* — Context resource name. Used for later removal (`context remove <name>`).

### Options

| Flag | Default | Required | Purpose |
|---|---|---|---|
| `--index <indexName>` | — | yes | Index name to retrieve from. |
| `--retrieval-mode <mode>` | `semantic` | | Retrieval mode. One of: `semantic`, `structured`, `deeprag`, `batchtransform`. |
| `--threshold <n>` | `0` | | Retrieval score threshold (numeric). Values below this cutoff are discarded. |
| `--result-count <n>` | `3` | | Number of results to retrieve per query (integer). |
| `--path <path>` | `.` | | Path to the agent project directory. |

Invalid numeric inputs for `--threshold` or `--result-count` fail with a validation error.

### Examples

```bash
# Semantic RAG with defaults (threshold 0, 3 results)
uip agent context add KnowledgeBase --index docs-index --path ./my-agent

# Tighter recall: higher threshold, more results
uip agent context add KnowledgeBase \
  --index docs-index \
  --retrieval-mode semantic \
  --threshold 0.7 \
  --result-count 5

# Structured retrieval over a different index
uip agent context add Tickets \
  --index ticket-index \
  --retrieval-mode structured
```

### Data shape (--output json)

```json
{
  "Code": "AgentContextAdd",
  "Data": {
    "Status": "Context added",
    "Name": "KnowledgeBase",
    "Index": "docs-index",
    "Mode": "semantic",
    "Id": "a1b2c3d4-0000-0000-0000-000000000010"
  }
}
```

`Id` is a generated UUID stamped into the resource. Use either the `Name` or the `Id` with `context remove`.

## uip agent context list

Enumerate the context resources configured on the agent.

### Options

| Flag | Default | Purpose |
|---|---|---|
| `--path <path>` | `.` | Path to the agent project directory. |

### Example

```bash
uip agent context list --path ./my-agent
```

### Data shape (--output json)

```json
{
  "Code": "AgentContextList",
  "Data": [
    {
      "Name": "KnowledgeBase",
      "Index": "docs-index",
      "Mode": "semantic",
      "Id": "a1b2c3d4-0000-0000-0000-000000000010"
    }
  ]
}
```

Empty projects return `Data: { "Message": "No contexts configured" }`.

## uip agent context remove

Remove a context resource.

### Arguments

- `<name>` *(required)* — Context name **or** ID.

### Options

| Flag | Default | Purpose |
|---|---|---|
| `--path <path>` | `.` | Path to the agent project directory. |

### Example

```bash
uip agent context remove KnowledgeBase --path ./my-agent
```

### Data shape (--output json)

```json
{
  "Code": "AgentContextRemove",
  "Data": {
    "Status": "Context removed",
    "Name": "KnowledgeBase"
  }
}
```

A missing context fails with `Context "<name>" not found` and exit code `1`.

## Related

- [`uip agent tool`](./uip-agent-tool-manage.md) — add other resource kinds (IS integrations, processes, etc.).
- [`uip agent escalation`](./uip-agent-escalation-manage.md) — HITL / escalation resources.
- [`uip agent validate`](./uip-agent-validate.md) — re-run after batch edits to confirm resource integrity.

## See also

- [Concepts: skills](./concepts-skills.md) — how resources connect to the skill model.
- [Global options](./global-options.md), [Exit codes](./exit-codes.md).