agent.yaml Reference

The agent.yaml file controls the AI agent's behavior — system prompt, MCP server connections, and starter messages. It is loaded once at startup.

Location

By default Nibchat looks for agent.yaml in the working directory. Override with:

AGENT_CONFIG_PATH=/path/to/my-agent.yaml

In Docker, mount your file and set the path:

# docker-compose.yml
services:
  server:
    volumes:
      - ./my-agent.yaml:/app/agent.yaml

Full example

agent:
  name: Acme Agent
  description: |
    You are a customer support agent for Acme Corp.

  icon: |
    data:image/svg+xml;base64,PHN2ZyB3aWR0...
    
  instructions: |
    - Always greet the user warmly.
    - For billing issues, ask for their account email and escalate to billing@acme.com.
    - For technical issues, try to resolve them using the knowledge base tool.
    - Never share internal pricing structures.
    - If unsure, say so and offer to connect the user with a human agent.

  starterMessages:
    - "I need help with my account"
    - "I have a billing question"
    - "Something isn't working"
    - "I'd like to cancel my subscription"

  mcpServers:
    - url: https://files.acme.com/mcp
      name: files

    - url: https://crm.acme.com/mcp
      name: crm
      headers:
        Authorization: "Bearer crm-api-key"

Fields

name

The name of your agent.

description

A brief description of your agent's capabilities displayed on the splash screen

icon / iconDark

The icon or logo for your agent in base64 format (png, jpeg, svg)

instructions

A string injected as the system message before every conversation. Supports multiline YAML syntax (|).

Nibchat appends its own internal directives (memory instructions, tool guidance) after your system prompt.

starterMessages

An optional list of suggested messages shown when the chat is empty. Limited to 4 displayed at a time in the UI.

starterMessages:
  - "What can you help me with?"
  - "Show me your available tools."

mcpServers

An array of MCP server configurations.

mcpServers:
  - url: https://server-url/sse   # Required
    name: myserver                # Optional, used as tool prefix
    headers:                      # Optional, bypasses OAuth
      Authorization: "Bearer token"

Field	Required	Description
url	Yes	SSE endpoint URL of the MCP server.
name	No	Friendly name. Used as a prefix (name__toolname) when tool names collide across servers. Defaults to the hostname.
headers	No	Static headers sent with every request. When set, OAuth is skipped.

mcpServer (legacy)

Single-server shorthand from earlier versions. Accepts the same fields as a single mcpServers entry. Use mcpServers (array) for new configurations.

Hot reload

agent.yaml is read once at process startup. Restart the server (or container) after making changes.