Getting Started with Agent-Flavored Markdown

This guide walks through the implementation of a simple Friendly Assistant agent, introducing AFM concepts.

Agent File Structure

AFM is a simple, Markdown-based format for defining AI agents. It uses Markdown for instructions with YAML front matter for configuration and metadata. This improves authoring and readability of AI agents for both humans and machines.

An AFM file has two main parts:

1. Front Matter: A YAML block at the top of the file, enclosed by ---. It contains metadata and configuration for the agent, such as its name, the AI model it uses, and any tools it has access to.
2. Markdown Body: The rest of the file, which contains the agent's instructions written in Markdown. This is where you define the agent's role (its purpose and responsibilities) and its instructions (directives governing its behavior).

Your First AFM Agent

Let's create a simple "Friendly Assistant" agent. We'll start by defining what the agent does, and then we'll add the necessary metadata and configuration.

1. Defining the Role and Instructions

The core of any agent is its Role and Instructions. This is where you define the agent's persona and the tasks it should perform.

For our Friendly Assistant, we'll keep it simple:

# Role

You are a friendly and helpful conversational assistant. Your purpose is to engage in
natural, helpful conversations with users, answering their questions, providing
information, and assisting with various tasks to the best of your abilities.

# Instructions

- Always respond in a friendly and conversational tone
- Keep your responses clear, concise, and easy to understand
- If you don't know something, be honest about it
- Ask clarifying questions when the user's request is ambiguous
- Be helpful and try to provide practical, actionable advice
- Maintain context throughout the conversation
- Show empathy and understanding in your responses

• # Role: Defines the agent's purpose and responsibilities (its persona).
• # Instructions: Provides directives governing the agent's behavior.

2. Adding Metadata and Configuration

Next, we add the Front Matter. This is the YAML block at the top of the file that contains metadata about the agent and configuration for the AI model it will use.

---
spec_version: "0.3.0"
name: "Friendly Assistant"
description: "A friendly conversational assistant that helps users with various tasks."
version: "0.1.0"
license: "Apache-2.0"
model:
  name: "gpt-4o"
  provider: "openai"
  authentication:
    type: "api-key"
    api_key: "${env:OPENAI_API_KEY}"
interfaces:
  - type: "consolechat"
---

• spec_version: Specifies the version of the AFM specification the file adheres to.
• name: The name of the agent.
• description: A short description of what the agent does.
• version: The version of the agent.
• model: This section specifies the AI model the agent will use. In this example, we use OpenAI's gpt-4o model. The variable substitution indicates that the API key should be retrieved from an environment variable named OPENAI_API_KEY.
• interfaces: This section defines how the agent can be interacted with. In this case, we're exposing it as a command-line chat interface.

3. The Complete AFM File

Putting it all together, our complete friendly_assistant.afm.md file looks like this:

friendly_assistant.afm.md

---
spec_version: "0.3.0"
name: "Friendly Assistant"
description: "A friendly conversational assistant that helps users with various tasks."
version: "0.1.0"
license: "Apache-2.0"
model:
  name: "gpt-4o"
  provider: "openai"
  authentication:
    type: "api-key"
    api_key: "${env:OPENAI_API_KEY}"
interfaces:
  - type: "consolechat"
---

# Role

You are a friendly and helpful conversational assistant. Your purpose is to engage in
natural, helpful conversations with users, answering their questions, providing
information, and assisting with various tasks to the best of your abilities.

# Instructions

- Always respond in a friendly and conversational tone
- Keep your responses clear, concise, and easy to understand
- If you don't know something, be honest about it
- Ask clarifying questions when the user's request is ambiguous
- Be helpful and try to provide practical, actionable advice
- Maintain context throughout the conversation
- Show empathy and understanding in your responses

What's Next?

Use the AFM file with a tool or platform that supports AFM. See Reference Implementations for options. For a complete overview of all AFM features, see the Specification.