client

Documentation

Overview

Package client implements interfaces.A2AClient, interfaces.A2AStreamingClient, and interfaces.A2ATaskClient using the github.com/a2aproject/a2a-go/v2 SDK. Application code creates a Client via NewClient and registers it with the agent via agent.WithA2AConfig. All operations share a single a2aclient.Client that is created lazily on first use from the resolved AgentCard.

Index

• type Client
  • func NewClient(name string, url string, opts ...Option) (*Client, error)
  • func (c *Client) CancelTask(ctx context.Context, taskID string) (interfaces.A2ATask, error)
  • func (c *Client) Close() error
  • func (c *Client) GetTask(ctx context.Context, taskID string) (interfaces.A2ATask, error)
  • func (c *Client) ListSkills(ctx context.Context) ([]interfaces.A2ASkillSpec, error)
  • func (c *Client) Name() string
  • func (c *Client) Ping(ctx context.Context) error
  • func (c *Client) ResolveCard(ctx context.Context) (interfaces.A2AAgentCard, error)
  • func (c *Client) SendMessage(ctx context.Context, req interfaces.A2ASendMessageRequest) (interfaces.A2ASendMessageResult, error)
  • func (c *Client) SendStreamingMessage(ctx context.Context, req interfaces.A2ASendMessageRequest) (interfaces.A2AStreamSeq, error)
• type ClientConfig
  • func BuildConfig(opts ...Option) (*ClientConfig, error)
• type Option
  • func WithHeaders(h map[string]string) Option
  • func WithLogLevel(level string) Option
  • func WithLogger(l logger.Logger) Option
  • func WithSkillFilter(f a2apkg.A2ASkillFilter) Option
  • func WithSkipTLSVerify(skip bool) Option
  • func WithTimeout(d time.Duration) Option
  • func WithToken(tok string) Option

Types

type Client

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

Client implements interfaces.A2AClient, interfaces.A2AStreamingClient, and interfaces.A2ATaskClient backed by a2aclient.Client from the a2aproject/a2a-go/v2 SDK.

The inner a2aclient.Client is created lazily on the first call that needs it (SendMessage, GetTask, CancelTask, SendStreamingMessage). [ResolveCard] and [ListSkills] use only the lightweight card resolver HTTP call. [Ping] also uses only the resolver.

All exported methods are safe for concurrent use. A single inner client is shared across calls.

func NewClient

func NewClient(name string, url string, opts ...Option) (*Client, error)

NewClient creates an A2A client connected to the agent server at url.

url is the base URL used for card resolution (e.g. "https://agent.example.com"). name identifies this connection for logging (equivalent role to the key in agent.A2AServers). opts are optional [Option]s; see BuildConfig for defaults.

NewClient does not open a network connection. The inner a2aclient.Client is created lazily on the first SendMessage / GetTask / CancelTask / SendStreamingMessage call.

func (*Client) CancelTask

func (c *Client) CancelTask(ctx context.Context, taskID string) (interfaces.A2ATask, error)

CancelTask implements interfaces.A2ATaskClient: requests cancellation of an in-progress task. The returned interfaces.A2ATask reflects the server-acknowledged state after cancellation.

func (*Client) Close

func (c *Client) Close() error

Close implements interfaces.A2AClient: destroys the inner client and marks this client as closed. Subsequent calls on a closed client return an error. Close is idempotent.

func (*Client) GetTask

func (c *Client) GetTask(ctx context.Context, taskID string) (interfaces.A2ATask, error)

GetTask implements interfaces.A2ATaskClient: retrieves the current state of an async task.

func (*Client) ListSkills

func (c *Client) ListSkills(ctx context.Context) ([]interfaces.A2ASkillSpec, error)

ListSkills implements interfaces.A2AClient: resolves the card and returns the skill specs. Skills are the A2A equivalent of tools and are used to expose the remote agent's capabilities to the LLM as Tool definitions. When WithSkillFilter is configured, only skills matching the allow/block lists are returned (types.A2ASkillFilter.Apply runs here).

func (*Client) Name

func (c *Client) Name() string

Name implements interfaces.A2AClient.

func (*Client) Ping

func (c *Client) Ping(ctx context.Context) error

Ping implements interfaces.A2AClient by resolving the agent card at the configured URL. A successful card resolution proves the server is reachable and well-formed.

func (*Client) ResolveCard

func (c *Client) ResolveCard(ctx context.Context) (interfaces.A2AAgentCard, error)

ResolveCard implements interfaces.A2AClient: fetches the AgentCard from the server's well-known endpoint. The resolved card is cached so that subsequent [ListSkills] calls (and the lazy inner-client creation) do not incur an additional round-trip.

func (*Client) SendMessage

