Defining Agents with YAML

The AIGNE Framework supports a declarative approach for defining agents using YAML configuration files. This method separates the agent's definition (its properties, instructions, and skills) from the application's business logic, promoting better organization, reusability, and easier management of complex agentic systems.

This guide provides a comprehensive overview of the YAML syntax for defining various agent types and their properties.

Basic Structure#

Every agent definition, regardless of its type, is contained within a .yaml file. The type attribute is the primary discriminator that determines the agent's behavior and required properties. If the type is omitted, it defaults to ai.

Here is a fundamental example of an AI agent configuration:

chat.yaml

name: Basic Chat Agent
description: A simple agent that responds to user messages.
type: ai
instructions: "You are a helpful assistant. Respond to the user's message concisely."
input_key: message
skills:
  - my-skill.js

Core Properties#

The following properties are common across most agent types:

name
string

A human-readable name for the agent.

description
string

A brief description of the agent's purpose and capabilities.

type
string
default:ai

Specifies the agent's type. Determines the required fields and behavior. Valid types include ai, image, team, transform, mcp, and function.

model
object | string

Configuration for the chat model used by the agent, overriding any globally defined model. Can be a string or a detailed object.

skills
array

A list of other agents or JavaScript/TypeScript functions that this agent can use as tools. Each skill is referenced by its file path.

inputSchema
object | string

A JSON schema defining the expected input structure. Can be an inline object or a path to an external .json or .yaml file.

outputSchema
object | string

A JSON schema for structuring the agent's output. Can be an inline object or a path to an external file. This is crucial for enabling structured output.

memory
boolean | object

Enables statefulness for the agent. Set to true for default memory or provide a configuration object for specific providers.

hooks
array

Defines lifecycle hooks (onStart, onSuccess, onError, onEnd) that trigger other agents at different stages of execution.

Loading External Prompts and Schemas#

To maintain clean and modular configurations, you can load agent instructions and schemas from external files. This is particularly useful for complex prompts or reusable data structures.

External Instructions#

For ai and image agents, instructions can be lengthy. You can define them in a separate Markdown or text file and reference it using the url key.

chat-with-prompt.yaml

name: chat-with-prompt
description: An AI agent with instructions loaded from an external file.
type: ai
instructions:
  url: prompts/main-prompt.md
input_key: message
memory: true
skills:
  - skills/sandbox.js

The main-prompt.md file contains the raw text that will be used as the agent's system prompt.

prompts/main-prompt.md

You are a master programmer. When the user asks for code, provide a complete, runnable example and explain the key parts.

You can also construct a multi-part prompt with different roles:

multi-role-prompt.yaml

instructions:
  - role: system
    url: prompts/system-role.md
  - role: user
    content: "Here is an example of a good response:"
  - role: assistant
    url: prompts/example-response.md

External Schemas#

Similarly, inputSchema and outputSchema can reference external JSON or YAML files that define the schema structure.

structured-output-agent.yaml

name: JSON Extractor
type: ai
instructions: Extract the user's name and email from the text.
outputSchema: schemas/user-schema.yaml

The user-schema.yaml file would contain the JSON schema definition:

schemas/user-schema.yaml

type: object
properties:
  name:
    type: string
    description: The full name of the user.
  email:
    type: string
    description: The email address of the user.
required:
  - name
  - email

Agent Type Specifics#

The following sections detail the unique configuration properties for each agent type.

AI Agent (type: ai)#

The AIAgent is the most common type, designed for general-purpose interaction with language models.

ai-agent-example.yaml

type: ai
name: Customer Support AI
instructions:
  url: prompts/support-prompt.md
input_key: customer_query
output_key: response
# Enforce the model to call a specific skill
tool_choice: "sandbox"
outputSchema: schemas/support-response.yaml
skills:
  - sandbox.js
instructions
string | object | array

The system prompt or instructions for the AI model. Can be a simple string, a reference to an external file (url), or an array of message objects (role, content/url).

inputKey
string

The key in the input object that contains the main user message to be sent to the model.

outputKey
string

The key under which the AI's final text response will be placed in the output object.

toolChoice
string

Forces the model to use a specific skill (tool). The value must match the name of a skill attached to the agent.

Team Agent (type: team)#

The TeamAgent orchestrates a collection of child agents (defined under skills) to perform a multi-step task.

team-agent-example.yaml

type: team
name: Research and Write Team
# Agents will run one after another
mode: sequential
# The output of this team will be the collected outputs of all steps
include_all_steps_output: true
skills:
  - url: agents/researcher.yaml
  - url: agents/writer.yaml
  - url: agents/editor.yaml
mode
string
default:sequential

The execution mode for the team. Can be sequential (agents run in order) or parallel (agents run concurrently).

iterateOn
string

The key in the input object containing an array. The team will execute its workflow for each item in the array.

reflection
object

Configures a self-correction loop where a reviewer agent inspects the output and can trigger re-runs until the output is approved.

Image Agent (type: image)#

The ImageAgent is specialized for generating images using an image model.

image-agent-example.yaml

type: image
name: Logo Generator
instructions: "A minimalist, flat-design logo for a tech startup named 'Innovate'."
# Pass through specific options to the image model provider
model_options:
  quality: hd
  style: vivid
instructions
string | object
required

The prompt describing the desired image. Unlike the AI agent, this is a mandatory field.

modelOptions
object

A key-value map of provider-specific options to control image generation (e.g., quality, style, size).

Transform Agent (type: transform)#

The TransformAgent uses a JSONata expression to declaratively map, filter, or restructure JSON data without writing code.

transform-agent-example.yaml

type: transform
name: User Formatter
description: Extracts and formats user names from a list.
jsonata: "payload.users.{'name': firstName & ' ' & lastName}"
jsonata
string
required

The JSONata expression to execute against the input data.

Summary#

Defining agents via YAML offers a powerful, declarative alternative to programmatic definition. It allows for clear separation of concerns, enhances reusability, and simplifies the management of agent configurations. By leveraging external files for prompts and schemas, you can build complex, modular, and maintainable AI systems.

For more hands-on examples, refer to the other guides in the Advanced Topics section.

Advanced Topics
Prompts