Early prototype

PROFILE.md
for AI agents.

AgentProfile is a lightweight PROFILE.md format and Python parser for packaging an agent's identity, model, tools, skills, handoff behavior, output contract, and system prompt in one version-controlled file.

v0.1.0 — prototype 3 days old
Primary artifact PROFILE.md
Read the docs GitHub
researcher/ PROFILE.md provider.json output-schema.json researcher v1 · PROFILE.md MODEL deepseek:deepseek-v4-pro TOOLS web_search code_runner SKILLS literature-review fact-check → Hand off to writer agent
How to think about it

Like Agent Skills, but for the agent itself.

Agent Skills package what an agent can do. PROFILE.md packages who the agent is: baseline instructions, preferred model, allowed tools, skills, handoff notes, and output schema. 

researcher/
├── PROFILE.md
├── provider.json
└── output-schema.json
badge

Portable identity

Keep an agent's name, description, model, tools, skills, tags, and instructions in one file.

inventory_2

Folder-friendly

Use PROFILE.md plus optional provider.json and output-schema.json companion files.

schema

Validated schema

Pydantic enforces a versioned schema, name pattern, and required frontmatter fields.

sync_alt

Runtime-neutral

Load the same profile from CLIs, agent runtimes, test harnesses, and deployment tools.

PROFILE.md

A readable file humans and runtimes can both use.

Frontmatter holds structured metadata. The Markdown body becomes the system prompt unless a system prompt is explicitly set in frontmatter.

PROFILE.md
---
version: 1
name: researcher
description: Research agent
model: deepseek:deepseek-v4-pro
tools:
  - web_search
skills:
  - literature-review
tags:
  - research
  - citations
handoff_instructions: |
  Hand off open questions to the writer agent
  with a short evidence summary.
provider: provider.json
output_schema: output-schema.json
---

You are a careful research agent. Cite sources, separate facts from assumptions,
and hand off unresolved questions clearly.
Python
from agentprofile import load_profile, dumps_profile

profile = load_profile("./researcher/PROFILE.md")

print(profile.name)
print(profile.version)
print(profile.model)
print(profile.system_prompt)
print(profile.provider_options)

# Round-trip back to PROFILE.md
markdown = dumps_profile(profile)
How it works

Small format, clear lifecycle.

01

Discovery

A runtime reads lightweight metadata such as name, description, and version.

02

Validation

Pydantic checks the version, name pattern, required fields, and frontmatter shape.

03

Activation

The full PROFILE.md body becomes the agent's system prompt unless overridden in frontmatter.

04

Companions

Provider options and output schemas are loaded from files next to the profile.

05

Execution

The runtime maps model, tools, skills, and schema into its own agent API.

Status

Early prototype. Schema may change.

AgentProfile is a 3-day-old prototype with a validated Pydantic schema and a PROFILE.md parser. It is not yet published on PyPI, has no CLI or MCP server, and the format is subject to change as we learn what fields matter for multi-agent team formation.

The current focus is validating the fields against real multi-agent workflows before committing to a stable format. Install from GitHub to experiment: 

pip install "agentprofile @ git+https://github.com/open-assistants-lab/AgentProfile.git"
Where it fits

One piece of the local agent stack.

PROFILE.md defines who the agent is.

Agent Skills define reusable capabilities and workflows.

ConnectKit connects user accounts and tools.

CoreMem retrieves what the agent remembers.

HybridDB stores local searchable data.