Documentation
¶
Overview ¶
Package a2aclient sends an envelope.Message to a remote agent and polls task status and results, through the a2aproject/a2a-go client. Send creates the remote task; Status reads it; Result fetches the output and re-verifies the signature after the network hop. See docs/plans/a2aclient.md for the contract.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrNoBaseURL = errors.New("a2aclient: baseURL is required")
transport is the remote operation set Client needs to run one task's lifecycle: send, poll, fetch, close. New builds the production transport, wrapping a2a-go's gRPC transport. newFromTransport injects a substitute transport instead of dialing a live network endpoint; this is the seam this package's own internal tests use for a recorded transcript, since sdk-standards.yml scopes the third-party- import exception to a2aclient/*.go and an external test package cannot import a2a-go directly. Both stay unexported: no caller outside this package's own tests needs them. See docs/plans/a2aclient.md's Verification section for the test seam. ErrNoBaseURL reports a New or newFromTransport call whose baseURL is empty. Test with errors.Is.
var ErrNoCredentials = errors.New("a2aclient: transport credentials are required")
ErrNoCredentials reports a NewWithCredentials call whose credentials are nil. Test with errors.Is.
var ErrNoDataPart = errors.New("a2aclient: result message carries no data part")
ErrNoDataPart reports a Result call whose result message carries no DataPart. Test with errors.Is.
var ErrNoResultMessage = errors.New("a2aclient: task carries no result message")
ErrNoResultMessage reports a Result call against a task that carries no status message and no history entry. Test with errors.Is.
var ErrNoTask = errors.New("a2aclient: send did not return a task")
ErrNoTask reports a Send call whose remote response was not a Task. Test with errors.Is.
var ErrNoTaskID = errors.New("a2aclient: transport returned an empty task id")
ErrNoTaskID reports a Send call whose transport returned an empty task id. Test with errors.Is.
var ErrNoTransport = errors.New("a2aclient: transport is required")
ErrNoTransport reports a newFromTransport call whose tr is nil. Test with errors.Is.
var ErrNotTerminal = errors.New("a2aclient: task is not terminal")
ErrNotTerminal reports a Result call against a task that has not yet reached a terminal State. Test with errors.Is.
var ErrSignatureCheckFailed = errors.New("a2aclient: signature check failed")
ErrSignatureCheckFailed reports a Result call whose mapped message fails VerifySignature after the remote hop. Test with errors.Is.
var ErrZeroTaskHandle = errors.New("a2aclient: zero TaskHandle")
ErrZeroTaskHandle reports a Status or Result call against the zero TaskHandle. Test with errors.Is.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client sends envelope messages to one remote A2A agent and reads task status and results back. Client wraps the a2aproject/a2a-go client for one base URL. The caller owns the Client; a Client is safe for concurrent use by multiple goroutines.
func New ¶
New builds a Client that talks to the A2A agent at baseURL over a plaintext gRPC channel. It suits loopback and otherwise trusted links only. New validates baseURL and opens the underlying a2a-go gRPC transport, which holds a persistent connection. It returns an error, not a partial Client, when baseURL is empty or the transport fails to open. The caller must call Close when done with the Client. Use NewWithCredentials for a remote link that needs TLS.
func NewWithCredentials ¶ added in v0.2.0
func NewWithCredentials(baseURL string, creds credentials.TransportCredentials) (*Client, error)
NewWithCredentials builds a Client that talks to the A2A agent at baseURL over a gRPC channel secured by creds. Pass a TLS credentials value for a remote link; nil fails with ErrNoCredentials, never an implicit dial mode. It returns an error, not a partial Client, when baseURL is empty, creds is nil, or the transport fails to open. The caller must call Close when done with the Client.
func (*Client) Close ¶
Close releases the resources New opened. a2a-go's gRPC transport wraps a persistent grpc.ClientConn; Close forwards to the transport's own teardown call. Close is idempotent: a second call returns nil. A Client whose Close was never called leaks the underlying connection, the same way an unclosed net.Conn does.
func (*Client) Result ¶
Result fetches the output of the task identified by h and maps it back to an envelope.Message through a2a.FromPart. Result calls msg.VerifySignature on the mapped message before returning it: the signature must still verify after the remote hop. Result returns an error, not a partial Message, when the task is not yet in a terminal state, when FromPart fails, when the signature check fails, or when ctx is canceled or its deadline expires.
func (*Client) Send ¶
Send maps msg to an A2A part through a2a.ToPart, then sends it to the remote agent as a new task. Send returns the TaskHandle identifying the created task. msg must already be signed; Send performs no signing of its own, matching a2a.ToPart's contract. A transport failure, a canceled ctx, or an expired ctx deadline returns an error and a zero TaskHandle, never a partial one.
func (*Client) Status ¶
Status reads the current state of the task identified by h from the remote agent. Status rejects the zero TaskHandle with an error. A canceled ctx or an expired ctx deadline returns that ctx error, unwrapped, so the caller can distinguish it from a remote failure with errors.Is(err, context.Canceled) or context.DeadlineExceeded.
type State ¶
type State int
State is the state of a remote task, mirrored from the a2a-go task state enum. Every a2a-go TaskState has one State. See the State constants for the closed set of values.
const ( StateUnspecified State = iota StateSubmitted StateWorking StateCompleted StateFailed StateCanceled StateRejected StateAuthRequired StateInputRequired StateUnknown )
The states a remote task passes through. A2A tasks move from submitted through working to one terminal state: completed, failed, canceled, or rejected. Auth-required and input-required both wait for client action. Unspecified and unknown both mean the state is not yet determined. StateUnknown's String is "unknown", the same text a State outside the declared range returns, so that text names either the upstream indeterminate state or an out-of-range value.
type TaskHandle ¶
type TaskHandle struct {
// contains filtered or unexported fields
}
TaskHandle identifies one remote task started by Send. The caller passes it back into Status and Result to track the same task. The zero TaskHandle identifies no task; Status and Result reject it.
Source Files