func (c *Client) SendMessage(ctx context.Context, req interfaces.A2ASendMessageRequest) (interfaces.A2ASendMessageResult, error)

SendMessage implements interfaces.A2AClient: sends req to the agent and returns the result. The result contains either a completed interfaces.A2AMessage (synchronous response) or an interfaces.A2ATask (asynchronous; poll with [GetTask] or subscribe via [SendStreamingMessage]).

func (*Client) SendStreamingMessage

func (c *Client) SendStreamingMessage(ctx context.Context, req interfaces.A2ASendMessageRequest) (interfaces.A2AStreamSeq, error)

SendStreamingMessage implements interfaces.A2AStreamingClient: sends req and returns an iterator over events streamed back by the agent. Each event is one of: message delta, task status update, or artifact update.

The caller must either consume all events or break the iteration to release resources. The iterator is driven by ctx; cancel ctx to abort the stream.

When the server does not support streaming, the SDK falls back to a single non-streaming SendMessage call and wraps the result as a single event.

type ClientConfig

type ClientConfig struct {
	// Logger receives structured diagnostic output. When nil, [BuildConfig] creates a
	// stderr text logger at [LogLevel].
	Logger logger.Logger

	// LogLevel sets the level used when Logger is not provided ("debug", "info", "warn", "error").
	// Empty defaults to "error" in [BuildConfig].
	LogLevel string

	// Timeout is the deadline applied to each operation (card resolve, send message, get/cancel task).
	// Zero defaults to [types.DefaultA2ATimeout] in [BuildConfig].
	Timeout time.Duration

	// Token is a static bearer token. When non-empty, [BuildConfig] injects it as the
	// Authorization: Bearer <token> header (only if Authorization is not already in Headers).
	Token string

	// Headers are additional HTTP headers sent on every request (card resolution and A2A protocol calls).
	// Use this for API keys, correlation IDs, or any custom header your server requires.
	Headers map[string]string

	// SkipTLSVerify disables TLS certificate verification. Use only in development/testing.
	SkipTLSVerify bool

	// SkillFilter restricts which skills from [ListSkills] are returned (exact skill-ID match).
	// [BuildConfig] validates the filter; [Client.ListSkills] runs [a2apkg.A2ASkillFilter.Apply]
	// to restrict returned specs.
	SkillFilter a2apkg.A2ASkillFilter
}

ClientConfig holds optional settings for NewClient. Logger and LogLevel mirror pkg/llm and pkg/mcp/client patterns. Token, Headers, and SkipTLSVerify configure HTTP auth for both card resolution and A2A protocol calls. SkillFilter aligns with github.com/agenticenv/agent-sdk-go/pkg/agent.A2AConfig.SkillFilter (same field semantics as a2apkg.A2ASkillFilter).

func BuildConfig

func BuildConfig(opts ...Option) (*ClientConfig, error)

BuildConfig builds a ClientConfig from opts. Defaults when not set:

• LogLevel: "error"
• Logger: stderr text logger at LogLevel
• Timeout: types.DefaultA2ATimeout
• Token injected into Headers["Authorization"] if Token is set and key not already present

It returns an error if [ClientConfig.SkillFilter] fails a2apkg.A2ASkillFilter.Validate.

type Option

type Option func(*ClientConfig)

Option mutates ClientConfig when passed to BuildConfig or NewClient.

func WithHeaders

func WithHeaders(h map[string]string) Option

WithHeaders sets additional HTTP headers sent on every request (merged with any token header). Call multiple times; each call replaces the header map.

func WithLogLevel

func WithLogLevel(level string) Option

WithLogLevel sets the level used when WithLogger is not set (same level strings as logger.DefaultLogger: debug, info, warn, error). Empty defaults to "error" in BuildConfig.

func WithLogger

func WithLogger(l logger.Logger) Option

WithLogger sets the diagnostic logger for this client. When l is *logger.SlogLogger the underlying *slog.Logger is also forwarded where the SDK accepts one.

func WithSkillFilter

func WithSkillFilter(f a2apkg.A2ASkillFilter) Option

WithSkillFilter sets allow/block lists (same semantics as github.com/agenticenv/agent-sdk-go/pkg/agent.A2AConfig.SkillFilter). BuildConfig validates the filter; Client.ListSkills runs a2apkg.A2ASkillFilter.Apply to restrict returned specs.

func WithSkipTLSVerify

func WithSkipTLSVerify(skip bool) Option

WithSkipTLSVerify disables TLS certificate verification. Only use in development or testing.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the per-operation deadline (card resolve, SendMessage, GetTask, CancelTask). Zero means use [defaultA2ATimeout] in BuildConfig.

func WithToken

func WithToken(tok string) Option

WithToken sets a static bearer token. BuildConfig injects it as "Authorization: Bearer <token>" unless the caller already set that header via WithHeaders.