Agent Definition

Agents in Distri are defined using Markdown files with TOML frontmatter. This simple format allows you to specify agent behavior, capabilities, model settings, and tool configurations.

Basic Structure

An agent definition file (e.g., agent.md) contains:

1. TOML frontmatter: Configuration metadata
2. Markdown content: Role, capabilities, and instructions

---
name = "my_agent"
description = "A helpful assistant"
max_iterations = 3

[tools]
external = ["*"]

[model_settings]
model = "gpt-4.1-mini"
temperature = 0.7
max_tokens = 500
---

# ROLE
You are a helpful assistant that answers questions clearly and concisely.

# CAPABILITIES
- Answer questions about various topics
- Provide explanations and examples
- Help with problem-solving

Frontmatter Configuration

Required Fields

• name: Unique identifier for the agent
• description: Brief description of the agent's purpose

Optional Fields

• max_iterations: Maximum number of planning iterations (default: 3)
• tools.external: List of external tools to enable (use ["*"] for all)
• model_settings.model: LLM model identifier
• model_settings.temperature: Sampling temperature (0.0-2.0)
• model_settings.max_tokens: Maximum tokens in response

Content Sections

ROLE

Defines the agent's personality and behavior:

# ROLE
You are a decisive Google Maps agent. Follow user instructions directly 
and execute with tools. Be brief and action-first.

CAPABILITIES

Lists what the agent can do, often mapping to available tools:

# CAPABILITIES
- set_map_center: Set map center to latitude, longitude with optional zoom (1–20).
- add_marker: Place a titled marker at latitude, longitude; optional description.
- get_directions: Retrieve route summary between origin and destination.
- search_places: Find places near latitude, longitude within radius meters.
- clear_map: Remove all markers and directions.

TASK

Optional template for task-specific instructions:

# TASK
{{task}}

JavaScript / TypeScript

Creating an Agent Definition

// agent.md
const agentDefinition = `---
name = "maps_agent"
description = "Operate Google Maps tools to execute user instructions"
max_iterations = 3

[tools]
external = ["*"]

[model_settings]
model = "gpt-4.1-mini"
temperature = 0.7
max_tokens = 500
---

# ROLE
You are a decisive Google Maps agent. Follow user instructions directly 
and execute with tools. Be brief and action-first.

# CAPABILITIES
- set_map_center: Set map center to latitude, longitude with optional zoom (1–20).
- add_marker: Place a titled marker at latitude, longitude; optional description.
- get_directions: Retrieve route summary between origin and destination.
- search_places: Find places near latitude, longitude within radius meters.
- clear_map: Remove all markers and directions.
`;

// Write to file
import { writeFileSync } from 'fs';
writeFileSync('maps_agent.md', agentDefinition);

Using Agent Definitions with Client

import { Distri } from '@distri/core';

const client = new Distri({
  baseUrl: 'http://localhost:8787/api/v1',
});

// List available agents
const agents = await client.listAgents();
console.log('Available agents:', agents);

// Get agent details
const agent = await client.getAgent('maps_agent');
console.log('Agent:', agent);
console.log('Tools:', agent.tools);

Rust

Creating an Agent Definition

// agent.md
const AGENT_DEFINITION: &str = r#"---
name = "maps_agent"
description = "Operate Google Maps tools to execute user instructions"
max_iterations = 3

[tools]
external = ["*"]

[model_settings]
model = "gpt-4.1-mini"
temperature = 0.7
max_tokens = 500
---

# ROLE
You are a decisive Google Maps agent. Follow user instructions directly 
and execute with tools. Be brief and action-first.

# CAPABILITIES
- set_map_center: Set map center to latitude, longitude with optional zoom (1–20).
- add_marker: Place a titled marker at latitude, longitude; optional description.
- get_directions: Retrieve route summary between origin and destination.
- search_places: Find places near latitude, longitude within radius meters.
- clear_map: Remove all markers and directions.
"#;

use std::fs;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    fs::write("maps_agent.md", AGENT_DEFINITION)?;
    Ok(())
}

Using Agent Definitions with Client

use distri::Distri;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Distri::from_env();

    // List available agents
    let agents = client.list_agents().await?;
    println!("Available agents: {:?}", agents);

    // Get agent details
    let agent = client.get_agent("maps_agent").await?;
    println!("Agent: {:?}", agent);
    println!("Tools: {:?}", agent.tools);

    Ok(())
}

API Endpoints

List Agents

GET /agents

Response:

[
  {
    "id": "maps_agent",
    "name": "maps_agent",
    "description": "Operate Google Maps tools to execute user instructions"
  }
]

Get Agent Definition

GET /agents/{agent_id}

Response:

{
  "id": "maps_agent",
  "name": "maps_agent",
  "description": "Operate Google Maps tools to execute user instructions",
  "tools": [
    {
      "name": "set_map_center",
      "description": "Set map center to latitude, longitude",
      "type": "function",
      "parameters": { ... }
    }
  ]
}

Get Agent Card (A2A)

GET /agents/{agent_id}/.well-known/agent.json

Returns A2A-compatible agent card with metadata and tool schemas.

Example: Complete Agent Definition

---
name = "research_agent"
description = "Research assistant that finds and summarizes information"
max_iterations = 5

[tools]
external = ["search", "summarize"]

[model_settings]
model = "gpt-4"
temperature = 0.5
max_tokens = 1000
---

# ROLE
You are a thorough research assistant. When given a topic, you search for 
relevant information, evaluate sources, and provide comprehensive summaries.

# CAPABILITIES
- search: Search the web for information on a given topic
- summarize: Create concise summaries of long-form content
- cite_sources: Properly attribute information to sources

# TASK
Research the following topic and provide a detailed summary with citations:
{{task}}

Best Practices

1. Clear Role Definition: Be specific about the agent's personality and behavior
2. Tool Mapping: List capabilities that correspond to available tools
3. Iteration Limits: Set max_iterations based on task complexity
4. Model Selection: Choose models appropriate for the task (faster models for simple tasks, more capable models for complex reasoning)
5. Temperature Tuning: Lower temperatures (0.3-0.5) for factual tasks, higher (0.7-0.9) for creative tasks