A2A-T Workflow Execution Engine (Java)

A Java SDK embedded in a host agent for executing multi-agent workflows over the A2A protocol with A2A-T telecom extensions.

The engine handles workflow scheduling, A2A envelopes, transport, task waiting, authentication and TLS. Host callbacks return final message content and own any A2A-T generation, schema, validation or LLM calls.

• A2A-T Extension Support: Task-T (structured task prompts), Negotiation-T (host-activated auto negotiation loop), Authorization-T (independent authorization operation), Notification-T (independent long-lived SSE subscription)
• Content-neutral callbacks: final MessageContent, complete ReceivedMessage, local multi-output TaskResult and explicit NegotiationReply.Send/Stop
• Minimal A2A-T dependency: a2a-t-core only in the engine; content generation and template queries use the host's explicit a2a-t-client dependency
• DAG Workflow Execution: Parallel dispatch, self-loop steps, conditional routing
• Multi-Protocol Transport: REST, JSON-RPC, and gRPC auto-selected from AgentCard
• Authentication: Bearer token login with TTL cache, AES-256-GCM encrypted credentials, custom AuthProvider
• HTTPS/TLS: Configurable trust store, self-signed cert support for development
• Protocol Logging: actual HTTP/JSON-RPC boundaries and gRPC metadata/protobuf views; bodies default on at DEBUG with mandatory secret-field redaction

Protocol documents are integration inputs, not executable truth. The pinned A2A-T SDK templates, slot schemas, canonical URIs, and validation results are authoritative. Protocol generation and validation fail closed; raw text is never sent under an A2A-T URI as a fallback.

The SDK is embedded in a host agent. It schedules workflow tasks to dispatched agents and returns complete results to the host callbacks. Task-T, Authorization-T, and Notification-T use independent transport/runtime/context instances. Authorization and Notification are independently triggered host-agent operations rather than DAG nodes; a notification subscription remains open until the host-defined terminal event, explicit cancellation, or shutdown.

The current engine release is 0.1.0 on Maven Central.

A2A-T SDK 1.1.1 is published to Maven Central. Maven resolves it automatically; no SDK source checkout or local SDK build is required. The engine depends only on a2a-t-core; host agents using content generation explicitly add a2a-t-client:1.1.1. A dispatched-agent service that validates received extension content adds a2a-t-server:1.1.1. See the bilingual Developer Guide / 开发者指南 for dependency and upgrade guidance.

<dependency>
    <groupId>net.openan.workflow.sdk</groupId>
    <artifactId>workflow-engine</artifactId>
    <version>0.1.0</version>
</dependency>

For Spring Boot server-side integration:

<dependency>
    <groupId>net.openan.workflow.sdk</groupId>
    <artifactId>spring-boot-starter</artifactId>
    <version>0.1.0</version>
</dependency>

The sample demos read samples/src/main/resources/spn_agent_credentials.json, which is git-ignored. Copy spn_agent_credentials.example.json to that name to run against the bundled demo OMC — the checked-in defaults pair with the demo's embedded OMC server. When targeting a real OMC, replace the endpoint and user name, and encrypt the password with CredentialCrypto (set A2AT_CRED_KEY, then use the enc:-prefixed output). Tests use the tracked test resource and need no setup.

The complete, compiled example is HostQuickStart.java. It converts registry JSON maps to typed AgentCards, runs a remote task and local aggregation, cancels timed-out work, and closes caller-owned transport resources. Run its main method in IDEA with three arguments: registry URL, target AgentCard name, and credentials JSON path. The registry and target agent must be reachable; TLS verification is enabled.

// In the samples module; HostQuickStart is example source, not a class shipped in the SDK jar.
HostQuickStart.main(new String[] {
    "https://registry.example.com",
    "Your Agent Name",
    "/secure/credentials.json"
});

This minimal example sends plain A2A content. For Task-T, Negotiation-T, Authorization-T and Notification-T content generation/validation in host-agent business callbacks, follow the business callback guide.

Final content callbacks, complete dependency inputs and negotiation Send/Stop: English / 中文.

graph TD
    L2["Layer 2 — Orchestration<br/>ExecutePsop<br/>lifecycle, event stream, onFinish hook"]
    L1["Layer 1 — Traversal<br/>WorkflowExecutor<br/>DAG walk, parallel dispatch, context assembly, routing"]
    L0["Layer 0 — Transport<br/>WorkflowEngineClient / A2ATransport<br/>A2A send, auth, extensions, SSL, SSE"]
    F["Foundation — Decision<br/>ControlPoint<br/>user-implemented business decisions"]

    L2 --> L1 --> L0
    L0 -.-> F

graph TD
    root["dev.openan.workflow.engine"]
    client["client<br/>A2A transport, auth, extensions"]
    control["control<br/>User decision interfaces"]
    core["core<br/>DAG traversal, context assembly"]
    model["model<br/>Data models"]
    registry["registry<br/>LoadPsop, RegistryClient"]
    runner["runner<br/>ExecutePsop entry point"]

    root --> client
    root --> control
    root --> core
    root --> model
    root --> registry
    root --> runner

Note: LlmHelper lives in the samples module (dev.openan.workflow.engine.examples), not in the client package. The workflow engine itself does not call an LLM directly.

• Integration Guide - Setup, configuration, secondary development
• API Reference - Public interface and class documentation
• Business Callback Contract - Host-agent callback inputs, outputs, and ownership
• Design Document - Architecture, module structure, design decisions
• Developer Guide - Internal architecture, contribution, debugging

• 集成指南 - 安装、配置、二次开发
• API 参考 - 公共接口和类文档
• 业务回调集成契约 - 宿主智能体回调的输入、输出与职责边界
• 架构设计 - 架构、模块结构、设计决策
• 开发者指南 - 内部架构、贡献、调试

Apache License 2.0

Run mvn -B clean verify before release. The reactor verifies the engine, Spring Boot starter, callback examples, protocol transport, negotiation, independent extension lifecycles, cancellation, error propagation, and credential redaction. These automated tests use controlled fixtures; production endpoints, identity services, and live model providers require a separate acceptance record.