Open source · MIT · on PyPI

Every agent deserves
A PROFILE.md.

Agent identity as code: a minimal schema and parser that defines what an agent is — name, model, tools, skills, handoff instructions, output schema, and hard runtime limits — in one human-readable Markdown file, following the SKILL.md convention.

v0.2.1 — pip install agentprofile Python 3.11–3.14
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

Portable identity

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

Folder-friendly

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

Validated schema

Pydantic enforces version 1, the ^[a-zA-Z0-9_-]+$ name pattern (max 64), required fields, and runtime limits. Unknown fields are ignored.

Runtime-neutral

Load the same profile from any agent runtime, test harness, or deployment tool.

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
max_llm_calls: 50
cost_limit_usd: 1.0
timeout_seconds: 300
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, loads_profile, dumps_profile

# From a file
profile = load_profile("./researcher/PROFILE.md")

# Or from a string you already have in memory
profile = loads_profile(profile_md_text, base_dir="./researcher")

print(profile.name, profile.version)
print(profile.max_llm_calls, profile.cost_limit_usd, profile.timeout_seconds)
print(profile.system_prompt)

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

Small format, clear lifecycle.

01

Write

Author PROFILE.md — YAML frontmatter for metadata, Markdown body for the system prompt.

02

Validate

Pydantic checks the version, the ^[a-zA-Z0-9_-]+$ name pattern, required fields, and runtime limits.

03

Load

load_profile splits frontmatter from the body; the body becomes the system prompt unless frontmatter overrides it.

04

Round-trip

dumps_profile re-emits canonical PROFILE.md, dropping runtime-only fields — edit, reload, repeat.

Status

Early prototype. Schema may change.

AgentProfile is an early prototype with a validated Pydantic schema and a PROFILE.md parser. It is not yet published on PyPI and ships no command-line tool or MCP server. The format is subject to change as we learn what fields matter for multi-agent teams.

The roadmap is a bridge library — the pandoc of agent definitions — that converts between agent formats (Agent Format, Open Agent Spec, SKILL.md, ...). Feedback is welcome on GitHub.

Share feedback on GitHub
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.

FAQ

Questions, answered.

What is AgentProfile?

AgentProfile is a portable agent identity format: a PROFILE.md that declares an agent's name, description, model, tools, skills, tags, handoff instructions, provider, output schema, and cost limits — so any runtime can load the same agent.

What fields does an agent profile contain?

name, description, model, tools, skills, tags, handoff_instructions, provider, output_schema, max_llm_calls, cost_limit_usd, and timeout_seconds — parsed from PROFILE.md by agentprofile/parser.py.

How do I create an agent profile?

Write a PROFILE.md with the schema fields and run the parser — it validates the profile and produces a structured agent definition any runtime can consume.

How is AgentProfile different from AGENTS.md?

AGENTS.md is guidance for coding agents working in a repo. AgentProfile is a structured, validated identity for the agent itself — with typed fields, output schemas, and hard cost and time limits.

How is AgentProfile different from gitagent or the .agents protocol?

Those package whole agent directories — tools, scripts, assets — as portable runtime artifacts. AgentProfile is the unit of identity itself: a single PROFILE.md with a validating parser and enforceable runtime limits, small enough to version control, diff, and hand off.

Can AgentProfile enforce cost and timeout limits?

Yes. max_llm_calls, cost_limit_usd, and timeout_seconds are first-class fields, so runtimes can cap spend and runtime per agent.

Is AgentProfile free and open source?

Yes — MIT-licensed, on PyPI (pip install agentprofile), and part of the Open Assistants stack.

What Python versions does AgentProfile support?

Python 3.11 through 3.13 (3.14 incoming). The parser is pure Python with Pydantic validation — no runtime dependencies beyond the schema layer.