# Agent Card Schema — Layer 3 Entity Type # KNO Schema Version: 0.2.1 # CHANGELOG: # 0.2.1 (M22 P-B, #2674): Declare `agent-card-schema` as the P10 wire-projection # target of the new `agent-blueprint@0.2.0` substrate. Agent cards on the # A2A wire are now derived (one P10 thin transformation) from agent-blueprint # entities at `content/agent-blueprints/*.kno`; the substrate carries the # full persona (perception/goals/boundaries/composes) and the wire envelope # is the `a2a_projection` sub-tree. Adds no fields; no breaking changes. # 0.2.0 (M52 P4.1, #2139): Add `visibility: public` collection default per REQ-18. # # An Agent Card describes an A2A-compatible agent: its identity, capabilities, # skills, authentication requirements, and ownership context. # # EXTENDS: document-schema.kno (which composes identity, history, quality) # USE CASES: # - Platform agents (auth-agent, infra-agent) # - Per-possibility agents (future tenant-scoped agents) # - External agent registration # # DESIGN DECISIONS: # - DD-A2A-01: Agent Cards are .kno entities; /.well-known/agent.json is derived # - DD-A2A-02: Ownership context distinguishes platform vs tenant agents # # MAPS TO: a2a-js SDK AgentCard interface (A2A Protocol Specification § 5.5) # ============================================================================= # SCHEMA DECLARATION # ============================================================================= $schema: kno@0.0.9 # ============================================================================= # IDENTITY # ============================================================================= id: 01KKSY7MK56WAKNP2QVKKZ1RXP slug: agent-card-schema type: spec version: 0.2.1 # ============================================================================= # VISIBILITY DECLARATION (REQ-18) — collection default # ============================================================================= # Agent-card entities (content/agents/*.kno) are public reference knowledge by # default — they describe Possibility-discoverable agents and are consumed by # the A2A surface. Per REQ-18, individual entities MAY override with their own # `visibility:` field (last-write-wins at the entity level). Drives the # four-surface contract per kno-system_architecture.md § Agent Surface # Integration and public-surface-parity.instructions.md. visibility: public # ============================================================================= # STANDARD TIER # ============================================================================= title: "Agent Card Schema" purpose: | Define the schema for A2A Agent Cards — machine-readable descriptions of agents that participate in the A2A protocol. **What is an Agent Card?** An Agent Card is a JSON document that describes an agent's identity, capabilities, authentication requirements, and skills. It enables agent-to-agent discovery and interoperability via the A2A protocol. **Ownership Contexts:** | Context | Description | Example | |------------|--------------------------------|--------------------------| | `platform` | Operated by Possibility itself | auth-agent, infra-agent | | `tenant` | Scoped to a specific realm | per-possibility agents | **A2A Protocol Mapping:** The .kno entity is the source of truth. The `/.well-known/agent.json` endpoint serves a thin transformation to standard A2A JSON format (P10). **Layer 3 Position**: Agent Card extends document (Layer 2), which composes identity, history, and quality (Layer 1). **v0.2.0 — Perception, Goals, Boundaries (M22-P2 F1, #849):** Three new optional rich-tier blocks make the Agent Card a complete description of an agentic actor — not just *who it is and what it can do* (v0.1.0 A2A protocol surface), but also *what it sees, what it's trying to achieve, and what it must not do*: | Block | Purpose | Required? | |---|---|---| | `perception.domains[]` | What data sources / signal types the agent monitors | Optional — agents without perception (e.g. echo agents) leave empty or omit | | `goals[]` | Measurable outcomes the agent is trying to achieve | Optional — recommended for non-trivial personas | | `boundaries[]` | Constraints on agent behaviour (MUST NOT / SHOULD NOT) | Optional but recommended for any agent with side effects | **Bidirectional perception (P10 derivable):** the forward direction is declared on the agent card (`perception.domains[]`); the reverse projection ("which agents subscribe to domain X?") is computed at runtime by `getAgentsForDomain(domain)`, not stored. This unlocks capability-based routing in F3 (#851) without hardcoded persona IDs in routing rules (blindspot B-004). **Open enum for perception domains:** values in `perception.domains[]` are slugs that MUST resolve to a `content/perception-domains/*.kno` entity (per `specs/perception-domain-schema.kno`). New domains are added by creating new .kno files in that directory — no schema change required. Drift-guard test asserts every referenced domain exists. **Composition with `service-config-schema`:** existing agent instances in `content/agents/*.kno` declare `$schema: service-config@0.3.0` with `subtype: agent-card` rather than `$schema: agent-card@0.2.0` directly. This is intentional — agent-card-schema documents the agent-specific fields; service-config-schema is the universal binding for any provisioned platform service. v0.2.0 stays additive so existing instances adopt by adding the new fields, not by changing $schema. **v0.2.1 — Projection target of `agent-blueprint@0.2.0` (M22 P-B, #2674):** As of Phase B of the M22 #2674 substrate migration (DD-A2A-01 Path X), agent personas live in `content/agent-blueprints/*.kno` under `agent-blueprint@0.2.0`. Each blueprint carries the full persona (`persona.{safety_level, lifecycle, perception, goals, boundaries}`, `composes`, `ownership`, `provenance.migration`) AND a wire-projection sub-tree (`a2a_projection`). The platform projects agent-blueprint entities onto agent-card-shaped JSON for the A2A wire via a single P10 thin transformation (`buildAgentCard` in `services/pspace-api/src/a2a/routes.ts` reads the blueprint and emits the projection). This schema therefore now plays two roles: 1. The legacy direct `$schema: agent-card@0.2.0` shape for any remaining direct authors (none in-repo as of Phase B). 2. The **projection-target shape** that agent-blueprint substrate entities project onto for the A2A wire surface. Future evolution of agent-card fields MUST keep both roles in mind: any new optional field is automatically available to projection authors via the `a2a_projection` sub-tree of agent-blueprint without a substrate-shape change. # ============================================================================= # RICH TIER — Taxonomy # ============================================================================= provenance: origin: id: 01KKSY7MK56WAKNP2QVKKZ1RXP timestamp: "2026-03-15T23:45:00Z" tool: manual taxonomy: topics: - a2a - agents - discovery - interoperability keywords: - agent-card - a2a-protocol - agent-discovery - capabilities - skills # ============================================================================= # RICH TIER — Relationships # ============================================================================= relationships: extends: - xri: "kno://specs/document-schema" reason: "Layer 2 base type" depends_on: - xri: "kno://specs/kno-spec" reason: "Defines kno@0.0.9 schema structure" composes: - xri: "kno://specs/identity-schema" reason: "id, slug" - xri: "kno://specs/history-schema" reason: "_history" - xri: "kno://specs/quality-schema" reason: "quality" related_to: - xri: "kno://specs/role-schema" reason: "Agents may fulfill roles defined by role-schema" - xri: "kno://specs/capability-schema" reason: "Skills map to capabilities in the ontology" - xri: "kno://specs/service-config-schema" reason: "Agent endpoints are service configurations" - xri: "kno://specs/platform-capability-schema" reason: "Agent Cards are derived from Platform Capability entities via thin transformation (P10). GAP-02: `capabilities` here means A2A protocol features; Platform Capabilities use `a2a.protocol_capabilities` to avoid collision." quality: completeness: 0.8 last_reviewed: "2026-03-15" review_status: draft # ============================================================================= # HISTORY # ============================================================================= _history: version: 2 created: "2026-03-15T23:45:00Z" created_by: "pspace-core-team" modified: "2026-04-25T22:00:00Z" modified_by: "claude" # ============================================================================= # SPECIFICATION # ============================================================================= spec: status: Draft changelog: - version: "0.2.1" date: "2026-04-29" changes: - "Add OPTIONAL `budget_override` block (M22-P3 PR-2). Per-agent override of the process-template `budget_policy`. Strict-additive bump — v0.2.0 instances remain valid." - "Allow `agent-card@0.2.1` in `$schema` enum." - version: "0.2.0" date: "2026-04-25" changes: - "Add `perception` block — domains[] (slug refs to content/perception-domains/*.kno) + refresh strategy. Closes M22-P2 F1 (#849)." - "Add `goals[]` block — measurable outcomes with id, description, metric, target. Supports `target_query` for dynamic targets (per #2018 futro carry-forward)." - "Add `boundaries[]` block — natural-language constraints (MUST NOT / SHOULD NOT) on agent behaviour." - "All three new blocks are OPTIONAL — strict-additive minor bump per #2020 spike. Existing v0.1.0 instances remain valid." - "Bidirectional perception projection (P10): forward direction declared per agent; reverse direction derived at runtime via getAgentsForDomain(). Unblocks capability-based routing in F3 (#851); mitigates blindspot B-004." - version: "0.1.0" date: "2026-03-15" changes: - "Initial creation for Issue #179 (A2A Foundation)" - "Maps to a2a-js SDK AgentCard interface" - "Adds ownership.context for platform vs tenant agents (DD-A2A-01)" - "Supports per-realm authentication endpoints (DD-A2A-02)" schema: type: object required: - id - name - url - version - capabilities - skills - ownership properties: # ----------------------------------------------------------------------- # BASIC TIER — Identity (inherited from kno-spec) # ----------------------------------------------------------------------- $schema: type: string enum: - "agent-card@0.1.0" - "agent-card@0.2.0" - "agent-card@0.2.1" description: | Schema declaration. Either v0.1.0 or v0.2.0 is valid; v0.2.0 adds optional perception/goals/boundaries blocks. Note that most actual agent instances declare `service-config@0.3.0` with `subtype: agent-card` rather than referencing this schema directly — see purpose statement § Composition. id: type: string description: "Unique identifier (ULID) for this agent card" examples: - "01KKSY7MK56WAKNP2QVKKZ1RXP" slug: type: string description: "Human-readable identifier for the agent" examples: - "echo-agent" - "auth-agent" - "infra-agent" # ----------------------------------------------------------------------- # STANDARD TIER — A2A Protocol Fields # Maps directly to a2a-js AgentCard interface # ----------------------------------------------------------------------- name: type: string description: "Human-readable name of the agent" examples: - "Echo Agent" - "Possibility Auth Agent" description: type: string description: "Human-readable description. CommonMark may be used." examples: - "Echoes back messages for testing A2A connectivity" url: type: string description: "Base URL endpoint for the agent's A2A service" examples: - "https://api.possibility.space/a2a" - "https://api.possibility.space/a2a/auth/v1" version: type: string description: "Version string for the agent (semver recommended)" examples: - "0.1.0" documentation_url: type: string description: "URL to human-readable documentation" examples: - "https://possibility.space/docs/agents/echo" provider: type: object description: "Organization or entity providing the agent" properties: organization: type: string description: "Name of the providing organization" url: type: string description: "URL for the provider's website" required: - organization examples: - organization: "Possibility" url: "https://possibility.space" capabilities: type: object description: "A2A protocol features supported by this agent" properties: streaming: type: boolean description: "Supports tasks/sendSubscribe and SSE" default: false push_notifications: type: boolean description: "Supports webhook-based task updates" default: false state_transition_history: type: boolean description: "Includes status change history in Task objects" default: false authentication: type: object description: "Authentication requirements for the agent's endpoint" properties: schemes: type: array items: type: string description: "Supported auth scheme names (e.g., Bearer, OAuth2)" examples: - ["Bearer"] credentials: type: string description: "Non-secret scheme configuration (e.g., tokenUrl). MUST NOT contain secrets." default_input_modes: type: array items: type: string description: "MIME types the agent accepts as input" default: ["text/plain"] examples: - ["text/plain"] - ["text/plain", "application/json"] default_output_modes: type: array items: type: string description: "MIME types the agent produces as output" default: ["text/plain"] examples: - ["text/plain"] skills: type: array description: "Capabilities the agent offers. Must contain at least one." items: type: object required: - id - name properties: id: type: string description: "Unique identifier for this skill within the agent" name: type: string description: "Human-readable skill name" description: type: string description: "What the skill does. CommonMark may be used." tags: type: array items: type: string description: "Keywords for discoverability" examples: type: array items: type: string description: "Example prompts or use cases" input_modes: type: array items: type: string description: "Overrides agent's defaultInputModes for this skill" output_modes: type: array items: type: string description: "Overrides agent's defaultOutputModes for this skill" examples: - id: echo name: Echo description: "Echoes back the input message" tags: ["testing", "diagnostics"] # ----------------------------------------------------------------------- # RICH TIER — Possibility-Specific Extensions # ----------------------------------------------------------------------- ownership: type: object description: "Ownership context for this agent (DD-A2A-01)" required: - context properties: context: type: string enum: - platform - tenant description: | Whether this agent is platform-wide or scoped to a realm. - platform: Operated by Possibility, available to all realms - tenant: Scoped to a specific possibility's realm possibility_slug: type: string description: "Required when context is 'tenant'. Identifies the realm." # ----------------------------------------------------------------------- # RICH TIER — Perception (v0.2.0, M22-P2 F1, #849) # ----------------------------------------------------------------------- perception: type: object description: | What data sources / signal types the agent monitors. Forward declaration of P10 derivable structure: agents declare their perception domains; the reverse projection (`getAgentsForDomain(domain)`) is computed at runtime, not stored. F3 routing rules name a domain (capability), not an agent ID, and dispatch via this projection — see #851. OPTIONAL. Agents that don't perceive (e.g. echo agents) may omit this block or declare an empty `domains: []`. properties: domains: type: array items: type: string description: | Slugs of `content/perception-domains/*.kno` entities. Open enum: new domains are added by creating new perception-domain .kno files, not by changing this schema. Drift-guard test asserts every referenced domain has a corresponding file. examples: - ["schemas", "api-surface"] - ["entity-health", "drift-surfaces"] - [] refresh: type: string enum: - on-change - periodic - on-demand - scheduled description: | When the agent updates its perception: - on-change: react to events as they happen (e.g. via F3 tap) - periodic: poll on a fixed cadence - on-demand: refresh only when invoked - scheduled: continuous monitoring with a fixed cadence (continuous-lifecycle agents) # ----------------------------------------------------------------------- # RICH TIER — Goals (v0.2.0, M22-P2 F1, #849) # ----------------------------------------------------------------------- goals: type: array description: | Measurable outcomes the agent is trying to achieve. Each goal binds a metric to a target so agent effectiveness can be assessed against ground truth. Goals SHOULD be measurable, not aspirational — "find drift" is too vague; "0 unresolved drift findings older than 7 days" is verifiable. OPTIONAL but recommended for any persona that takes initiative. Agents whose only role is to respond to requests (echo, synchronous tools) MAY omit goals. items: type: object required: - id - description properties: id: type: string description: "Stable identifier within this agent (kebab-case)" examples: - "goal-1" - "drift-detection" - "principled-reviews" description: type: string description: "Human-readable goal statement" metric: type: string description: | Name of the metric used to measure progress. SHOULD correspond to an OTel metric, observation count, or computable property of the agent's output. examples: - "drift_findings_per_sweep" - "review_severity_distribution" target: type: string description: | Literal target value (string for flexibility: ">0", "≥99.9%", "0", "<5s p95"). MUTUALLY EXCLUSIVE with target_query. examples: - "0" - ">0 per weekly scan" - "<5s p95" target_query: type: string description: | Dynamic target expression (WOQL or jq) evaluated at metric-collection time. Use when the target depends on runtime state (e.g. "0 unresolved drift findings" where the set of drift surfaces grows as the system grows). MUTUALLY EXCLUSIVE with target. examples: - "drift_surfaces.count == 0" - "perception_domains.length" # ----------------------------------------------------------------------- # RICH TIER — Boundaries (v0.2.0, M22-P2 F1, #849) # ----------------------------------------------------------------------- boundaries: type: array description: | Natural-language constraints on agent behaviour. Each entry SHOULD start with "MUST NOT" (hard prohibition) or "SHOULD NOT" (advisory) so the constraint type is unambiguous. Boundaries are documentation + design intent — runtime enforcement is the agent implementation's responsibility. OPTIONAL but recommended for any agent with side effects. Helps reviewers, downstream agents, and humans understand the agent's scope without reading the implementation. items: type: string examples: - "MUST NOT modify .kno files directly (propose via STRUCTURE phase)" - "MUST NOT exceed 3 LLM calls per analysis pass" - "SHOULD NOT operate on entities older than 90 days without explicit invocation" # ----------------------------------------------------------------------- # RICH TIER — Budget Override (v0.2.1, M22-P3 PR-2) # ----------------------------------------------------------------------- budget_override: type: object description: | OPTIONAL per-agent override of the process-template's `budget_policy` (process-template-schema v0.2.0). When present, the runtime applies these values instead of (or in addition to) the template policy. Field-level merge: fields set here win; fields omitted fall through to the template. Use cases: - A12 Hindsight Reviewer needs more headroom than the template default for large AC histories. - A research persona running a one-off deep dive may raise the cap for a single invocation. Routing semantics (`on_breach`) are inherited from the template policy unless overridden here. properties: max_invocation_tokens: type: integer minimum: 1 max_phase_tokens: type: integer minimum: 1 warn_threshold_pct: type: number minimum: 0 maximum: 1 cost_ceiling_usd: type: number minimum: 0 on_breach: type: string enum: - blocked - failed # ============================================================================= # EXAMPLES # ============================================================================= examples: - title: "Platform Echo Agent" description: "Minimal agent card for the echo test agent" content: | $schema: agent-card@0.1.0 id: 01KKSY8ABC123DEF456GHI789 slug: echo-agent name: Echo Agent description: Echoes back messages for testing A2A connectivity url: https://api.possibility.space/a2a version: "0.1.0" provider: organization: Possibility url: https://possibility.space capabilities: streaming: false push_notifications: false skills: - id: echo name: Echo description: Echoes back the input message tags: [testing, diagnostics] ownership: context: platform - title: "Platform Auth Agent" description: "Agent card for the auth provisioning agent" content: | $schema: agent-card@0.1.0 id: 01KKSY9XYZ789ABC123DEF456 slug: auth-agent name: Possibility Auth Agent description: | Provisions and manages Keycloak realms, clients, roles, and SMTP configuration for per-possibility authentication. url: https://api.possibility.space/a2a/auth/v1 version: "0.1.0" provider: organization: Possibility url: https://possibility.space capabilities: streaming: true push_notifications: false authentication: schemes: [Bearer] skills: - id: provision-realm name: Provision Realm description: Create a new pspace-{slug} Keycloak realm tags: [auth, provisioning, keycloak] - id: configure-realm-oauth name: Configure Realm OAuth description: Set up per-realm OIDC discovery and branding tags: [auth, oauth, oidc] - id: configure-realm-smtp name: Configure Realm SMTP description: Configure per-realm email sender tags: [auth, email, smtp] - id: create-realm-roles name: Create Realm Roles description: Define roles within a target realm tags: [auth, roles, rbac] - id: deprovision-realm name: Deprovision Realm description: Tear down realm and all associated resources tags: [auth, provisioning, cleanup] ownership: context: platform