Chat Agents

---
name: chat-agents
description: "Build, use, and troubleshoot Khoj chat, conversation sessions,
  agents, commands, model providers, streaming, and chat tools."
disable-model-invocation: true
metadata:
  disco-role: operating
license: AGPL 3.0
---

# Khoj Chat and Agents

Use this sub-skill when working on Khoj chat behavior, `/api/chat`, `/api/agents`, conversation sessions, chat commands, streaming events, agent configuration, model-provider routing, voice/image/code/research/operator features, or conversation sharing/history/file filters.

## Start Here

- Use `references/chat-api.md` for REST and WebSocket chat endpoints, `ChatRequestBody`, stream events, sessions, history, sharing, titles, message deletion, and conversation file filters.
- Use `references/agent-configuration.md` for `/api/agents`, `ModifyAgentBody`, `ModifyHiddenAgentBody`, privacy levels, tool/output options, hidden agents, file knowledge bases, and chat model selection.
- Use `references/tools-and-commands.md` for slash commands, automatic tool selection, command prerequisites, output modes, and tool failure behavior.
- Use `references/troubleshooting.md` for missing chat model/API key, unsafe prompts, rate limits, local provider mismatches, unavailable web/code/image/voice/operator services, and share-domain errors.
- Use `scripts/inspect_chat_schema.py` to print chat/agent Pydantic schemas, agent enum choices, conversation commands, and stream event names without starting the Khoj server.

## Boundaries

- This sub-skill owns chat request/response behavior, conversation and sharing APIs, agents, tools, model-provider checks, voice response, image/diagram output, code/research/operator routing, and chat-specific troubleshooting.
- Route raw content ingestion, parsing, indexing, and `/api/content` behavior to `content-indexing`.
- Route semantic search internals, query filters, embeddings, reranking, and `/api/search` to `search-retrieval`; chat can use file/query filters, but the search implementation lives there.
- Route scheduled automations, reminders, and memory API behavior to `automations-memory`.
- Route server startup, auth, CORS/host configuration, admin setup, Docker, and broad deployment diagnostics to `deployment-api`.

## Safe Workflow

1. Identify whether the task is chat transport, command/tool selection, agent configuration, model-provider setup, conversation metadata, or feature troubleshooting.
2. Inspect the schema with the bundled helper when payload fields or option values are uncertain; do not import `khoj.main` or run `khoj --help` for schema-only checks.
3. For behavior changes, keep tool prerequisites explicit: chat model/API setup is required for all chat, and `/online`, `/code`, `/image`, `/diagram`, `/research`, `/operator`, and voice each have additional service requirements.
4. For agent changes, distinguish user-facing public/private/protected agents from per-conversation hidden agents, and distinguish agent input tools from chat-only slash commands.
5. For verification, prefer small authenticated API calls or focused unit tests around route/helper behavior; avoid starting browsers, sandboxes, external model calls, or long research/operator runs unless the user explicitly requests operational validation.

## Evidence Basis

This guidance is distilled from Khoj chat and agent routes, conversation helpers, tool processors, model-provider docs, operator notes, and focused tests covering online chat, agent updates, and conversation utilities. It is self-contained for future coding agents and does not require reading original repo docs or tests at runtime.