Documentation
¶
Overview ¶
Package a2ax drives A2A agents through the official Go A2A SDK and reports what each call returned in framework-owned types.
The conformant path of an A2A scenario is a cross-SDK interoperability check: a client built on the reference Go SDK talks, through the gateway, to an agent built on the reference Python SDK. Hand-built JSON-RPC envelopes and REST paths would make both sides of that check the test's own reading of the specification, so a field name misread the same way twice would pass. Requests a conformant client cannot produce, such as a missing protocol version or an unknown method, belong on the ordinary HTTP funnel instead.
Every Client is bound to exactly one endpoint and one protocol binding, with the SDK's transport defaults disabled, so a client asked for JSON-RPC cannot fall back to HTTP+JSON and turn a scenario claiming both bindings into one that exercised one binding twice. A Client is never built by following the URL inside a card unless the caller asks for that explicitly through InterfaceURL: a passthrough card advertises the upstream agent's own address, and a client that followed it would bypass the gateway entirely.
SDK results are converted into Outcome values rather than re-encoded as response bytes, so an assertion over them can never be mistaken for an assertion over what the gateway returned. A failed call is recorded in Outcome.Err rather than returned, because whether a call was meant to be refused is the caller's assertion to make.
Index ¶
- Constants
- func InterfaceURL(card []byte, binding string) (string, error)
- type Card
- type Client
- func (c *Client) Binding() string
- func (c *Client) CancelTask(ctx context.Context, headers Headers, taskID string) *Outcome
- func (c *Client) Close() error
- func (c *Client) CreatePushConfig(ctx context.Context, headers Headers, taskID, configID, url string) *Outcome
- func (c *Client) DeletePushConfig(ctx context.Context, headers Headers, taskID, configID string) *Outcome
- func (c *Client) GetExtendedCard(ctx context.Context, headers Headers) *Outcome
- func (c *Client) GetPushConfig(ctx context.Context, headers Headers, taskID, configID string) *Outcome
- func (c *Client) GetTask(ctx context.Context, headers Headers, taskID string) *Outcome
- func (c *Client) ListPushConfigs(ctx context.Context, headers Headers, taskID string) *Outcome
- func (c *Client) ListTasks(ctx context.Context, headers Headers) *Outcome
- func (c *Client) SendMessage(ctx context.Context, headers Headers, text string, returnImmediately bool) *Outcome
- func (c *Client) StreamMessage(ctx context.Context, headers Headers, text string) *Outcome
- func (c *Client) SubscribeToTask(ctx context.Context, headers Headers, taskID string, maxEvents int) *Outcome
- func (c *Client) URL() string
- type Event
- type Headers
- type Options
- type Outcome
- type PushConfig
- type Task
Constants ¶
const ( BindingJSONRPC = string(a2a.TransportProtocolJSONRPC) BindingHTTPJSON = string(a2a.TransportProtocolHTTPJSON) )
Protocol bindings a Client can be bound to, spelled as an Agent Card and an Agent resource spell them.
const ( DefaultCallTimeout = 30 * time.Second DefaultStreamTimeout = 60 * time.Second )
Default bounds for one SDK call. They are stuck-test backstops rather than assertions: a call that should succeed and does not is reported with the SDK's own error long before either fires.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is one SDK client bound to one endpoint and one protocol binding.
func (*Client) CancelTask ¶
CancelTask cancels one task.
func (*Client) Close ¶
Close releases the client's connections. It is safe to call on a nil or closed client.
func (*Client) CreatePushConfig ¶
func (c *Client) CreatePushConfig(ctx context.Context, headers Headers, taskID, configID, url string) *Outcome
CreatePushConfig registers a push notification config for a task.
func (*Client) DeletePushConfig ¶
func (c *Client) DeletePushConfig(ctx context.Context, headers Headers, taskID, configID string) *Outcome
DeletePushConfig removes one push notification config of a task.
func (*Client) GetExtendedCard ¶
GetExtendedCard fetches the authenticated extended Agent Card.
func (*Client) GetPushConfig ¶
func (c *Client) GetPushConfig(ctx context.Context, headers Headers, taskID, configID string) *Outcome
GetPushConfig fetches one push notification config of a task.
func (*Client) ListPushConfigs ¶
ListPushConfigs lists the push notification configs of a task.
func (*Client) SendMessage ¶
func (c *Client) SendMessage(ctx context.Context, headers Headers, text string, returnImmediately bool) *Outcome
SendMessage sends one user text message. returnImmediately asks the agent to answer as soon as the task exists, which is the only way to obtain a task that is still running.
func (*Client) StreamMessage ¶
StreamMessage sends one user text message as a stream and drains it to its end.
func (*Client) SubscribeToTask ¶
func (c *Client) SubscribeToTask(ctx context.Context, headers Headers, taskID string, maxEvents int) *Outcome
SubscribeToTask re-attaches to a task and stops after maxEvents events.
Bounded by events rather than by the terminal state: the task it attaches to is normally still running, so reading to the end would wait out the agent's whole hold. maxEvents must be positive.
type Event ¶
type Event struct {
// Type is the event kind: task, message, status-update or artifact-update.
Type string
// State is the task state the event carries, empty when it carries none.
State string
// Text is the event rendered as the text a scenario asserts on.
Text string
// TaskID is the task the event belongs to, empty when it names none.
TaskID string
// Artifact is the artifact text an artifact-update event carries.
Artifact string
Offset time.Duration
}
Event is one streamed event and when it was handed to the caller, measured from the start of the call. A response held whole and released at the end yields every event at effectively the same offset, which is what keeps buffering observable through the SDK.
type Headers ¶
Headers are request headers attached to a call, such as the credentials a scenario set. They are read per call, so a token obtained after the client was built still applies.
type Options ¶
type Options struct {
// ProtocolVersion is the A2A version the client states on every request. It is required:
// the gateway rejects an operation whose stated version is not the one its Agent exposes,
// so a defaulted value would make the rejection path the one a scenario exercises.
ProtocolVersion string
// CallTimeout bounds one unary call. Zero selects DefaultCallTimeout.
CallTimeout time.Duration
// StreamTimeout bounds one streamed call, including the time spent waiting for events.
// Zero selects DefaultStreamTimeout.
StreamTimeout time.Duration
}
Options configure a Client.
type Outcome ¶
type Outcome struct {
Method string
Err error
Task *Task
Message *string
Tasks []Task
Card *Card
PushConfig *PushConfig
PushConfigs []PushConfig
Events []Event
StreamDuration time.Duration
}
Outcome is the typed result of one call. Exactly one payload field is populated per call, or Err is set.
func (*Outcome) ArtifactText ¶
ArtifactText concatenates the text of every artifact the outcome carries, whether it arrived on a task or as streamed artifact-update events.
func (*Outcome) FinalState ¶
FinalState returns the task state carried by the last streamed event.
type PushConfig ¶
PushConfig identifies one push notification config.
type Task ¶
type Task struct {
ID string
ContextID string
// State is the protocol's state name, such as TASK_STATE_COMPLETED.
State string
// Terminal reports whether the state admits no further change.
Terminal bool
// Artifacts holds the text of each artifact, one entry per artifact.
Artifacts []string
}
Task is the part of an A2A task a scenario asserts on.
Source Files