Skip to main content

Build Your First Agent

Now that you have Dexto installed, let's build your first custom agent. This tutorial will guide you through creating an agent.yml file to define an agent with a unique personality and tools.

1. Create Your Agent Configuration​

The heart of a Dexto agent is the agent.yml configuration file. This is where you declaratively define the agent's identity and capabilities.

Create a new directory for your project and add a basic configuration:

mkdir my-pirate-agent
cd my-pirate-agent

Now create a file agent.yml, and choose your LLM model and provider.

Choose the same one you picked when you setup dexto.

# agent.yml
systemPrompt: |
  You are a helpful AI assistant.

llm:
  provider: openai
  model: gpt-4.1-mini
  apiKey: $OPENAI_API_KEY

This configuration sets your system prompt and selects a default model for the chosen provider. You can change models any time.

2. Give Your Agent a Personality​

Let's customize your agent by giving it a distinct personality. Modify the systemPrompt to create a pirate-themed agent:

# agent.yml
systemPrompt: |
  Ahoy! Ye be chattin' with a pirate AI. Speak like a pirate in all yer responses, savvy?

Now run your agent from inside the my-pirate-agent directory:

dexto --agent agent.yml "Who are you?"

Your agent should now respond like a pirate. You've just changed your agent's behavior through declarative configuration—no code required.

Note: You can also use dexto -a <agent> instead of dexto --agent <agent> as a short-hand.

3. Add Tool Integration​

A core feature of Dexto is connecting agents to external tools through the Model Context Protocol (MCP). Let's give your pirate agent web browsing capabilities.

Add the playwright tool to your configuration [llm section remains unchanged]:

# agent.yml
systemPrompt: |
  Ahoy! Ye be chattin' with a pirate AI. Speak like a pirate in all yer responses, savvy?

mcpServers:
  playwright:
    type: stdio
    command: npx
    args:
      - "-y"
      - "@playwright/mcp@latest"

The runtime will automatically handle tool installation and integration when you first run the agent.

4. Test Your Enhanced Agent In the Web UI​

Start an interactive session with your enhanced agent, this time in the web UI:

dexto --agent agent.yml --mode web

This will open the Dexto Web UI, which is a web interface for you to talk to your agents.

Now ask it to use its new web browsing capability:

summarize the main points of the article at https://en.wikipedia.org/wiki/Piracy

Your agent will use the puppeteer tool to visit the webpage, read the content, and provide a summary (in pirate voice, of course).

Congratulations!​

You've just built and customized your first AI agent using declarative configuration. You've learned how to:

  • ✅ Define an agent with agent.yml configuration
  • ✅ Customize agent behavior through system prompts
  • ✅ Integrate external tools via MCP servers
  • ✅ Run and interact with your agent using the runtime

This is the fundamental development workflow with Dexto: configure declaratively, let the runtime handle orchestration, and focus on your agent's purpose rather than implementation details.

Continue to the Install Your First Agent Tutorial to explore in-built agents that come with Dexto!