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

# Agent

Status, configuration, and on-demand AI responses for the support agent.

# Agent API

The AI agent reads conversations, retrieves KB context, calls an LLM,
and posts a response (autopilot) or drafts one for review (copilot).

## Endpoints

| Method | Path | Scope |
|--------|------|-------|
| `GET` | `/v1/projects/{projectId}/agent/status` | `read` |
| `GET` | `/v1/projects/{projectId}/agent/config` | `read` |
| `PATCH` | `/v1/projects/{projectId}/agent/config` | `agent:write` |
| `POST` | `/v1/projects/{projectId}/agent/respond` | `agent:write` |
| `POST` | `/v1/projects/{projectId}/agent/classify` | `agent:write` |
| `POST` | `/v1/projects/{projectId}/agent/suggest` | `agent:write` |

## Status

```bash cURL
curl https://api.rogeriq.com/api/v1/projects/prj_xxx/agent/status \
  -H "X-API-Key: riq_xxx"
```

```bash CLI
rogeriq agent status
```

```ts SDK
const status = await roger.agent.status();
```

```json
{
  "data": {
    "enabled": true,
    "mode": "copilot",
    "model": "anthropic/claude-sonnet-4",
    "domain": "support.acme.com",
    "has_byom_key": false,
    "usage_this_month": {
      "calls": 1284,
      "input_tokens": 845022,
      "output_tokens": 184211,
      "cost_usd": 12.40
    }
  }
}
```

## Update config

```bash cURL
curl -X PATCH https://api.rogeriq.com/api/v1/projects/prj_xxx/agent/config \
  -H "X-API-Key: riq_xxx" \
  -H "Content-Type: application/json" \
  -d '{"agent_mode": "autopilot", "ai_model": "openai/gpt-4o"}'
```

```bash CLI
rogeriq agent config --mode autopilot --model openai/gpt-4o
```

```ts SDK
await roger.agent.updateConfig({
  agent_mode: "autopilot",
  ai_model: "openai/gpt-4o",
});
```

`autopilot` (send replies directly), `copilot` (draft as internal
  notes for human review), or `assist` (suggestions only, no posting).
Any model id supported by OpenRouter, e.g.
  `anthropic/claude-sonnet-4`, `openai/gpt-4o`,
  `google/gemini-2.5-pro`.
0-1. Replies below this confidence are flagged / held for review.
Merged into the project's settings JSON. Includes guardrails, tone,
  persona, and other agent tuning.

## Respond on a conversation

```bash
curl -X POST https://api.rogeriq.com/api/v1/projects/prj_xxx/agent/respond \
  -H "X-API-Key: riq_xxx" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id": "con_xxx"}'
```

Runs the full agent pipeline:

1. Loads conversation history + contact metadata.
2. Hybrid-searches the KB for relevant context.
3. Builds the system prompt + calls the LLM.
4. Posts the response according to the project's `agent_mode`.

```json
{
  "data": {
    "content": "Hi Jane! ...",
    "content_html": "<p>Hi Jane! ...</p>",
    "confidence": 0.82,
    "mode": "copilot",
    "effective_mode": "copilot",
    "message_created": true,
    "message_id": "msg_xxx",
    "sources": [{ "id": "kba_xxx", "title": "How refunds work" }],
    "usage": { "input_tokens": 4500, "output_tokens": 230, "cost_usd": 0.04 }
  }
}
```

`mode_override` in the body forces a specific mode for this call only.

## Classify

```bash
curl -X POST https://api.rogeriq.com/api/v1/projects/prj_xxx/agent/classify \
  -H "X-API-Key: riq_xxx" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id": "con_xxx"}'
```

Returns intent, sentiment, suggested priority, and tags. Useful for
triage automation:

```ts
for await (const conv of roger.conversations.listAll({ status: "open" })) {
  const c = await roger.agent.classify(conv.id);
  if (c.priority === "urgent") {
    await roger.conversations.update(conv.id, { priority: "urgent" });
  }
}
```

## Suggest (without posting)

```bash
curl -X POST https://api.rogeriq.com/api/v1/projects/prj_xxx/agent/suggest \
  -H "X-API-Key: riq_xxx" \
  -H "Content-Type: application/json" \
  -d '{"conversation_id": "con_xxx"}'
```

Same retrieval + generation pipeline as `respond`, but never posts.
Returns the suggested text + sources for human review.

## Audit

Every `agent.config.updated` and `agent.responded` event is captured in
the audit log with the acting API key id.