Skip to main content

Installing Custom Agents

Dexto makes it easy to install and use custom AI agents. Whether you're using pre-built agent templates from the registry or creating your own from scratch, this guide covers everything you need to know.

What are Custom Agents?​

Custom agents are specialized AI configurations tailored for specific tasks. They can include:

  • Custom system prompts – Define the agent's personality and behavior
  • LLM settings – Choose specific models and providers
  • Tools and MCP servers – Enable specific capabilities
  • Memory and storage – Configure how agents remember context

Dexto provides two ways to install custom agents:

  1. From the CLI – Using dexto agents install command
  2. From the Web UI – Using the "+New Agent" button

Installing from CLI​

Installing Pre-built Agents from Registry​

Dexto comes with a curated registry of agent templates ready to use:

# List available agents
dexto agents list

# Install a specific agent
dexto agents install nano-banana-agent

# Install multiple agents at once
dexto agents install podcast-agent database-agent music-agent

# Install all available agents
dexto agents install --all

Available agent templates include:

  • nano-banana-agent – Image generation and editing with Google Nano Banana
  • podcast-agent – Podcast generation with multi-speaker TTS
  • database-agent – SQL queries and database operations
  • image-editor-agent – Image manipulation and editing
  • music-agent – Music creation and audio processing
  • pdf-agent – Document analysis and conversation
  • product-researcher – Product naming and branding research
  • triage-agent – Multi-agent customer support routing
  • workflow-builder-agent – n8n workflow automation
  • product-analysis-agent – PostHog product analytics
  • gaming-agent – Play GameBoy games like Pokemon

Installing from a Local File​

You can install an agent from a local YAML configuration file:

dexto agents install ./my-agent.yml

Dexto will prompt you for metadata:

  • Agent ID – Unique identifier (lowercase, hyphens only)
  • Agent Name – Display name shown in UI
  • Description – Brief description of what the agent does
  • Author – Your name or organization
  • Tags – Comma-separated categories

Example:

$ dexto agents install ./coding-assistant.yml

📝 Custom Agent Installation
Agent name: coding-assistant
Description: A specialized coding assistant with best practices
Author: Your Name
Tags (comma-separated): coding, development, productivity

✅ coding-assistant installed successfully

Installing from a Directory​

For more complex agents with multiple files (prompts, tools, resources):

dexto agents install ./my-complex-agent/

Dexto will ask for:

  1. Metadata (same as file installation)
  2. Main config file – Which YAML file is the entry point (e.g., agent.yml)

Directory structure example:

my-complex-agent/
├── agent.yml              # Main config (specified during install)
├── prompts/
│   ├── system.txt
│   └── examples.txt
└── tools/
    └── custom-tool.js

Installation Options​

Force Reinstall:

dexto agents install nano-banana-agent --force

Preferences at startup:

Installation copies the agent files without writing global preferences into them. The CLI applies your configured LLM preferences in memory when starting the agent; reinstalling does not disable those preferences. API keys are loaded from the environment, including ~/.dexto/.env.

Installing from Web UI​

The Web UI provides a visual way to create custom agents without writing YAML files.

Steps to Create an Agent​

  1. Open the Web UI:

    dexto

  2. Click "+New Agent" in the agent selector (top of the interface)

  3. Fill out the form:

    Basic Information:

    • Agent ID – Unique identifier (e.g., my-research-agent)
    • Agent Name – Display name (e.g., Research Assistant)
    • Description – What the agent does
    • Author – Your name (optional)
    • Tags – Comma-separated (e.g., research, analysis, custom)

    LLM Configuration:

    • Provider – Choose from OpenAI, Anthropic, Google, etc.
    • Model – Select the specific model (e.g., gpt-5, claude-sonnet-4-5)
    • API Key – Enter your API key (stored securely in ~/.dexto/.env)

    System Prompt:

    • Write the agent's instructions and behavior guidelines

  4. Click "Create Agent"

The agent is immediately available in the agent switcher!

Web UI Features​

  • Visual Configuration – No YAML syntax required
  • Secure Key Storage – API keys are stored in .dexto/.env with environment variable references
  • Instant Availability – Created agents appear immediately in all Dexto modes
  • Edit Later – Use the "Edit Agent" button to modify configuration

Where Agents are Stored​

All installed agents (both CLI and Web UI) are stored in:

~/.dexto/agents/<agent-id>/

For registry agents:

~/.dexto/agents/nano-banana-agent/
└── nano-banana-agent.yml

