diff --git a/examples/bobs-brain/README.md b/examples/bobs-brain/README.md new file mode 100644 index 0000000..66cb9f4 --- /dev/null +++ b/examples/bobs-brain/README.md @@ -0,0 +1,149 @@ +# Bob's Brain - AI Card Reference Implementation + +**Status:** Production-grade multi-agent system +**Tech Stack:** Google ADK 1.18.0, Vertex AI Agent Engine, A2A Protocol 0.3.0 +**Repository:** https://github.com/jeremylongshore/bobs-brain + +--- + +## Overview + +Bob's Brain is a **production-grade ADK agent department** that demonstrates comprehensive implementation of both: +- **A2A Protocol 0.3.0** (current AgentCard format) +- **AI Card Standard v1.0** (new universal format) + +This directory contains reference examples showing how to convert existing A2A AgentCards to the new universal AI Card format while maintaining backward compatibility. + +--- + +## What Makes Bob's Brain Notable + +### Multi-Agent Architecture +- **1 global orchestrator** (bob) coordinating specialist departments +- **1 foreman agent** (iam-senior-adk-devops-lead) managing department tasks +- **8 specialist agents** (iam-adk, iam-issue, iam-fix-plan, iam-fix-impl, iam-qa, iam-docs, iam-cleanup, iam-index) + +### Production Patterns Demonstrated +- ✅ **Hard Mode Rules (R1-R8)** - CI-enforced architectural standards preventing drift +- ✅ **Inline Source Deployment** - Deploy source code directly to Agent Engine (no pickle serialization) +- ✅ **Dual Memory Architecture** - Session Cache + Memory Bank for real agent continuity +- ✅ **A2A Protocol** - Full AgentCard implementation with foreman-worker pattern +- ✅ **SPIFFE Identity** - Immutable identity framework for clean tracing +- ✅ **Workload Identity Federation** - Keyless CI/CD authentication +- ✅ **ARV Gates** - Agent Readiness Verification in deployment pipeline +- ✅ **Comprehensive CI/CD** - 8 GitHub Actions workflows with drift detection + +### Standards-Based Documentation +- **141 organized docs** in `000-docs/` following Document Filing System v3.0 +- **28 canonical standards** (6767-series) reusable across repos +- **Complete DevOps playbook** generated via `/appaudit` analysis +- **20+ operational guides** for deployment, monitoring, troubleshooting + +--- + +## Files in This Directory + +### 1. `ai-card.json` - New Universal AI Card Format (v1.0) +The AI Card standard format showing: +- SPIFFE ID as primary identity +- Trust attestations (Hard Mode compliance, CI/CD gates, WIF auth) +- A2A protocol service with complete skill definitions +- Publisher information and metadata + +### 2. `agent-card-a2a.json` - Original A2A AgentCard Format (v0.3.0) +Current A2A protocol AgentCard for comparison showing: +- Protocol version 0.3.0 +- Skills with input/output schemas +- SPIFFE identity propagation +- Transport preferences + +### 3. `conversion-guide.md` - Migration Guide +Step-by-step guide for converting A2A AgentCards to AI Card format including: +- Field mapping reference +- Identity migration (SPIFFE) +- Service configuration +- Trust attestation examples + +--- + +## Key Implementation Details + +### SPIFFE Identity Pattern +``` +spiffe://intent.solutions/agent/bobs-brain/prod/us-central1/0.12.0 + └─ trust domain ─┘ └─ workload path (agent/name/env/region/version) ┘ +``` + +### Hard Mode Rules (R1-R8) +1. **R1: ADK-Only** - No LangChain, CrewAI, or mixed frameworks +2. **R2: Agent Engine Runtime** - Vertex AI managed runtime only +3. **R3: Gateway Separation** - Cloud Run proxies, no embedded runners +4. **R4: CI-Only Deployments** - GitHub Actions with WIF, no manual gcloud +5. **R5: Dual Memory Wiring** - Session + Memory Bank required +6. **R6: Single Docs Folder** - All docs in `000-docs/` +7. **R7: SPIFFE ID Propagation** - In AgentCard, logs, headers +8. **R8: Drift Detection** - Runs first in CI, blocks violations + +### A2A Protocol Implementation +- **Protocol Version:** 0.3.0 +- **Transport:** JSONRPC over HTTPS +- **Skills:** 3 core skills (ADK Q&A, doc search, deployment guidance) +- **Authentication:** OAuth2 client credentials (future) +- **Gateway:** Cloud Run service at https://a2a-gateway.bobs-brain.run.app + +### Trust Attestations +- **HardModeCompliance** - R1-R8 enforced via CI drift detection +- **CI-CD-Gates** - Drift detection, ARV validation, WIF authentication +- **InlineDeployment** - Source code deployment (not pickle/serialization) +- **DualMemoryArchitecture** - Session Cache + Memory Bank wired correctly + +--- + +## How to Use This Reference + +### For Template Adopters +1. Copy the AI Card structure from `ai-card.json` +2. Update SPIFFE ID with your trust domain and workload path +3. Customize skills and capabilities for your agent +4. Add relevant trust attestations for your deployment + +### For A2A → AI Card Migration +1. Start with your existing `agent-card.json` (A2A format) +2. Follow `conversion-guide.md` for field mapping +3. Test backward compatibility with A2A protocol +4. Deploy both formats during transition period + +### For New Implementations +1. Start with `ai-card.json` as template +2. Implement A2A protocol in `services.a2a` section +3. Add other protocols (MCP, etc.) as needed in `services` +4. Use SPIFFE for identity where possible + +--- + +## Production Metrics + +- **Version:** 0.12.0 (current production) +- **Deployment:** Vertex AI Agent Engine (us-central1) +- **Availability:** 99.9% uptime (Cloud Run + Agent Engine) +- **Response Time:** < 200ms (gateway) + agent processing time +- **Memory:** Dual-layer (Session + Memory Bank) with automatic persistence +- **Test Coverage:** 65%+ across all agents +- **Documentation:** 141 files, 28 canonical standards + +--- + +## Links + +- **Repository:** https://github.com/jeremylongshore/bobs-brain +- **Documentation:** See `000-docs/` directory +- **Master Index:** `000-docs/6767-DR-INDEX-bobs-brain-standards-catalog.md` +- **Hard Mode Spec:** `000-docs/6767-DR-STND-adk-agent-engine-spec-and-hardmode-rules.md` +- **Operations Runbook:** `000-docs/6767-RB-OPS-adk-department-operations-runbook.md` +- **DevOps Playbook:** `000-docs/680-AA-AUDT-appaudit-devops-playbook.md` + +--- + +**Reference Implementation for:** Linux Foundation AI Card Standard +**Last Updated:** 2025-12-02 +**Contact:** jeremy@intentsolutions.io diff --git a/examples/bobs-brain/agent-card-a2a.json b/examples/bobs-brain/agent-card-a2a.json new file mode 100644 index 0000000..5a8cc04 --- /dev/null +++ b/examples/bobs-brain/agent-card-a2a.json @@ -0,0 +1,185 @@ +{ + "protocol_version": "0.3.0", + "name": "bobs-brain", + "version": "0.12.0", + "description": "Bob's Brain - Expert Google ADK Agent\n\n**Identity:** spiffe://intent.solutions/agent/bobs-brain/prod/us-central1/0.12.0\n\nBob is an expert Google Agent Development Kit (ADK) specialist who helps prodelopers:\n- Design and build AI agents using Google ADK\n- Understand ADK architecture patterns and best practices\n- Implement tools, multi-agent systems, and workflows\n- Deploy agents to Vertex AI Agent Engine\n- Debug agent issues and optimize performance\n- Integrate with Google Cloud services (BigQuery, Vertex AI Search, Memory Bank)\n\nBob has access to comprehensive ADK documentation and can provide expert guidance with accurate code examples, deployment commands, and architectural recommendations based on official Google patterns.\n", + "url": "https://bob.intent.solutions", + "preferred_transport": "JSONRPC", + "additional_interfaces": [ + { + "url": "https://bob.intent.solutions", + "transport": "JSONRPC" + } + ], + "provider": { + "organization": "Intent Solutions", + "url": "https://intent.solutions" + }, + "documentation_url": "https://github.com/jeremylongshore/bobs-brain", + "icon_url": null, + "capabilities": [ + "adk_expertise", + "documentation_search", + "code_examples", + "deployment_guidance", + "architecture_review" + ], + "default_input_modes": [ + "text" + ], + "default_output_modes": [ + "text" + ], + "skills": [ + { + "name": "Answer ADK Question", + "description": "Provide expert answers about Google ADK using documentation and examples", + "input_schema": { + "type": "object", + "required": [ + "question" + ], + "properties": { + "question": { + "type": "string", + "description": "Question about Google ADK" + }, + "context": { + "type": "string", + "description": "Additional context (optional)" + } + } + }, + "output_schema": { + "type": "object", + "required": [ + "answer" + ], + "properties": { + "answer": { + "type": "string", + "description": "Expert answer with code examples and references" + }, + "references": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Relevant documentation references" + } + } + }, + "id": "bob.answer_adk_question", + "tags": [ + "bob", + "answer_adk_question" + ], + "examples": [] + }, + { + "name": "Search ADK Documentation", + "description": "Search local and Vertex AI Search documentation for ADK information", + "input_schema": { + "type": "object", + "required": [ + "query" + ], + "properties": { + "query": { + "type": "string", + "description": "Search query" + }, + "max_results": { + "type": "integer", + "default": 5, + "description": "Maximum results to return" + } + } + }, + "output_schema": { + "type": "object", + "required": [ + "results" + ], + "properties": { + "results": { + "type": "array", + "items": { + "type": "object", + "properties": { + "title": { + "type": "string" + }, + "content": { + "type": "string" + }, + "source": { + "type": "string" + } + } + } + } + } + }, + "id": "bob.search_adk_docs", + "tags": [ + "bob", + "search_adk_docs" + ], + "examples": [] + }, + { + "name": "Provide Deployment Guidance", + "description": "Guide users through deploying agents to Vertex AI Agent Engine", + "input_schema": { + "type": "object", + "required": [ + "deployment_scenario" + ], + "properties": { + "deployment_scenario": { + "type": "string", + "description": "Description of what needs to be deployed" + }, + "current_setup": { + "type": "string", + "description": "Current environment setup (optional)" + } + } + }, + "output_schema": { + "type": "object", + "required": [ + "steps", + "commands" + ], + "properties": { + "steps": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Step-by-step deployment instructions" + }, + "commands": { + "type": "array", + "items": { + "type": "string" + }, + "description": "Exact commands to run" + } + } + }, + "id": "bob.provide_deployment_guidance", + "tags": [ + "bob", + "provide_deployment_guidance" + ], + "examples": [] + } + ], + "security": null, + "security_schemes": null, + "supports_authenticated_extended_card": false, + "spiffe_id": "spiffe://intent.solutions/agent/bobs-brain/prod/us-central1/0.12.0" +} \ No newline at end of file diff --git a/examples/bobs-brain/ai-card.json b/examples/bobs-brain/ai-card.json new file mode 100644 index 0000000..45adfe6 --- /dev/null +++ b/examples/bobs-brain/ai-card.json @@ -0,0 +1,228 @@ +{ + "$schema": "https://a2a-protocol.org/ai-card/v1/schema.json", + "specVersion": "1.0", + + "id": "spiffe://intent.solutions/agent/bobs-brain/prod/us-central1/0.12.0", + "identityType": "spiffe", + "name": "Bob's Brain - ADK Compliance Department", + "description": "Production-grade multi-agent system for Google ADK/Vertex compliance auditing and automated fixes. Enforces Hard Mode rules (R1-R8) with CI-driven drift detection.", + "logoUrl": null, + "maturity": "stable", + + "publisher": { + "id": "spiffe://intent.solutions/org/intent-solutions", + "identityType": "spiffe", + "name": "Intent Solutions", + "url": "https://intent.solutions", + "attestation": { + "type": "OrganizationIdentity", + "description": "Verified organization identity via SPIFFE trust domain" + } + }, + + "trust": { + "attestations": [ + { + "type": "HardModeCompliance", + "description": "R1-R8 architectural rules enforced via CI drift detection", + "details": { + "rules": [ + "R1: ADK-Only (no LangChain/CrewAI mixing)", + "R2: Vertex AI Agent Engine runtime (managed only)", + "R3: Gateway separation (Cloud Run proxies)", + "R4: CI-only deployments (WIF auth)", + "R5: Dual memory wiring (Session + Memory Bank)", + "R6: Single docs folder (000-docs/)", + "R7: SPIFFE ID propagation", + "R8: Drift detection (CI-first gate)" + ], + "enforcement": "Automated CI checks block non-compliant code", + "verification": "scripts/ci/check_nodrift.sh" + } + }, + { + "type": "CI-CD-Gates", + "description": "Comprehensive deployment pipeline with ARV validation", + "details": { + "workflows": 8, + "gates": ["drift-detection", "tests", "arv-minimum", "build", "deploy"], + "authentication": "Workload Identity Federation (keyless)", + "platform": "GitHub Actions" + } + }, + { + "type": "InlineDeployment", + "description": "Source code deployment (not pickle/serialization)", + "details": { + "pattern": "inline-source", + "runtime": "Vertex AI Agent Engine", + "standard": "000-docs/6767-INLINE-DR-STND-inline-source-deployment-for-vertex-agent-engine.md" + } + }, + { + "type": "DualMemoryArchitecture", + "description": "Session Cache + Memory Bank for real agent continuity", + "details": { + "session_service": "VertexAiSessionService", + "memory_service": "VertexAiMemoryBankService", + "pattern": "after_agent_callback wiring (R5 compliance)" + } + } + ], + "privacyPolicyUrl": null, + "termsOfServiceUrl": null + }, + + "services": { + "a2a": { + "type": "a2a", + "name": "Bob's Brain A2A Interface", + "description": "Expert Google ADK agent with documentation search and deployment guidance", + "protocolSpecific": { + "protocolVersion": "0.3.0", + "supportedInterfaces": [ + { + "transport": "JSONRPC", + "url": "https://a2a-gateway.bobs-brain.run.app" + } + ], + "securitySchemes": { + "note": "OAuth2 client credentials planned for future release" + }, + "skills": [ + { + "id": "bob.answer_adk_question", + "name": "Answer ADK Question", + "description": "Provide expert answers about Google ADK using documentation and examples", + "inputModes": ["application/json"], + "outputModes": ["application/json", "text/plain"], + "inputSchema": { + "type": "object", + "required": ["question"], + "properties": { + "question": { + "type": "string", + "description": "Question about Google ADK" + }, + "context": { + "type": "string", + "description": "Additional context (optional)" + } + } + }, + "outputSchema": { + "type": "object", + "required": ["answer"], + "properties": { + "answer": { + "type": "string", + "description": "Expert answer with code examples and references" + }, + "references": { + "type": "array", + "items": { "type": "string" }, + "description": "Relevant documentation references" + } + } + }, + "tags": ["adk", "documentation", "q-and-a"] + }, + { + "id": "bob.search_adk_docs", + "name": "Search ADK Documentation", + "description": "Search local and Vertex AI Search documentation for ADK information", + "inputModes": ["application/json"], + "outputModes": ["application/json"], + "inputSchema": { + "type": "object", + "required": ["query"], + "properties": { + "query": { + "type": "string", + "description": "Search query" + }, + "max_results": { + "type": "integer", + "default": 5, + "description": "Maximum results to return" + } + } + }, + "outputSchema": { + "type": "object", + "required": ["results"], + "properties": { + "results": { + "type": "array", + "items": { + "type": "object", + "properties": { + "title": { "type": "string" }, + "content": { "type": "string" }, + "source": { "type": "string" } + } + } + } + } + }, + "tags": ["adk", "search", "documentation"] + }, + { + "id": "bob.provide_deployment_guidance", + "name": "Provide Deployment Guidance", + "description": "Guide users through deploying agents to Vertex AI Agent Engine", + "inputModes": ["application/json"], + "outputModes": ["application/json"], + "inputSchema": { + "type": "object", + "required": ["deployment_scenario"], + "properties": { + "deployment_scenario": { + "type": "string", + "description": "Description of what needs to be deployed" + }, + "current_setup": { + "type": "string", + "description": "Current environment setup (optional)" + } + } + }, + "outputSchema": { + "type": "object", + "required": ["steps", "commands"], + "properties": { + "steps": { + "type": "array", + "items": { "type": "string" }, + "description": "Step-by-step deployment instructions" + }, + "commands": { + "type": "array", + "items": { "type": "string" }, + "description": "Exact commands to run" + } + } + }, + "tags": ["deployment", "agent-engine", "vertex-ai"] + } + ] + } + } + }, + + "createdAt": "2025-01-15T10:00:00Z", + "updatedAt": "2025-12-02T18:00:00Z", + + "metadata": { + "region": "us-central1", + "environment": "production", + "version": "0.12.0", + "runtime": "Vertex AI Agent Engine", + "architecture": "multi-agent-department", + "agents_count": 10, + "documentation_files": 141, + "canonical_standards": 28, + "test_coverage": "65%+", + "repository": "https://github.com/jeremylongshore/bobs-brain" + } +} diff --git a/examples/bobs-brain/conversion-guide.md b/examples/bobs-brain/conversion-guide.md new file mode 100644 index 0000000..d51de1d --- /dev/null +++ b/examples/bobs-brain/conversion-guide.md @@ -0,0 +1,403 @@ +# A2A AgentCard → AI Card Conversion Guide + +**Version:** 1.0 +**Date:** 2025-12-02 +**Purpose:** Guide for migrating existing A2A AgentCards (v0.3.0) to universal AI Card format (v1.0) + +--- + +## Overview + +This guide shows how to convert an existing A2A AgentCard to the new universal AI Card format while maintaining backward compatibility with the A2A protocol. + +**Key Benefits of AI Card:** +- ✅ **Protocol-agnostic** - Support A2A, MCP, and custom protocols in one card +- ✅ **Trust attestations** - Document compliance, certifications, security posture +- ✅ **Rich identity** - SPIFFE, DID, or custom identity systems +- ✅ **Publisher information** - Clear attribution and organization details +- ✅ **Extensible metadata** - Custom fields for deployment, versioning, metrics + +--- + +## Quick Comparison + +### A2A AgentCard (v0.3.0) +```json +{ + "protocol_version": "0.3.0", + "name": "bobs-brain", + "version": "0.12.0", + "description": "...", + "url": "https://bob.intent.solutions", + "preferred_transport": "JSONRPC", + "skills": [...] +} +``` + +### AI Card (v1.0) +```json +{ + "$schema": "https://a2a-protocol.org/ai-card/v1/schema.json", + "specVersion": "1.0", + "id": "spiffe://intent.solutions/agent/bobs-brain/prod/us-central1/0.12.0", + "identityType": "spiffe", + "name": "Bob's Brain", + "services": { + "a2a": { + "type": "a2a", + "protocolSpecific": { + "protocolVersion": "0.3.0", + "skills": [...] + } + } + } +} +``` + +--- + +## Field Mapping Reference + +### Top-Level Fields + +| A2A AgentCard (v0.3.0) | AI Card (v1.0) | Notes | +|------------------------|----------------|-------| +| N/A | `$schema` | Required. Points to AI Card JSON schema | +| N/A | `specVersion` | Required. Currently "1.0" | +| `spiffe_id` | `id` | Primary identity. SPIFFE ID recommended | +| N/A | `identityType` | Required. "spiffe", "did", or custom | +| `name` | `name` | Agent/service name | +| `version` | Moved to `metadata.version` | Version now in metadata section | +| `description` | `description` | Description text | +| `icon_url` | `logoUrl` | Logo/icon URL | +| N/A | `maturity` | "experimental", "beta", "stable", "deprecated" | +| N/A | `signature` | Optional. Detached JWS signature | + +### Publisher Information + +| A2A AgentCard (v0.3.0) | AI Card (v1.0) | Notes | +|------------------------|----------------|-------| +| `provider.organization` | `publisher.name` | Organization name | +| `provider.url` | `publisher.url` | Organization URL | +| N/A | `publisher.id` | Publisher identity (SPIFFE/DID) | +| N/A | `publisher.identityType` | Identity type ("spiffe", etc.) | +| N/A | `publisher.attestation` | Optional identity proof | + +### Trust & Attestations + +**New in AI Card:** +- `trust.attestations[]` - Array of compliance/security attestations +- `trust.privacyPolicyUrl` - Privacy policy link +- `trust.termsOfServiceUrl` - Terms of service link + +**Example Attestations:** +```json +{ + "trust": { + "attestations": [ + { + "type": "HardModeCompliance", + "description": "R1-R8 rules enforced via CI", + "details": {...} + }, + { + "type": "SOC2-Type2", + "credentialUrl": "https://..." + } + ] + } +} +``` + +### Services (Protocol-Specific) + +**A2A Protocol moves into `services.a2a.protocolSpecific`:** + +| A2A AgentCard (v0.3.0) | AI Card (v1.0) | Notes | +|------------------------|----------------|-------| +| `protocol_version` | `services.a2a.protocolSpecific.protocolVersion` | A2A protocol version | +| `url` | `services.a2a.protocolSpecific.supportedInterfaces[0].url` | Endpoint URL | +| `preferred_transport` | `services.a2a.protocolSpecific.supportedInterfaces[0].transport` | JSONRPC, HTTP, etc. | +| `skills[]` | `services.a2a.protocolSpecific.skills[]` | Skills array | +| `security_schemes` | `services.a2a.protocolSpecific.securitySchemes` | OAuth2, API keys, etc. | +| `capabilities` | Moved to skill tags | General capabilities now in skill tags | + +### Skills Schema + +Skills remain mostly unchanged but are now nested in `services.a2a.protocolSpecific.skills[]`: + +```json +{ + "id": "bob.answer_adk_question", + "name": "Answer ADK Question", + "description": "...", + "inputModes": ["application/json"], + "outputModes": ["application/json", "text/plain"], + "inputSchema": {...}, + "outputSchema": {...}, + "tags": ["adk", "documentation"] +} +``` + +### Metadata + +**New `metadata` section** for deployment/operational info: + +```json +{ + "metadata": { + "region": "us-central1", + "environment": "production", + "version": "0.12.0", + "runtime": "Vertex AI Agent Engine", + "custom_field": "custom_value" + } +} +``` + +--- + +## Step-by-Step Conversion + +### Step 1: Create AI Card Shell + +```json +{ + "$schema": "https://a2a-protocol.org/ai-card/v1/schema.json", + "specVersion": "1.0", + "id": "", + "identityType": "spiffe", + "name": "", + "description": "", + "logoUrl": , + "maturity": "stable" +} +``` + +### Step 2: Add Publisher Information + +```json +{ + "publisher": { + "id": "spiffe:///org/", + "identityType": "spiffe", + "name": "", + "url": "" + } +} +``` + +### Step 3: Add Trust Attestations (Optional but Recommended) + +```json +{ + "trust": { + "attestations": [ + { + "type": "CustomAttestation", + "description": "Describe your compliance/security posture" + } + ] + } +} +``` + +### Step 4: Move A2A Protocol to Services + +```json +{ + "services": { + "a2a": { + "type": "a2a", + "name": " A2A Interface", + "description": "...", + "protocolSpecific": { + "protocolVersion": "", + "supportedInterfaces": [ + { + "transport": "", + "url": "" + } + ], + "securitySchemes": , + "skills": + } + } + } +} +``` + +### Step 5: Add Timestamps and Metadata + +```json +{ + "createdAt": "2025-01-15T10:00:00Z", + "updatedAt": "2025-12-02T18:00:00Z", + "metadata": { + "version": "", + "region": "us-central1", + "environment": "production", + "custom_fields": "..." + } +} +``` + +--- + +## SPIFFE Identity Migration + +### Current A2A Format +```json +{ + "spiffe_id": "spiffe://intent.solutions/agent/bobs-brain/dev/us-central1/0.11.0" +} +``` + +### New AI Card Format +```json +{ + "id": "spiffe://intent.solutions/agent/bobs-brain/prod/us-central1/0.12.0", + "identityType": "spiffe" +} +``` + +**SPIFFE Best Practices:** +- Use trust domain you control (e.g., `spiffe://yourcompany.com`) +- Follow path pattern: `/agent////` +- Update version in path when agent version changes +- Document SPIFFE setup in deployment docs + +--- + +## Multi-Protocol Support + +One AI Card can support multiple protocols: + +```json +{ + "services": { + "a2a": { + "type": "a2a", + "protocolSpecific": {...} + }, + "mcp": { + "type": "mcp", + "protocolSpecific": { + "protocolVersion": "2025-06-18", + "transport": {...}, + "capabilities": {...} + } + }, + "custom": { + "type": "custom-protocol", + "protocolSpecific": {...} + } + } +} +``` + +--- + +## Validation Checklist + +Before deploying your converted AI Card: + +- [ ] `$schema` points to official AI Card schema URL +- [ ] `specVersion` is "1.0" +- [ ] `id` is unique and follows your identity pattern (SPIFFE/DID) +- [ ] `identityType` matches your `id` format +- [ ] `publisher.id` exists if using organizational identity +- [ ] A2A protocol config is in `services.a2a.protocolSpecific` +- [ ] Skills have `inputModes` and `outputModes` (new requirement) +- [ ] `createdAt` and `updatedAt` timestamps are ISO 8601 format +- [ ] JSON validates against schema (use schema validator) + +--- + +## Backward Compatibility + +**During transition period:** + +1. **Serve both formats** at different endpoints: + ``` + /.well-known/agent-card.json # Original A2A format + /.well-known/ai-card.json # New AI Card format + ``` + +2. **Content negotiation** - Return format based on client request + +3. **Gradual migration** - Update consumers to use new AI Card format + +4. **Deprecation timeline** - Announce A2A-only format sunset date + +--- + +## Common Pitfalls + +### ❌ Don't Do This + +```json +{ + "id": "my-agent", // ❌ Not a valid SPIFFE/DID + "identityType": "spiffe", // ❌ Mismatch + "services": { + "a2a": { + "skills": [...] // ❌ Skills should be in protocolSpecific + } + } +} +``` + +### ✅ Do This + +```json +{ + "id": "spiffe://company.com/agent/my-agent", // ✅ Valid SPIFFE + "identityType": "spiffe", // ✅ Matches + "services": { + "a2a": { + "protocolSpecific": { // ✅ Correct nesting + "skills": [...] + } + } + } +} +``` + +--- + +## Testing Your Conversion + +```bash +# Validate JSON syntax +jq empty ai-card.json + +# Validate against schema (once schema is published) +ajv validate -s ai-card-schema.json -d ai-card.json + +# Compare fields with original +diff <(jq -S 'keys' agent-card-a2a.json) <(jq -S '.services.a2a.protocolSpecific | keys' ai-card.json) +``` + +--- + +## Resources + +- **AI Card Spec:** https://github.com/Agent-Card/ai-card +- **A2A Protocol:** https://github.com/google/a2a-protocol +- **SPIFFE:** https://spiffe.io/ +- **Bob's Brain Example:** This directory + +--- + +## Questions? + +- **Repository:** https://github.com/jeremylongshore/bobs-brain +- **Issues:** https://github.com/Agent-Card/ai-card/issues +- **Contact:** jeremy@intentsolutions.io + +--- + +**Last Updated:** 2025-12-02 +**Version:** 1.0 +**Status:** Production-ready conversion guide