Agent Personality Protocol (APP)

APP is a portable schema and runtime contract for representing agent identity and behavior.

It gives agent runtimes a structured way to carry persona, dynamic state, and behavior rules across frameworks and model providers.

It is designed to sit alongside adjacent systems rather than replace them:

• Tools and data access: MCP
• Agent-to-agent communication: A2A
• Memory backends and orchestration: external runtimes and frameworks
• Identity and behavior: APP

APP standardizes four core objects:

• Profile: stable identity
• State: dynamic runtime state
• MemoryRefs: references to external memory systems
• Policy: behavior mapping rules

Status

APP v1 is an early stable protocol draft with a reference TypeScript runtime in this repository.

The goal of this repo is to make the protocol understandable and implementable, not to define the only valid APP runtime.

Why APP

Today, most agent "personality" lives inside prompts.

That works for small systems, but it is hard to validate, version, inspect, compare, and port across runtimes. APP exists to make identity and behavior explicit data instead of implicit prompt prose.

APP is useful when you want:

• portable agent personas
• inspectable runtime behavior state
• policy-driven behavior changes
• consistent behavior across frameworks or model providers

APP is not trying to replace prompts. A host runtime can still convert APP outputs into prompt instructions, tool heuristics, or other execution-time controls.

Versioning And Conformance

APP uses semantic versioning at the protocol level.

• 1.0 is the initial stable protocol version
• minor versions add backward-compatible fields or clarifications
• major versions may introduce breaking changes

Conformance is claimed per object type, not only for the repository as a whole.

An implementation should state whether it supports:

• APP v1 Profile
• APP v1 State
• APP v1 MemoryRefs
• APP v1 Policy
• APP v1 Session

Version 1 of the protocol is specified in:

• spec/APP-v1.md

Machine-readable validation artifacts:

• schema/app-v1.schema.json

Reference TypeScript runtime:

• npm run build
• npm test
• entrypoint: dist/index.js
• npm run demo:story for a terminal APP-driven story demo

The reference runtime currently provides:

• APP v1 TypeScript types
• document validation helpers
• a minimal evaluator that computes effective behavior from Profile, State, and Policy

This runtime is a reference implementation, not the only valid implementation of APP.

Example:

import { evaluateApp } from "agent-personality-protocol";

const result = evaluateApp({ profile, state, policy });

Implementing APP

The minimum APP v1 implementation contract is intentionally small:

1. parse APP documents
2. validate object structure and required fields
3. evaluate Profile + State + Policy into an effective behavior view
4. treat MemoryRefs as pointers to external memory owned by another system

An implementation does not need to adopt this repository's demo or prompt style to support APP.

Who Consumes APP

APP is typically consumed by the host runtime running an agent, not by the end user directly.

Typical consumers include:

• chat applications with multiple personas
• multi-agent runtimes
• games and simulations
• orchestration layers that want structured behavior control

The host runtime uses APP to answer:

given this agent's profile, current state, and policy, how should it behave right now?

Concrete Integration Example

A host runtime can use APP before every model call:

1. load the agent Profile
2. update the runtime State
3. evaluate APP
4. translate the effective behavior into prompt instructions, tool heuristics, or UI behavior

import { evaluateApp } from "agent-personality-protocol";

const behavior = evaluateApp({ profile, state, policy });

const systemPrompt = `
You are speaking with this behavior:
- Tone: ${behavior.speechStyle.tone ?? "neutral"}
- Verbosity: ${behavior.speechStyle.verbosity ?? "medium"}
- Style: ${(behavior.speechStyle.style ?? []).join(", ")}
- Directness: ${String(behavior.responseConstraints.directness ?? "default")}
`;

const runtimeHeuristics = {
  aggression: behavior.behaviorBiases.aggression ?? 1.0,
  bluffing: behavior.behaviorBiases.bluffing ?? 1.0
};

APP does not generate the response itself. It computes a normalized behavior view that the host runtime can use when generating the response.

LLM integration is optional. APP is still useful without a live model because the protocol can validate, transport, and evaluate agent behavior data on its own.

Evaluator Semantics

The current reference runtime uses these APP v1 semantics:

• default_effect is applied before any matched rule
• rules are evaluated in descending priority
• rules with equal priority preserve source order
• later-applied effects override earlier values for the same key
• object-like effect sections merge by key
• arrays such as speech_style.style are replaced, not concatenated

Terminal Demo

The repository includes a terminal APP-driven story demo about two estranged childhood friends sneaking back into their boarded-up movie theater on its last night before demolition.

The demo uses APP to compute each character's behavior, retrieves backstory through local MemoryRefs, evolves each character's runtime State through a ContextBuilder, and feeds behavior plus memory into an OpenAI prompt.

It also includes:

• scene-beat prompts that push the story through emotional phases
• ambient interruptions from the room itself
• runtime memory that accumulates as the scene unfolds

Run it with:

npm run demo:story

You can provide your API key either by exporting OPENAI_API_KEY first or by pasting it when the demo prompts you.

Optional flags:

npm run demo:story -- --rounds 4
npm run demo:story -- --model gpt-5-mini
npm run demo:story -- --dry-run

The --dry-run mode is only for local testing and does not call OpenAI.

Examples:

• examples/profile.example.json
• examples/state.example.json
• examples/memoryrefs.example.json
• examples/policy.example.json
• examples/session.example.json

Project policies:

• LICENSE
• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• SECURITY.md
• CHANGELOG.md