a2aclient

package
v1.0.0-rc.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 8, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

Package a2aclient implements the bounded outbound A2A wire protocol.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func EncodeRequest 

func EncodeRequest(version string, op Operation, r Request) ([]byte, error)

EncodeRequest encodes only the supported fields, bounding aggregate input.

func ParseCard 

func ParseCard(body []byte, dialect string) (*Card, Interface, error)

ParseCard selects version evidence without allowing a dialect override to invent it. Every advertised endpoint is validated, including unselected bindings.

func ParseURL 

func ParseURL(raw string) (*url.URL, error)

ParseURL validates an operator or advertised A2A destination without echoing it.

Types

type Artifact 

type Artifact struct {
	Name, Description string
	Parts             []Part
}

Artifact preserves an artifact's application fields without its protocol ID.

type Card 

type Card struct {
	SupportedInterfaces  []Interface `json:"supportedInterfaces"`
	ProtocolVersion      string      `json:"protocolVersion"`
	URL                  string      `json:"url"`
	PreferredTransport   string      `json:"preferredTransport"`
	AdditionalInterfaces []Interface `json:"additionalInterfaces"`
	Capabilities         struct {
		Extensions []struct {
			Required bool `json:"required"`
		} `json:"extensions"`
	} `json:"capabilities"`
	DefaultInputModes    []string        `json:"defaultInputModes"`
	DefaultOutputModes   []string        `json:"defaultOutputModes"`
	Security             json.RawMessage `json:"security"`
	SecurityRequirements json.RawMessage `json:"securityRequirements"`
	SecuritySchemes      json.RawMessage `json:"securitySchemes"`
	Skills               []Skill         `json:"skills"`
}

Card retains the discovery fields needed by the bounded adapter subset. Text and raw compatibility declarations are untrusted, not diagnostic values.

type CardCache 

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

CardCache is private to one registration and credential/session identity. Approved trust must be stored separately; a cache hit is not approval.

func NewCardCache 

func NewCardCache(client *Client, dialect string) *CardCache

NewCardCache binds freshness to an immutable client and configured dialect.

func (*CardCache) Fetch 

func (c *CardCache) Fetch(ctx context.Context, force bool) ([]byte, error)

Fetch returns validated card bytes. Force bypasses successful cache reuse for approval, but still honors bounded failure backoff. Each caller owns its bytes. Admission/capability checks must precede this call.

type CardResponse 

type CardResponse struct {
	Body   []byte
	Header http.Header
}

CardResponse is bounded discovery evidence. Callers must keep it out of diagnostics.

type Client 

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

Client owns a single bounded HTTP transport and a private discovery session. It performs no automatic RPC retries and has no ambient cookie credentials.

func New 

func New(opts Options) (*Client, error)

New constructs the transport. HTTP fixtures always dial verified loopback IPs.

func (*Client) Close 

func (c *Client) Close()

Close releases idle transport connections. In-flight calls are canceled by their owning adapter generation before transport cleanup.

func (*Client) FetchCard 

func (c *Client) FetchCard(ctx context.Context) (CardResponse, error)

FetchCard performs a full GET, following at most three same-origin redirects.

func (*Client) RPC 

func (c *Client) RPC(ctx context.Context, endpoint, version, session string, body []byte) ([]byte, int, error)

RPC sends one request to an authorized endpoint and returns bounded wire bytes. Both success and error bodies are returned for dialect-aware JSON-RPC decoding.

func (*Client) ResolveEndpoint 

func (c *Client) ResolveEndpoint(advertised string) (string, error)

ResolveEndpoint authorizes an advertised URL, or the explicit operator override.

type Compatibility 

type Compatibility struct {
	AcceptsData bool
	OutputModes []string
}

Compatibility is the supported media intersection for one message operation.

func CheckCompatibility 

func CheckCompatibility(card *Card, skill *Skill, version string, bearer, bedrock bool) (Compatibility, error)

CheckCompatibility evaluates agent defaults or a skill's explicit overrides. Security alternatives are OR; schemes within an alternative are AND. URLs in security declarations are descriptive only and are never fetched here.

type Error 

type Error struct {
	Category  string
	Status    int
	Code      int
	Retryable bool
	// contains filtered or unexported fields
}

Error contains only locally authored diagnostics, never downstream text.

func (*Error) Error 

func (e *Error) Error() string

func (*Error) Unwrap 

func (e *Error) Unwrap() error

Unwrap preserves cancellation identity without retaining transport errors.

type Interface 

type Interface struct {
	URL             string `json:"url"`
	ProtocolBinding string `json:"protocolBinding"`
	ProtocolVersion string `json:"protocolVersion"`
	Tenant          string `json:"tenant"`
	Transport       string `json:"transport"`
}

Interface describes an advertised protocol binding. It is not authorization.

type Message 

type Message struct {
	TaskID, ContextID string
	Role              string
	Parts             []Part
}

Message preserves boundaries and validated protocol references for admission.

type Operation 

type Operation uint8

Operation is the bounded, non-streaming subset of A2A JSON-RPC. 

const (
	Send Operation = iota + 1
	Get
	Cancel
)

type Options 

type Options struct {
	Card     string
	Endpoint string
	Token    string
	Bedrock  bool
	Timeout  time.Duration
}

Options identifies operator-authorized destinations and discovery credentials.

type Part 

type Part struct {
	Type string         `json:"type"`
	Text string         `json:"text,omitempty"`
	Data map[string]any `json:"data,omitempty"`
}

Part holds accepted application content. Numbers in Data retain JSON precision.

func (Part) MarshalJSON 

func (p Part) MarshalJSON() ([]byte, error)

MarshalJSON preserves empty text and empty data objects as application content.

type Request 

type Request struct {
	ID, MessageID, TaskID, ContextID string
	Text                             string
	Data                             map[string]any
	SkillID                          string
	OutputModes                      []string
	ReturnImmediately                bool
	HistoryLength                    int
}

Request contains protocol IDs supplied by trusted routing, never capabilities.

type Result 

type Result struct {
	Kind, TaskID, ContextID, State string
	Parts                          []Part
	StatusMessages, History        []Message
	Artifacts                      []Artifact
}

Result is decoded evidence, not authority. Routing must validate its top-level IDs against the admitted operation before issuing or updating capabilities.

func DecodeResponse 

func DecodeResponse(version string, op Operation, id string, status int, body []byte) (Result, error)

DecodeResponse validates correlation, variants, and nested protocol references. JSON-RPC errors are decoded on every HTTP status without retaining remote text.

type Skill 

type Skill struct {
	ID                   string          `json:"id"`
	Description          string          `json:"description"`
	InputModes           []string        `json:"inputModes"`
	OutputModes          []string        `json:"outputModes"`
	Security             json.RawMessage `json:"security"`
	SecurityRequirements json.RawMessage `json:"securityRequirements"`
}

Skill preserves authored descriptions and mode/security overrides.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.