a2afmsg

README

A2A Go FMSG Transport

a2afmsg is an FMSG transport plugin for the official A2A Go SDK. It implements FMSG-004 v0.2.0 over an FMSG-003 Web API.

The binding is currently experimental. Its protocol identifier must match the protocolBinding value in the remote Agent Card exactly:

https://github.com/markmnl/fmsg/blob/main/standards/fmsg-004-a2a-binding.md

Install

go get github.com/markmnl/a2a-go-fmsg@v0.1.0

The module requires Go 1.25 or newer and A2A Go SDK v2.

Use

package main

import (
    "context"
    "os"

    "github.com/a2aproject/a2a-go/v2/a2a"
    "github.com/a2aproject/a2a-go/v2/a2aclient"
    "github.com/a2aproject/a2a-go/v2/a2aclient/agentcard"
    a2afmsg "github.com/markmnl/a2a-go-fmsg"
)

func main() {
    ctx := context.Background()
    card, err := agentcard.DefaultResolver.Resolve(ctx, "https://fmsg.io")
    if err != nil {
        panic(err)
    }

    client, err := a2aclient.NewFromCard(ctx, card,
        a2afmsg.WithTransport(a2afmsg.Config{
            WebAPIURL: os.Getenv("FMSG_API_URL"),
            APIKey:    os.Getenv("FMSG_API_KEY"),
        }),
    )
    if err != nil {
        panic(err)
    }
    defer client.Destroy()

    _, err = client.SendMessage(ctx, &a2a.SendMessageRequest{
        Message: a2a.NewMessage(a2a.MessageRoleUser, a2a.NewTextPart("Hello Groot")),
    })
    if err != nil {
        panic(err)
    }
}

WebAPIURL and APIKey belong to the calling FMSG address, not the remote agent. The transport authenticates through POST /fmsg/token and uses the token subject as the caller's verified FMSG address.

The plugin supports every A2A 1.0 client transport operation, native FMSG mapping for Part.raw, request/result correlation, task and context thread topology, detached recovery after FMSG response code 6, streaming event ordering, bounded resource limits, and distinct A2A and FMSG delivery errors.

End-to-end CLI

go install github.com/markmnl/a2a-go-fmsg/cmd/a2a-fmsg@v0.1.0
export FMSG_API_URL=https://api.example.com
export FMSG_API_KEY=fmsgk_callers_key
a2a-fmsg -card https://fmsg.io "Hello Groot"

Using a caller on a different FMSG domain also exercises federated delivery.

Credentials and retention

FMSG messages are immutable and may be retained. Values supplied through Config.Credentials therefore become durable message content. Never send passwords, refresh tokens, or long-lived API keys; use narrowly scoped, short-lived credentials where application-level authentication is required.

Versioning

Module releases and binding revisions are versioned independently. Module v0.1.x implements FMSG-004 binding version 0.2 and A2A protocol version 1.0 using github.com/a2aproject/a2a-go/v2.

License

Apache License 2.0.

Documentation

Overview

Package a2afmsg implements the FMSG-004 v0.2.0 transport binding for the official A2A Go client.

Index

• Constants
• func ParseEndpoint(endpoint string) (string, error)
• func WithTransport(config Config) a2aclient.FactoryOption
• type BindingError
  • func (e *BindingError) Error() string
  • func (e *BindingError) Unwrap() error
• type Config
• type Credential
• type DeliveryError
  • func (e *DeliveryError) Error() string
• type Transport
  • func NewTransport(ctx context.Context, endpoint string, config Config) (*Transport, error)
  • func (t *Transport) CancelTask(ctx context.Context, params a2aclient.ServiceParams, ...) (*a2a.Task, error)
  • func (t *Transport) CreateTaskPushConfig(ctx context.Context, params a2aclient.ServiceParams, request *a2a.PushConfig) (*a2a.PushConfig, error)
  • func (t *Transport) DeleteTaskPushConfig(ctx context.Context, params a2aclient.ServiceParams, ...) error
  • func (t *Transport) Destroy() error
  • func (t *Transport) GetExtendedAgentCard(ctx context.Context, params a2aclient.ServiceParams, ...) (*a2a.AgentCard, error)
  • func (t *Transport) GetTask(ctx context.Context, params a2aclient.ServiceParams, ...) (*a2a.Task, error)
  • func (t *Transport) GetTaskPushConfig(ctx context.Context, params a2aclient.ServiceParams, ...) (*a2a.PushConfig, error)
  • func (t *Transport) ListTaskPushConfigs(ctx context.Context, params a2aclient.ServiceParams, ...) ([]*a2a.PushConfig, error)
  • func (t *Transport) ListTasks(ctx context.Context, params a2aclient.ServiceParams, ...) (*a2a.ListTasksResponse, error)
  • func (t *Transport) SendMessage(ctx context.Context, params a2aclient.ServiceParams, ...) (a2a.SendMessageResult, error)
  • func (t *Transport) SendStreamingMessage(ctx context.Context, params a2aclient.ServiceParams, ...) iter.Seq2[a2a.Event, error]
  • func (t *Transport) SubscribeToTask(ctx context.Context, params a2aclient.ServiceParams, ...) iter.Seq2[a2a.Event, error]

Constants

