Core Concepts

Understanding JACS requires familiarity with several key concepts that work together to create a secure, verifiable communication framework for AI agents.

Agents

An Agent is the fundamental entity in JACS - an autonomous participant that can create, sign, and verify documents.

Agent Identity

{
  "jacsId": "550e8400-e29b-41d4-a716-446655440000",
  "jacsVersion": "123e4567-e89b-12d3-a456-426614174000",
  "jacsType": "agent",
  "name": "Content Creation Agent",
  "description": "Specialized in creating marketing content"
}

Key Properties:

• jacsId: Permanent UUID identifying the agent
• jacsVersion: UUID that changes with each update
• Cryptographic Keys: Ed25519, RSA, or post-quantum key pairs
• Services: Capabilities the agent offers
• Contacts: How to reach the agent

Agent Lifecycle

1. Creation: Generate keys and initial agent document
2. Registration: Store public keys for verification
3. Operation: Create and sign documents
4. Updates: Version changes while maintaining identity
5. Verification: Other agents validate signatures

Verification: load() vs verify_standalone()

When consuming signed documents, you can verify in two ways:

• With a loaded agent (load(config) first): Call verify(signedDocument). The loaded agent uses its config (trust store, key resolution) to resolve the signer’s public key and verify the signature. Use this when your process already has a JACS config (e.g. it also signs) or when you want to use a specific key directory and resolution order.

• Without loading an agent (one-off verification): Call verify_standalone(signedDocument, options) (or the language equivalent: verifyStandalone, VerifyStandalone). This verifies the document using only the options you pass (e.g. keyResolution, keyDirectory). No config file or persistent agent state is required. Use this in lightweight services that only need to verify incoming documents.

Documents

A Document is any JSON object that follows JACS conventions for identity, versioning, and cryptographic integrity.

Document Structure

{
  "jacsId": "doc-uuid-here",
  "jacsVersion": "version-uuid-here",
  "jacsType": "task",
  "jacsVersionDate": "2024-01-15T10:30:00Z",
  "jacsPreviousVersion": "previous-version-uuid",
  
  "title": "Analyze Q4 Sales Data",
  "description": "Generate insights from sales data",
  
  "jacsSha256": "hash-of-document-content",
  "jacsSignature": {
    "agentID": "agent-uuid",
    "agentVersion": "agent-version-uuid",
    "signature": "base64-signature",
    "signingAlgorithm": "ring-Ed25519",
    "publicKeyHash": "hash-of-public-key",
    "date": "2024-01-15T10:30:00Z",
    "fields": ["jacsId", "title", "description"]
  }
}

Required JACS Fields

Document Types

Agent Documents

• Define agent identity and capabilities
• Contain service definitions and contact information
• Self-signed by the agent

Task Documents

• Describe work to be performed
• Include success/failure criteria
• Can be delegated between agents

Message Documents

• General communication between agents
• Can include attachments and metadata
• Support threaded conversations

Agreement Documents

• Multi-party consent mechanisms
• Track required and actual signatures
• Enforce completion before proceeding

Tasks

Tasks represent work that can be delegated, tracked, and verified between agents.

Task Structure

{
  "jacsType": "task",
  "title": "Generate Marketing Copy",
  "description": "Create compelling copy for product launch",
  
  "actions": [
    {
      "id": "research",
      "name": "Research competitors",
      "description": "Analyze competitor messaging",
      "success": "Complete competitive analysis report",
      "failure": "Unable to access competitor data"
    }
  ],
  
  "jacsTaskCustomer": {
    "agentID": "customer-agent-uuid",
    "signature": "customer-signature"
  }
}

Task Lifecycle

1. Creation: Customer agent creates task with requirements
2. Delegation: Task sent to service provider agent
3. Agreement: Provider signs agreement to accept task
4. Execution: Provider performs the work
5. Completion: Provider creates completion document
6. Verification: Customer verifies and accepts results

Task Components

Actions: Individual steps within a task

