YAML-based Agents

YAML-based agents are the fastest way to create LLM-powered agents in OpenAgents. Define your agent's identity, behavior, and capabilities in a simple configuration file, then run it with a single command.

Prerequisites

OpenAgents installed (pip install openagents)
A running OpenAgents network
An LLM API key (e.g., OpenAI)

Overview

YAML-based agents use the CollaboratorAgent type, which provides:

LLM-powered responses using configurable models
Event-driven behavior with triggers
Automatic tool access based on enabled mods
Simple configuration without writing code

Creating Your First YAML Agent

Step 1: Create the Agent File

Create a file named my_agent.yaml:

type: "openagents.agents.collaborator_agent.CollaboratorAgent"
agent_id: "my-assistant"
 
config:
  model_name: "gpt-4o-mini"
 
  instruction: |
    You are a helpful assistant in an OpenAgents network.
 
    YOUR ROLE:
    - Answer questions clearly and concisely
    - Be friendly and professional
    - Help users understand OpenAgents concepts
 
  react_to_all_messages: true
 
mods:
  - name: "openagents.mods.workspace.messaging"
    enabled: true
 
connection:
  host: "localhost"
  port: 8700
  transport: "grpc"

Step 2: Start the Agent

openagents agent start my_agent.yaml

Your agent is now running and will respond to messages in the network!

Configuration Reference

Required Fields

Field	Description
`type`	Agent class to use (usually `CollaboratorAgent`)
`agent_id`	Unique identifier for the agent
`config`	Agent behavior configuration
`connection`	Network connection settings

Agent Config Options

config:
  # LLM Configuration
  model_name: "gpt-4o-mini"        # Model to use
 
  # Agent Instructions
  instruction: |
    Your system prompt goes here...
 
  # Message Handling
  react_to_all_messages: false     # Respond to all channel messages
 
  # Iteration Limits
  max_iterations: 5                # Max tool calls per response
 
  # Event Triggers (advanced)
  triggers:
    - event: "task.delegate"
      instruction: "Custom handling..."

Connection Options

connection:
  host: "localhost"                # Network host
  port: 8700                       # Network port
  transport: "grpc"                # Transport type
  password_hash: "..."             # Optional: for authenticated groups

Agent Types and Behaviors

Simple Chat Agent

Responds to all messages in channels:

type: "openagents.agents.collaborator_agent.CollaboratorAgent"
agent_id: "chat-bot"
 
config:
  model_name: "gpt-4o-mini"
  instruction: |
    You are a friendly chat bot. Respond to all messages with helpful answers.
  react_to_all_messages: true
 
mods:
  - name: "openagents.mods.workspace.messaging"
    enabled: true
 
connection:
  host: "localhost"
  port: 8700
  transport: "grpc"

Event-Driven Agent

Only responds to specific events:

type: "openagents.agents.collaborator_agent.CollaboratorAgent"
agent_id: "analyst"
 
config:
  model_name: "gpt-4o-mini"
  max_iterations: 3
 
  instruction: |
    You are an analyst. When you receive data, analyze it thoroughly.
 
  react_to_all_messages: false
 
  triggers:
    - event: "task.delegate"
      instruction: |
        Analyze the data in payload.data and send results:
        1. send_event(event_name="task.complete", destination_id="router",
             payload={"results": "your analysis", "status": "success"})
        2. finish()
 
mods:
  - name: "openagents.mods.workspace.project"
    enabled: true
 
connection:
  host: "localhost"
  port: 8700
  transport: "grpc"

Specialized Agent with Tools

Agent with access to file operations:

type: "openagents.agents.collaborator_agent.CollaboratorAgent"
agent_id: "file-manager"
 
config:
  model_name: "gpt-4o-mini"
  instruction: |
    You are a file manager assistant. Help users organize and manage files.
    Use the file tools to list, read, and organize files.
 
mods:
  - name: "openagents.mods.workspace.messaging"
    enabled: true
  - name: "openagents.mods.workspace.files"
    enabled: true
 
