Skip to content

Protocol Overview

The AI Partner Up Flow Protocol defines the standard for interaction between different components of the system, enabling interoperability across multiple language implementations.

Protocol Goals

  • Language Agnostic: The protocol is designed to be implemented in any programming language (Python, Go, Rust, JavaScript, etc.).
  • Interoperability: Ensures seamless communication between nodes running different implementations.
  • Extensibility: Allows for future enhancements without breaking existing implementations.
  • Completeness: Provides all specifications needed to implement a compatible library without reference to specific implementations.

Protocol Version

Current Version: 1.0

Version Format: MAJOR.MINOR.PATCH - MAJOR: Breaking changes to the protocol - MINOR: New features that are backward compatible - PATCH: Bug fixes and clarifications

MUST: Implementations MUST specify the protocol version they support.

SHOULD: Implementations SHOULD be backward compatible with previous minor versions when possible.

Key Concepts

  • Flow: A complete workflow or process, structured as a hierarchical tree of Tasks.
  • Task: The atomic unit of execution within a Flow.
  • Executor: The component responsible for performing the actual work defined by a Task.
  • Node: A participant in the network that implements the protocol.
  • TaskManager: The orchestrator that coordinates task execution, dependency resolution, and priority scheduling.

See Core Concepts for detailed definitions.

Protocol Standards

The protocol builds on and complies with established standards:

JSON-RPC 2.0

Standard: JSON-RPC 2.0 Specification

Usage: All RPC operations use JSON-RPC 2.0 format.

Compliance: - MUST: Implementations MUST support JSON-RPC 2.0 over HTTP. - MUST: Implementations MUST use standard JSON-RPC 2.0 error codes for protocol errors.

See Interface Protocol for complete API specification.

A2A Protocol

Standard: A2A Protocol

Usage: Enhanced agent-to-agent communication with streaming and push notifications.

Compliance: - SHOULD: Implementations SHOULD support A2A Protocol for enhanced features. - SHOULD: Implementations SHOULD support agent card discovery.

See Interface Protocol for A2A Protocol integration details.

JSON Schema

Standard: JSON Schema Draft 7

Usage: Task schema definitions and input validation.

Compliance: - MUST: Implementations MUST validate tasks against JSON Schema definitions. - SHOULD: Implementations SHOULD use JSON Schema for input validation.

See Data Model for complete schema definitions.

UUID

Standard: RFC 4122 - UUID

Usage: Task identifiers (id, parent_id, dependency IDs).

Compliance: - MUST: Implementations MUST use UUID v4 format for all task identifiers. - MUST: Implementations MUST validate UUID format.

ISO 8601

Standard: ISO 8601 - Date and Time

Usage: Timestamp fields (created_at, started_at, updated_at, completed_at).

Compliance: - MUST: Implementations MUST use ISO 8601 format for timestamps. - SHOULD: Implementations SHOULD use UTC timezone.

Protocol Structure

The protocol specification is organized into the following documents:

  1. Overview (this document): Protocol introduction, versioning, and standards
  2. Core Concepts: Fundamental concepts and interfaces
  3. Data Model: Complete task schema and data structures
  4. Execution Lifecycle: State machine and execution rules
  5. Examples: Comprehensive examples and use cases
  6. Interface Protocol: API specifications (JSON-RPC 2.0, A2A Protocol)
  7. Conformance: Implementation requirements and compliance
  8. Error Handling: Error codes and handling procedures
  9. Validation: Validation rules and algorithms

Implementation Guide

Getting Started for Implementers

To implement a compatible library:

  1. Read the Specification: Start with Core Concepts and Data Model.
  2. Understand the State Machine: Study Execution Lifecycle for state transitions and execution rules.
  3. Review Examples: See Examples for practical usage patterns.
  4. Implement Core Components:
  5. Task data structures
  6. Executor interface
  7. TaskManager (orchestration)
  8. Storage interface
  9. API interface (JSON-RPC 2.0)
  10. Validate Implementation: Use Conformance checklist to verify compliance.
  11. Test: Create test cases based on Examples and Validation rules.

Core Implementation Requirements

MUST implement: - Complete Task schema - State machine (all states and valid transitions) - Dependency resolution - Priority scheduling - Executor interface - Storage interface - JSON-RPC 2.0 API

SHOULD implement: - A2A Protocol support - Streaming (SSE, WebSocket, or push notifications) - Input validation - Error handling

MAY implement: - Authentication - Retry mechanisms - Advanced features

See Conformance for complete requirements.

Testing Your Implementation

  1. Unit Tests: Test individual components (task validation, state transitions, dependency resolution).
  2. Integration Tests: Test complete workflows (task execution, dependency chains, error handling).
  3. Compliance Tests: Verify all MUST requirements are met.
  4. Interoperability Tests: Test with other implementations (if available).

Contributing Implementations

SHOULD: Implementations SHOULD be open source and publicly available.

SHOULD: Implementations SHOULD include: - Complete documentation - Test suite - Example code - Protocol version compatibility information

MAY: Implementations MAY seek protocol compliance certification.

Version History

Version 1.0 (Current)

Initial Release: Complete protocol specification including: - Task data model - State machine - Dependency resolution - Priority scheduling - Executor interface - Storage interface - JSON-RPC 2.0 API - A2A Protocol integration - Validation rules - Error handling

Breaking Changes: None (initial version).

Compatibility

Backward Compatibility

SHOULD: New minor versions SHOULD be backward compatible with previous minor versions.

MUST: Breaking changes MUST result in a new major version.

Forward Compatibility

MAY: Implementations MAY support features from future protocol versions if they are optional.

SHOULD: Implementations SHOULD gracefully handle unknown fields (ignore or preserve).

Protocol Independence

This protocol specification is independent of any specific implementation:

  • Language Agnostic: No language-specific code or examples (except for reference).
  • Implementation Agnostic: No assumptions about internal implementation details.
  • Complete: All information needed for implementation is in the protocol documents.

MUST: Implementations MUST not require knowledge of specific implementations (e.g., Python reference implementation) to be compliant.

SHOULD: Implementations SHOULD reference this protocol specification as the source of truth.

Reference Implementation

The Python implementation (aipartnerupflow) serves as a reference implementation:

  • Demonstrates protocol compliance
  • Provides examples and patterns
  • Validates protocol completeness

Note: The reference implementation is for reference only. Implementations in other languages MUST follow the protocol specification, not the reference implementation's internal details.

Protocol Extensions

The protocol supports extensions for custom functionality:

  1. Custom Executors: Implement custom executors for specific use cases
  2. System executors (system information, commands)
  3. Data processing executors (aggregation, transformation)
  4. External service executors (HTTP, APIs, databases)
  5. AI/LLM executors (LLM agents, AI models)

  6. Domain-specific executors (business logic, integrations)

  7. Storage Backends: Implement custom storage backends

  8. Database backends (SQL, NoSQL)
  9. File-based storage

  10. In-memory storage

  11. Transport Layers: Implement custom transport layers

  12. WebSocket
  13. Message queues
  14. Custom protocols

MUST: Extensions MUST not break protocol compliance.

SHOULD: Extensions SHOULD be documented and made available to the community.

Note: While implementations may provide various executor types (e.g., system_info_executor, command_executor, crew_manager), the protocol only specifies the interface and registration mechanism. Specific executor identifiers are implementation-specific.

Getting Help

See Also