docyrus-agent-design

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: docyrus-agent-design
description: Design, build, validate, and test a custom Docyrus AI agent end-to-end using the `docyrus agent` CLI commands and its sub-resources. Use when the user wants to create or configure a custom AI agent (assistant/skill/workflow agent) in a dev app — set its instructions, pick its models, toggle capabilities (tools, data sources, files, knowledge base, web search), attach data sources, attach tools, add knowledge docs, wire MCP servers, connect agents (forward/subagent), add dynamic contexts, build workflow steps, or create deployments. Covers choosing the agent shape, the required vs optional config, the sub-resource attach order, and proving the agent is well-formed. Triggers on "create an AI agent", "build an assistant", "configure an agent", "give the agent a data source / tool / knowledge", "agent workflow steps", "agent deployment", "connect agents", `docyrus agent create`, `docyrus agent tools`, `docyrus agent data-sources`, `docyrus agent workflow-steps`, or any custom-agent design + validation task. For authoring the tools an agent calls, use docyrus-app-ai-tools (define with `apps ai-tools`, then attach here with `agent tools`).
---

# Docyrus Agent Design

Build a custom AI agent with `docyrus agent`, then **validate** its configuration and **test** that it's well-formed. An agent is a row in `tenant_ai_agent` (identity + model + capability config) plus a set of **sub-resources** (tools, data sources, docs, MCPs, connections, dynamic contexts, workflow steps, deployments). This skill is the design workflow; the platform's conceptual capability catalog lives in **docyrus-platform** (`references/ai-capabilities.md`), and exhaustive CLI flags are available via `docyrus agent <sub> --help` (command index: **docyrus-cli-app**).

## Workflow

1. **Confirm app + auth.** Agents are dev-app scoped.
   ```bash
   docyrus auth who --json
   docyrus apps list --json          # target appSlug / appId
   ```

2. **Design the agent.** Decide its shape (is it a conversational **assistant**, a callable **skill**, or a **workflow** agent?), its instructions, its default/backup models, and which capabilities it needs (tools? data sources? files? knowledge base? web search?). Toggle a capability **on** before attaching the matching sub-resource. See [references/agent-model.md](references/agent-model.md) to map intent → fields.

3. **Create the agent.** The only required field is `--skillName`. Set identity + model + capability toggles in the same call. See [Create](#create-an-agent).

4. **Attach sub-resources** in this order (each is its own command group, see [Sub-resources](#sub-resources)):
   - **data-sources** the agent can read/write (turn on `--supportDataSources` first),
   - **tools** the agent can call (turn on `--supportTools`; author the tool first with **docyrus-app-ai-tools**, then attach it here),
   - **docs** (knowledge; turn on `--supportKnowledgeBase`), **mcps**, **connections** (forward/subagent), **dynamic-contexts**,
   - **workflow-steps** (only if `--hasWorkflow`), then **deployments** (+ deployment-tools / deployment-data-sources).

5. **Validate** — re-read the agent and each sub-resource list; confirm config + attachments landed. See [Validate](#validate).

6. **Test** — confirm the agent is well-formed (lists cleanly, references resolve) and, where possible, exercise it. See [Test](#test).

A full worked example (assistant with a data source, an attached tool, and a knowledge doc) is in [references/workflow-examples.md](references/workflow-examples.md).

## Command cheat-sheet

Selectors: `--appId | --appSlug`, `--agentId`. Sub-resource **row** id is the generic `--id` (not `--toolId`/`--dataSourceId`). Deployment-nested groups also need `--deploymentId`. Write commands take camelCase flags **or** `--data`/`--from-file` JSON (flags merge over JSON; API keys are **snake_case**). Append `--json`.

### Create an agent

```bash
docyrus agent create --appSlug crm \
  --skil