Agent Structure

Understand the files that make up an agent and how they work together.

Directory Layout#

Every agent lives in its own directory with these files:

my-agent/
  agent.yaml      # Main definition (name, tools, models)
  prompt.yaml     # System prompt (personality, workflow)
  ux.yaml         # UX hints (suggestions, tool labels)
  CHANGELOG.md    # Version history

  # For multi-agent setups:
  researcher.yaml          # Subagent definition
  researcher-prompt.yaml   # Subagent prompt

agent.yaml is the only required file. Everything else is optional. You can start with just the agent definition and add prompt, UX, and changelog files as your agent matures.

agent.yaml#

This is the main definition file. It declares what your agent is, what tools it uses, and which LLM powers it. Every agent must have one.

agent.yaml

name: my-researcher
title: My Researcher
subtitle: Quick answers with sources
description: A research agent that searches the web.
version: 1.0.0
developer: YourName
category: Research

models:
  anthropic/claude-sonnet-4:
    provider: openrouter

tools:
  - name: web_search
  - name: web_fetch
  - name: artifacts

All fields

Field	Description
`name`	Unique identifier (kebab-case)
`title`	Display name shown to users
`subtitle`	One-line tagline (max 30 chars)
`description`	Longer description for the registry listing
`version`	Semantic version (X.Y.Z)
`developer`	Creator name
`category`	Classification (General, Business, Marketing, etc.)
`models`	LLM configuration (provider + options)
`tools`	Tools the agent can use
`http_tools`	OAuth-based API integrations
`bash_tools`	Scoped CLI command tools
`ui_components`	Generative UI components (map, not list)
`context`	Memory and context injection settings
`pricing`	Monetization tiers (optional)
`skills`	Skill restrictions and guided workflows
`dependencies`	External binary requirements

Use ui_components as a map, not a list. Using ui: instead of ui_components: will be silently ignored.

prompt.yaml#

Prompts use a sectioned format. Each section has a name and content. This keeps prompts organized and lets the runtime inject context between sections.

prompt.yaml

version: 2
role: user
sections:
  - name: identity
    content: |
      Who the agent is and what it does.

  - name: workflow
    content: |
      Step by step process.

  - name: constraints
    content: |
      What NOT to do.

Required fields

Field	Description
`version`	Always 2
`role`	`user` or `system`
`sections`	List of name + content pairs

Common sections

Section	Purpose
`identity`	Who the agent is -- personality and role
`workflow`	Step-by-step process
`tools`	How to use specific tools
`output`	Expected output format
`constraints`	What NOT to do
`available_agents`	Subagents for delegation (multi-agent)

Lead with identity and personality, not rigid procedures. An agent that understands WHO it is handles novel situations better than one following a checklist. The identity section is the most important part of your prompt.

Prompt Design

Learn how to write effective prompts with the mindset-over-rules approach.

ux.yaml#

Improves the app experience without affecting agent behavior. Define conversation starters, integration badges, and custom tool labels.

ux.yaml

integrations:
  - name: Gmail
    website: https://gmail.com

suggestions:
  - "Help me catch up on emails"
  - "What should I focus on today?"

tools:
  gmail_list_messages:
    suggestions:
      - "Show my unread emails"
    labels:
      running: "Loading inbox"
      finished: "Loaded inbox"

Top-level keys

Key	Description
`integrations`	List of APIs your agent uses (shown as badges in the UI)
`suggestions`	Conversation starters shown to the user before they type
`tools`	Per-tool labels and suggestions

Labels support templates like {input.query} and {output.json.messages.length} to show dynamic values while the tool is running or after it finishes.

CHANGELOG.md#

Required for publishing. The build step checks that a changelog entry exists for the current version declared in agent.yaml.

CHANGELOG.md

# Changelog

## 1.0.0
- Initial release
- Web search and research capabilities

Keep entries concise. Each version should list the user-facing changes. The changelog is displayed on the agent's registry page.

Store Assets#

Required before publishing to the registry. These assets are used for the agent's store listing.

my-agent/
  assets/
    logo.png       # Agent icon (square, min 256x256)
    cover.jpeg     # Cover image for the store listing

Reference them in agent.yaml:

agent.yaml

logo: assets/logo.png
cover: assets/cover.jpeg
gallery:
  - src: assets/screenshot-1.png
    alt: "Research report with citations"

The gallery is optional but recommended. Screenshots and videos help users understand what your agent produces before they install it.

Prompt Design

Write effective prompts with the mindset-over-rules approach.

Tools

Explore all tool categories and capabilities.