agentprofile

AgentProfile

Portable agent profile definition — schema and parser.

AgentProfile defines a single PROFILE.md file that captures everything needed to instantiate an AI agent: identity metadata, model, tools, skills, system prompt, runtime limits, and pointers to companion config files. The format follows the SKILL.md convention — YAML frontmatter for metadata, Markdown body for the system prompt.

Installation

pip install agentprofile

Requires Python ≥ 3.11, < 3.14.

Quick start

Create a PROFILE.md:

---
name: research-assistant
description: Web research agent that summarizes findings with citations
model: gpt-4o-mini
tools:
  - web_search
tags:
  - research
---

You are a research assistant. Always cite sources with URLs.
Prefer primary sources. Be concise.

Load it:

from agentprofile import load_profile

profile = load_profile("PROFILE.md")

profile.name            # "research-assistant"
profile.model           # "gpt-4o-mini"
profile.tools           # ["web_search"]
profile.system_prompt   # "You are a research assistant. Always cite sources..."

Round-trip back to PROFILE.md:

from agentprofile import dumps_profile

md_text = dumps_profile(profile)

Or parse from a string (no file I/O):

from agentprofile import loads_profile

profile = loads_profile(md_text)

Format

A PROFILE.md has two parts:

1. YAML frontmatter (between --- delimiters) — structured metadata
2. Markdown body — becomes the agent's system_prompt (unless overridden by a system_prompt key in frontmatter)

A file without frontmatter is treated entirely as the system prompt.

Frontmatter fields

Runtime limits (harness-specific, optional)

Companion files

Frontmatter can point to JSON files in the same directory as the profile; they are auto-loaded when the profile is loaded from disk:

Companion contents are kept out of frontmatter serialization (exclude=True), so round-tripping a profile never leaks them into the .md.

profile = load_profile("agents/research/PROFILE.md")
profile.provider_options   # dict from provider.json
profile.output_schema_def  # dict from output-schema.json

When using loads_profile() on raw text, pass base_dir= to enable companion loading.

Behavior notes

• Validation: name must match ^[a-zA-Z0-9_-]+$ (1–64 chars); version must be ≥ 1.
• Lenient parsing: unknown frontmatter keys are ignored (extra="ignore").
• Serialization: dumps_profile() omits defaults, nulls, system_prompt (moved to the body), and companion-file fields. Pointers (provider, output_schema) are also omitted since they reference sibling files.

API

Development

uv sync            # install deps + dev group
uv run pytest      # run tests

License

MIT — see LICENSE.