a2atransport

README

nekiro-a2a-transport-go

Strict, bounded JSON-RPC/SSE client transport for the A2A protocol profile used by NeKiro.

The package builds on github.com/a2aproject/a2a-go v0.3.15; it does not replace or fork the A2A protocol implementation. It contributes explicit transport hardening and a reusable caller-owned policy boundary.

Scope

The module provides:

• message/send, message/stream, and tasks/cancel client operations;
• strict JSON-RPC response identity and envelope validation;
• strict single-data-line SSE framing with unique event IDs;
• explicit response/event byte bounds with no truncation;
• raw streaming result preservation alongside official decoded events;
• redirect rejection and typed transport failures;
• explicit request metadata through official call interceptors.

It does not provide discovery, endpoint selection, Agent Card resolution, credentials, authorization, retry, fallback, persistence, Ledger behavior, or an Agent Runtime.

Compatibility

• A2A protocol: 0.3.0
• Go A2A library: github.com/a2aproject/a2a-go v0.3.15
• Go: 1.26.0

Development checks

go test ./...
go test -race ./...
go vet ./...
go mod tidy
git diff --check

Fallback delta: removed 0, retained 1, added 0, net 0. The retained behavior is Go's documented nil http.Client.Transport policy. Added fallback evidence: none.

Documentation

Overview

Package a2atransport provides a strict, bounded JSON-RPC/SSE client transport for the A2A protocol profile used by NeKiro.

The package intentionally owns no Agent discovery, authorization, credential generation, invocation lineage, retry, persistence, or Agent Runtime behavior. Callers provide an exact endpoint, byte limits, and any request metadata interceptors for every operation.

Index

• Constants
• type CallOptions
• type Client
  • func NewClient(httpClient *http.Client) (*Client, error)
  • func (client *Client) CancelTask(ctx context.Context, options CallOptions, taskID a2a.TaskID) (*a2a.Task, error)
  • func (client *Client) SendMessage(ctx context.Context, options CallOptions, params *a2a.MessageSendParams) (a2a.SendMessageResult, error)
  • func (client *Client) SendStreamingMessage(ctx context.Context, options CallOptions, params *a2a.MessageSendParams) iter.Seq2[StreamItem, error]
• type Failure
  • func (failure *Failure) Error() string
  • func (failure *Failure) Kind() FailureKind
  • func (failure *Failure) Unwrap() error
• type FailureKind
  • func FailureKindOf(err error) (FailureKind, bool)
• type StreamItem

Examples

• Client

Constants

const (
	// ProtocolVersion is the A2A protocol version verified by this release.
	ProtocolVersion = "0.3.0"
	// A2AGoVersion is the official Go protocol-library version verified by this release.
	A2AGoVersion = "v0.3.15"
)

Types

type CallOptions

type CallOptions struct {
	Endpoint         string
	MaxResponseBytes int64
	MaxEventBytes    int64
	Interceptors     []a2aclient.CallInterceptor
}

CallOptions contains all transport policy required for one A2A operation. No endpoint, byte bound, or interceptor is inferred by the package.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client executes strict JSON-RPC A2A operations with caller-owned policy.

Example

client, err := a2atransport.NewClient(&http.Client{})
if err != nil {
	panic(err)
}
options := a2atransport.CallOptions{
	Endpoint:         "https://agent.example/a2a",
	MaxResponseBytes: 1 << 20,
	MaxEventBytes:    1 << 20,
}
_, _ = client.SendMessage(context.Background(), options, &a2a.MessageSendParams{})
for _, streamErr := range client.SendStreamingMessage(context.Background(), options, &a2a.MessageSendParams{}) {
	_ = streamErr
}

func NewClient

func NewClient(httpClient *http.Client) (*Client, error)

NewClient clones httpClient and installs a redirect-rejection policy. A nil *http.Client is invalid. A client whose Transport is nil retains Go's documented http.DefaultTransport behavior.

func (*Client) CancelTask

func (client *Client) CancelTask(ctx context.Context, options CallOptions, taskID a2a.TaskID) (*a2a.Task, error)

CancelTask executes one A2A tasks/cancel operation. Callers own any timeout and decide whether the operation should be attempted.

func (*Client) SendMessage

func (client *Client) SendMessage(ctx context.Context, options CallOptions, params *a2a.MessageSendParams) (a2a.SendMessageResult, error)

SendMessage executes A2A message/send.

func (*Client) SendStreamingMessage

func (client *Client) SendStreamingMessage(ctx context.Context, options CallOptions, params *a2a.MessageSendParams) iter.Seq2[StreamItem, error]

SendStreamingMessage executes A2A message/stream and returns the decoded A2A event together with the exact JSON-RPC result bytes that produced it.

type Failure

type Failure struct {
	// contains filtered or unexported fields
}

Failure carries a stable kind and an inspectable cause. Error deliberately omits cause text so callers do not leak remote endpoints or credentials by formatting the transport failure.

func (*Failure) Error

func (failure *Failure) Error() string

func (*Failure) Kind

func (failure *Failure) Kind() FailureKind

func (*Failure) Unwrap

func (failure *Failure) Unwrap() error

type FailureKind

type FailureKind string

FailureKind is a stable, transport-only error classification.

const (
	FailureInvalidArgument  FailureKind = "invalid_argument"
	FailureProtocol         FailureKind = "protocol"
	FailureRemoteAgent      FailureKind = "remote_agent"
	FailureUnavailable      FailureKind = "unavailable"
	FailureDeadlineExceeded FailureKind = "deadline_exceeded"
	FailureCanceled         FailureKind = "canceled"
	FailureResponseTooLarge FailureKind = "response_too_large"
)

func FailureKindOf

func FailureKindOf(err error) (FailureKind, bool)

FailureKindOf returns the first transport Failure classification in err's unwrap chain.

type StreamItem

type StreamItem struct {
	Event  a2a.Event
	Result json.RawMessage
}

StreamItem is one decoded A2A event and the immutable raw JSON-RPC result that produced it.