• id: Unique identifier within the task
• name: Human-readable action name
• description: Detailed requirements
• success: Definition of successful completion
• failure: What constitutes failure

Services: Required capabilities

• type: Service category
• requirements: Specific needs
• constraints: Limitations or restrictions

Agreements

Agreements enable multi-party consent and coordination between agents.

Agreement Structure

{
  "jacsType": "agreement",
  "title": "Task Acceptance Agreement",
  "question": "Do you agree to complete the marketing copy task?",
  "context": "Task ID: abc123, Deadline: 2024-01-20",
  
  "agents": [
    "agent-1-uuid",
    "agent-2-uuid",
    "agent-3-uuid"
  ],
  
  "jacsAgreement": {
    "agent-1-uuid": {
      "agentID": "agent-1-uuid",
      "signature": "base64-signature",
      "date": "2024-01-15T10:30:00Z"
    },
    "agent-2-uuid": {
      "agentID": "agent-2-uuid", 
      "signature": "base64-signature",
      "date": "2024-01-15T11:15:00Z"
    }
    // agent-3-uuid has not signed yet
  },
  
  "jacsAgreementHash": "hash-of-agreement-content"
}

Agreement Process

1. Creation: Initial agent creates agreement with required participants
2. Distribution: Agreement sent to all required agents
3. Review: Each agent reviews terms and conditions
4. Signing: Agents add their signatures if they consent
5. Completion: Agreement becomes binding when all parties have signed
6. Verification: Any party can verify all signatures

Agreement Types

Task Agreements: Consent to perform specific work Service Agreements: Long-term service provision contracts
Data Sharing Agreements: Permission to access or use data Update Agreements: Consent to system or process changes

Cryptographic Security

JACS uses industry-standard cryptographic primitives for security.

Supported Algorithms

Current Standards

• ring-Ed25519: Fast elliptic curve signatures using the ring library (recommended)
• RSA-PSS: Traditional RSA with probabilistic signature scheme

Post-Quantum

• pq-dilithium: NIST-standardized post-quantum signatures

Signature Process

1. Content Extraction: Specific fields are extracted for signing
2. Canonicalization: Fields are sorted and formatted consistently
3. Hashing: SHA-256 hash of the canonical content
4. Signing: Private key signs the hash
5. Verification: Public key verifies the signature

Key Management

• Agent Keys: Each agent has a unique key pair
• Public Key Distribution: Public keys shared through secure channels
• Key Rotation: Agents can update keys while maintaining identity
• Key Verification: Public key hashes ensure integrity

Versioning and Audit Trails

JACS provides comprehensive versioning for tracking document evolution.

Version Management

• Immutable IDs: jacsId never changes for a document
• Version IDs: jacsVersion changes with each update
• Previous Versions: jacsPreviousVersion creates a chain
• Timestamps: jacsVersionDate provides chronological order

Audit Trail Benefits

• Complete History: Track all changes to any document
• Attribution: Know exactly who made each change
• Verification: Cryptographic proof of authenticity
• Compliance: Meet regulatory audit requirements

Storage and Transport

JACS documents are designed to be storage and transport agnostic.

Storage Options

• File System: Simple JSON files
• Databases: Store as JSON/JSONB fields
• Object Storage: S3, Azure Blob, Google Cloud Storage
• Version Control: Git repositories for change tracking

Transport Mechanisms

• HTTP APIs: RESTful or GraphQL endpoints
• Message Queues: RabbitMQ, Kafka, SQS
• Email: Documents as attachments
• Direct Transfer: USB drives, file sharing

Format Compatibility

• JSON: Universal compatibility across all systems
• Schema Validation: Ensures consistent structure
• Self-Contained: All necessary information in the document
• Human Readable: Can be inspected and debugged easily

Next Steps

Now that you understand the core concepts:

1. Quick Start - Try JACS hands-on
2. Choose Implementation:
   • Rust CLI for command-line usage
   • Node.js for web applications
   • Python for AI/ML workflows
3. Examples - See real-world usage patterns