For custom agents:

~/.dexto/agents/my-custom-agent/
├── agent.yml              # Main configuration
└── .registry-metadata.json # Installation metadata

Using Installed Agents​

In Web UI (Default)​

# Use default agent (opens Web UI)
dexto

# Use specific installed agent (opens Web UI)
dexto --agent nano-banana-agent

Use the agent selector dropdown (top of web UI) to switch between installed agents.

In CLI Mode​

# Use default agent in CLI
dexto --mode cli

# Use specific installed agent in CLI
dexto --agent nano-banana-agent --mode cli

# Switch LLM during CLI session
dexto --mode cli
> /model switch

In Other Modes​

# MCP server with custom agent
dexto --mode mcp --agent coding-assistant

Managing Installed Agents​

List Installed Agents​

# Show all agents (registry + installed)
dexto agents list

# Show only installed agents
dexto agents list --installed

# Show detailed information
dexto agents list --verbose

Find Agent Location​

dexto which nano-banana-agent
# Output: /Users/you/.dexto/agents/nano-banana-agent/nano-banana-agent.yml

Uninstall Agents​

# Uninstall specific agent
dexto agents uninstall nano-banana-agent

# Uninstall multiple agents
dexto agents uninstall agent1 agent2 agent3

# Uninstall all agents
dexto agents uninstall --all

Creating Your Own Agent Template​

Want to create a shareable agent template? Here's the structure:

Single-File Agent​

my-agent.yml:

llm:
  provider: anthropic
  model: claude-sonnet-4-5-20250929
  apiKey: $ANTHROPIC_API_KEY

systemPrompt: |
  You are a specialized assistant for data analysis.

  Your expertise includes:
  - Statistical analysis
  - Data visualization recommendations
  - Python/R code generation

  Always provide clear explanations alongside code.

memory:
  enabled: true
  maxTokens: 10000

tools:
  browserUse:
    enabled: true
  filesystem:
    enabled: true

Install with:

dexto agents install ./my-agent.yml

Directory-Based Agent​

For complex agents with multiple configuration files:

project-manager-agent/

project-manager-agent/
├── agent.yml              # Main config
├── prompts/
│   ├── system.md          # System prompt
│   └── examples.md        # Few-shot examples
├── mcp/
│   └── mcp-config.yml     # MCP server configurations
└── README.md              # Documentation

agent.yml:

llm:
  provider: openai
  model: gpt-5
  apiKey: $OPENAI_API_KEY

systemPrompt:
  type: file
  path: ./prompts/system.md

mcp:
  - name: github
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_TOKEN: $GITHUB_TOKEN

Install with:

dexto agents install ./project-manager-agent/
# When prompted for "Main config file:", enter: agent.yml

Best Practices​

✅ DO:​

  • Use descriptive agent IDs – data-analysis-agent not agent1
  • Write clear descriptions – Help users understand the agent's purpose
  • Use environment variables for API keys – Never hardcode secrets
  • Test thoroughly – Try the agent in different scenarios
  • Document custom tools – Explain any special configuration
  • Version your agents – Use git for custom agent directories

❌ DON'T:​

  • Don't use spaces in agent IDs – Use kebab-case: my-agent not my agent
  • Don't hardcode API keys – Use env vars: $ANTHROPIC_API_KEY
  • Don't override registry agents – Choose unique IDs
  • Don't skip descriptions – They help users find the right agent
  • Don't create overly complex configs – Keep it simple and focused

Troubleshooting​

Agent doesn't appear after installation​

  • Check installation completed successfully (look for ✅ message)
  • Verify agent exists: dexto which <agent-id>
  • Restart Dexto if in interactive mode
  • Check ~/.dexto/agents/<agent-id>/ directory exists

"Agent ID already exists" error​

  • The ID conflicts with a bundled agent or existing custom agent
  • Choose a different, unique ID
  • To reinstall, use dexto agents install --force <agent>

API key not working​

  • Ensure the key is in ~/.dexto/.env: 
    OPENAI_API_KEY=sk-...
    ANTHROPIC_API_KEY=sk-ant-...
  • Use the correct env var name in agent config: $OPENAI_API_KEY
  • Run dexto setup to configure keys globally

Custom agent YAML syntax errors​

  • Validate YAML syntax online or with a linter
  • Check indentation (use 2 spaces, not tabs)
  • Ensure all required fields are present
  • See agent configuration guide for valid schema

Next Steps​