const (
	// ProtocolBinding is the provisional FMSG-004 binding identifier.
	ProtocolBinding a2a.TransportProtocol = "https://github.com/markmnl/fmsg/blob/main/standards/fmsg-004-a2a-binding.md"
	// MediaType identifies FMSG-004 envelope data.
	MediaType = "application/vnd.fmsg.a2a+json"
)

Functions

func ParseEndpoint

func ParseEndpoint(endpoint string) (string, error)

ParseEndpoint validates an FMSG-004 interface URL and returns its address.

func WithTransport

func WithTransport(config Config) a2aclient.FactoryOption

WithTransport registers FMSG-004 with the official A2A client factory.

Types

type BindingError

type BindingError struct {
	Code    string
	Message string
	Details []any
	// contains filtered or unexported fields
}

BindingError is an A2A or FMSG-004 error returned by the remote agent.

func (*BindingError) Error

func (e *BindingError) Error() string

func (*BindingError) Unwrap

func (e *BindingError) Unwrap() error

type Config

type Config struct {
	WebAPIURL string
	APIKey    string

	HTTPClient         *http.Client
	PollInterval       time.Duration
	RequestTimeout     time.Duration
	MaxJSONBytes       int64
	MaxAttachmentBytes int64
	MaxBufferedEvents  int

	Credentials map[string]Credential
}

Config configures an FMSG A2A client transport.

type Credential

type Credential struct {
	Value  string   `json:"value"`
	Scopes []string `json:"scopes,omitempty"`
}

Credential is an optional short-lived application credential carried in an FMSG-004 request envelope. Long-lived secrets should not be sent because fmsg messages are immutable and may be retained.

type DeliveryError

type DeliveryError struct {
	Code      int
	Address   string
	Retryable bool
}

DeliveryError is an fmsg transport rejection, distinct from an A2A error.

func (*DeliveryError) Error

func (e *DeliveryError) Error() string

type Transport

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

Transport implements a2aclient.Transport over FMSG-004 and fmsg-webapi.

func NewTransport

func NewTransport(ctx context.Context, endpoint string, config Config) (*Transport, error)

NewTransport connects an FMSG-004 transport to one fmsg AgentInterface URL.

func (*Transport) CancelTask

func (t *Transport) CancelTask(ctx context.Context, params a2aclient.ServiceParams, request *a2a.CancelTaskRequest) (*a2a.Task, error)

CancelTask implements a2aclient.Transport.

func (*Transport) CreateTaskPushConfig

func (t *Transport) CreateTaskPushConfig(ctx context.Context, params a2aclient.ServiceParams, request *a2a.PushConfig) (*a2a.PushConfig, error)

CreateTaskPushConfig implements a2aclient.Transport.

func (*Transport) DeleteTaskPushConfig

func (t *Transport) DeleteTaskPushConfig(ctx context.Context, params a2aclient.ServiceParams, request *a2a.DeleteTaskPushConfigRequest) error

DeleteTaskPushConfig implements a2aclient.Transport.

func (*Transport) Destroy

func (t *Transport) Destroy() error

Destroy prevents new calls. In-flight calls continue until their contexts end.

func (*Transport) GetExtendedAgentCard

func (t *Transport) GetExtendedAgentCard(ctx context.Context, params a2aclient.ServiceParams, request *a2a.GetExtendedAgentCardRequest) (*a2a.AgentCard, error)

GetExtendedAgentCard implements a2aclient.Transport.

func (*Transport) GetTask

func (t *Transport) GetTask(ctx context.Context, params a2aclient.ServiceParams, request *a2a.GetTaskRequest) (*a2a.Task, error)

GetTask implements a2aclient.Transport.

func (*Transport) GetTaskPushConfig

func (t *Transport) GetTaskPushConfig(ctx context.Context, params a2aclient.ServiceParams, request *a2a.GetTaskPushConfigRequest) (*a2a.PushConfig, error)

GetTaskPushConfig implements a2aclient.Transport.

func (*Transport) ListTaskPushConfigs

func (t *Transport) ListTaskPushConfigs(ctx context.Context, params a2aclient.ServiceParams, request *a2a.ListTaskPushConfigRequest) ([]*a2a.PushConfig, error)

ListTaskPushConfigs implements a2aclient.Transport.

func (*Transport) ListTasks

func (t *Transport) ListTasks(ctx context.Context, params a2aclient.ServiceParams, request *a2a.ListTasksRequest) (*a2a.ListTasksResponse, error)

ListTasks implements a2aclient.Transport.

func (*Transport) SendMessage

func (t *Transport) SendMessage(ctx context.Context, params a2aclient.ServiceParams, request *a2a.SendMessageRequest) (a2a.SendMessageResult, error)

SendMessage implements a2aclient.Transport.

func (*Transport) SendStreamingMessage

func (t *Transport) SendStreamingMessage(ctx context.Context, params a2aclient.ServiceParams, request *a2a.SendMessageRequest) iter.Seq2[a2a.Event, error]

SendStreamingMessage implements a2aclient.Transport.

func (*Transport) SubscribeToTask

func (t *Transport) SubscribeToTask(ctx context.Context, params a2aclient.ServiceParams, request *a2a.SubscribeToTaskRequest) iter.Seq2[a2a.Event, error]

SubscribeToTask implements a2aclient.Transport.