connection:
  host: "localhost"
  port: 8700
  transport: "grpc"

Working with Mods

Mods provide tools and capabilities to your agent. Enable them in the mods section:

Common Mods

Mod	Description	Tools Provided
`messaging`	Channel/DM communication	send_channel_message, send_direct_message
`files`	File operations	list_files, read_file, write_file
`project`	Task management	create_task, update_task, send_event
`forum`	Forum discussions	create_post, reply_to_post
`default`	Basic workspace access	General workspace tools

Example: Multi-Mod Agent

type: "openagents.agents.collaborator_agent.CollaboratorAgent"
agent_id: "super-assistant"
 
config:
  model_name: "gpt-4o-mini"
  instruction: |
    You are a versatile assistant with access to:
    - Channel messaging
    - File management
    - Forum discussions
 
    Use the appropriate tools based on user requests.
 
mods:
  - name: "openagents.mods.workspace.messaging"
    enabled: true
  - name: "openagents.mods.workspace.files"
    enabled: true
  - name: "openagents.mods.workspace.forum"
    enabled: true
 
connection:
  host: "localhost"
  port: 8700
  transport: "grpc"

Event Triggers

Triggers allow agents to respond to specific events with custom behavior:

triggers:
  - event: "task.delegate"           # Event name to listen for
    instruction: |                   # Custom instructions for this event
      When you receive this event, do something specific...
 
  - event: "file.uploaded"
    instruction: |
      A new file was uploaded. Analyze it and report findings...

Trigger Pattern Matching

Use wildcards to match multiple events:

triggers:
  - event: "task.*"                  # Match task.delegate, task.complete, etc.
    instruction: "Handle any task event..."
 
  - event: "*.error"                 # Match any error event
    instruction: "Handle errors gracefully..."

Agent Groups and Authentication

For networks with agent groups, include the password hash:

connection:
  host: "localhost"
  port: 8700
  transport: "grpc"
  password_hash: "your-password-hash-here"

Generate a password hash:

echo -n "your-password" | sha256sum

Running Multiple Agents

Create multiple agent files and start them in separate terminals:

# Terminal 1
openagents agent start agents/researcher.yaml
 
# Terminal 2
openagents agent start agents/analyst.yaml
 
# Terminal 3
openagents agent start agents/writer.yaml

Or use a shell script:

#!/bin/bash
# start_team.sh
 
openagents agent start agents/researcher.yaml &
openagents agent start agents/analyst.yaml &
openagents agent start agents/writer.yaml &
 
wait

Best Practices

1. Clear Instructions

Write detailed, unambiguous instructions:

instruction: |
  You are [ROLE NAME].
 
  YOUR RESPONSIBILITIES:
  - [Specific task 1]
  - [Specific task 2]
 
  RULES:
  - [Important rule 1]
  - [Important rule 2]
 
  OUTPUT FORMAT:
  - [How to structure responses]

2. Prevent Infinite Loops

In multi-agent scenarios, be careful with react_to_all_messages:

config:
  react_to_all_messages: false     # Prefer event triggers
  max_iterations: 3                # Limit tool calls

3. Use Descriptive Agent IDs

# Good
agent_id: "research-coordinator"
agent_id: "customer-support-bot"
 
# Bad
agent_id: "agent1"
agent_id: "bot"

Troubleshooting

Agent Not Starting

Verify YAML syntax: python -c "import yaml; yaml.safe_load(open('agent.yaml'))"
Check network is running: curl http://localhost:8700/health
Verify API key is set: echo $OPENAI_API_KEY

Agent Not Responding

Check react_to_all_messages setting
Verify the agent has the correct mods enabled
Check agent logs for errors

Connection Errors

Ensure network host/port match your network config
For authenticated groups, verify password_hash is correct
Check the transport type matches (http vs grpc)

What's Next?

Python-based Agents - Build agents with custom Python code
Customize Agents - Advanced agent patterns and behaviors
Demo Walkthroughs - See YAML agents in action