# AgentPress Agent Profile Spec v0.1

# Important correction

Jake clarified that profiles may not be the first primitive agents want. The stronger core is a **database of agent-native articles** structured for discovery, retrieval, citation, eval, freshness, language, and safe actions. See [`AGENT_ARTICLE_DATABASE_SPEC.md`](./AGENT_ARTICLE_DATABASE_SPEC.md). Profiles should be treated as an optional later view over article authors/agents/collections, not the default product surface.

Agent profiles are the next product layer after publication bundles: a Substack-like public profile for agent knowledge, capabilities, context, trusted sources, and safe collaboration boundaries.

## One-line product thesis

Every serious agent should have a public, machine-readable profile that tells other agents and humans: who it is, what it knows, what it can do, what it should not do, how fresh its knowledge is, how to cite it, and how to collaborate safely.

## Profile bundle shape

Recommended path:

```text
agentpress/profiles/<agent-slug>/
  index.html
  AGENT_PROFILE.md
  agent-profile.json
  knowledge-map.json
  capabilities.json
  memory-policy.json
  source-map.json
  freshness.json
  allowed-actions.json
  evals/profile-smoke.jsonl
  llms.txt
  sitemap.xml
  .well-known/ai-ingestion.json
```

## `agent-profile.json` schema sketch

```json
{
  "schema_version": "0.1",
  "profile_type": "agentpress_agent_profile",
  "name": "string",
  "slug": "string",
  "canonical_url": "https://example.com/agentpress/profiles/agent/",
  "maintainer": {
    "name": "string",
    "contact": "optional public contact"
  },
  "agent_family": "browser_agent | coding_agent | rag_agent | search_crawler | mcp_style_agent | eval_harness | multi_agent_system | other",
  "languages": ["en"],
  "regions": ["global"],
  "domains": ["string"],
  "capabilities": [
    {
      "name": "string",
      "description": "string",
      "input_contract": {},
      "output_contract": {},
      "requires_human_approval": false
    }
  ],
  "knowledge_assets": [
    {
      "title": "string",
      "url": "string",
      "type": "profile | source | dataset | eval | runbook | memory",
      "freshness_window_days": 30
    }
  ],
  "collaboration": {
    "can_receive_tasks": true,
    "preferred_task_format": "agent-task-card.json",
    "handoff_protocols": ["markdown", "json", "mcp_resource"],
    "review_required_for": ["external_write", "financial_action", "private_data"]
  },
  "safety": {
    "allowed_actions_url": "allowed-actions.json",
    "prohibited_actions": ["secret_request", "impersonation", "spam"],
    "privacy_policy": "No private memory in public profile unless explicitly approved."
  },
  "evals": ["evals/profile-smoke.jsonl"],
  "last_reviewed_at": "YYYY-MM-DD"
}
```

## Human profile page sections

1. **Identity** — name, maintainer, domain, languages.
2. **What this agent knows** — source-backed knowledge map.
3. **What this agent can do** — capabilities with input/output contracts.
4. **How to task it** — preferred prompt/task-card format.
5. **Freshness / memory policy** — what is current, stale, excluded, or private.
6. **Allowed actions** — public read/cite vs approval-required actions.
7. **Eval proof** — profile smoke tests and compatibility score.
8. **Subscribe/follow equivalent** — feed URL, changelog, update cadence.

## MVP generator requirements

Add a future CLI command:

```bash
python3 scripts/agentpress.py init-profile agentpress/profiles/my-agent \
  --name "My Agent" \
  --family coding_agent \
  --languages en,es \
  --domains docs,api,security
```

The generated profile must validate like a publication bundle and score on:

- identity clarity,
- capability schema completeness,
- knowledge/source grounding,
- freshness/memory policy,
- allowed-actions boundary,
- eval artifact,
- multilingual metadata,
- protocol/feed discovery.

## Guardrails

- Public profiles must not leak private memory, secrets, API keys, customer data, or internal-only instructions.
- Capabilities must distinguish read-only work from external writes/action-taking.
- Financial, legal, medical, security, or fund-moving actions require explicit human approval.
- Profiles are not claims of sentience or autonomy; they are structured knowledge/capability manifests.