yao/agent/docs/configuration.md

Assistant Configuration

Directory Structure

assistants/
└── <assistant-id>/
    ├── package.yao          # Required: Configuration
    ├── prompts.yml          # Optional: Default prompts
    ├── prompts/             # Optional: Prompt presets
    │   ├── chat.yml
    │   └── task.yml
    ├── locales/             # Optional: Translations
    │   ├── en-us.yml
    │   └── zh-cn.yml
    ├── src/                 # Optional: Hook scripts
    │   └── index.ts
    └── mcps/                # Optional: MCP servers
        └── tools.mcp.yao

package.yao

Basic Fields

{
  "name": "{{ name }}",
  "type": "assistant",
  "avatar": "/assets/avatar.png",
  "description": "{{ description }}",
  "connector": "gpt-4o",
  "tags": ["Category1", "Category2"],
  "sort": 1
}

Field	Type	Description
name	string	Display name (supports i18n {{ }})
type	string	Type: assistant (default)
avatar	string	Avatar image path
description	string	Description (supports i18n)
connector	string	LLM connector ID
tags	string[]	Categorization tags
sort	number	Display order

Connector Options

{
  "connector": "gpt-4o",
  "connector_options": {
    "optional": true,
    "connectors": ["gpt-4o", "gpt-4o-mini", "claude-3"],
    "filters": ["tool_calls", "vision"]
  }
}

Field	Type	Description
optional	boolean	Allow user to select connector
connectors	string[]	Available connectors (empty = all)
filters	string[]	Required capabilities: vision, audio, tool_calls, reasoning

Generation Options

{
  "options": {
    "temperature": 0.7,
    "max_tokens": 4096
  }
}

Placeholder (UI Hints)

{
  "placeholder": {
    "title": "{{ chat.title }}",
    "description": "{{ chat.description }}",
    "prompts": [
      "{{ chat.prompts.0 }}",
      "{{ chat.prompts.1 }}"
    ]
  }
}

Visibility & Access

{
  "public": true,
  "share": "team",
  "readonly": true,
  "built_in": true,
  "mentionable": true,
  "automated": false
}

Field	Type	Description
public	boolean	Visible to all users
share	string	Sharing scope: private, team
readonly	boolean	Prevent user modifications
built_in	boolean	System-managed assistant
mentionable	boolean	Can be @mentioned in chat
automated	boolean	Can be triggered automatically

Modes

{
  "modes": ["chat", "task"],
  "default_mode": "task"
}

MCP Servers

{
  "mcp": {
    "servers": [
      "server-id",
      { "server_id": "tools", "tools": ["tool1", "tool2"] },
      { "server_id": "resources", "resources": ["uri://pattern"] }
    ]
  }
}

Knowledge Base

{
  "kb": {
    "collections": ["collection-id-1", "collection-id-2"]
  }
}

Database Models

{
  "db": {
    "models": ["model.name", "another.model"]
  }
}

Uses (Wrapper Tools)

{
  "uses": {
    "vision": "vision-agent",
    "audio": "audio-agent",
    "search": "disabled",
    "fetch": "mcp:fetcher"
  }
}

Field	Description
vision	Vision processing: <agent-id> or mcp:<server>
audio	Audio processing: <agent-id> or mcp:<server>
search	Search: disabled, <agent-id>, or mcp:<server>
fetch	HTTP fetching: <agent-id> or mcp:<server>

Search Configuration

{
  "search": {
    "web": {
      "provider": "tavily",
      "max_results": 10
    },
    "kb": {
      "threshold": 0.7,
      "graph": true
    },
    "db": {
      "max_results": 20
    },
    "citation": {
      "format": "[{index}]",
      "auto_inject_prompt": true
    }
  }
}

Environment Variables

Use $ENV.VAR_NAME for sensitive values:

{
  "connector": "$ENV.LLM_CONNECTOR"
}

Complete Example

{
  "name": "{{ name }}",
  "type": "assistant",
  "avatar": "/assets/assistant.png",
  "connector": "gpt-4o",
  "connector_options": {
    "optional": true,
    "connectors": ["gpt-4o", "gpt-4o-mini"],
    "filters": ["tool_calls"]
  },
  "mcp": {
    "servers": [{ "server_id": "tools", "tools": ["search", "calculate"] }]
  },
  "description": "{{ description }}",
  "options": { "temperature": 0.7 },
  "public": true,
  "placeholder": {
    "title": "{{ chat.title }}",
    "description": "{{ chat.description }}",
    "prompts": ["{{ chat.prompts.0 }}", "{{ chat.prompts.1 }}"]
  },
  "tags": ["Productivity"],
  "modes": ["chat", "task"],
  "default_mode": "chat",
  "sort": 1,
  "readonly": true,
  "mentionable": true
}