Documentation
¶
Overview ¶
Package a2a provides types for the Agent-to-Agent (A2A) protocol.
Types are derived from the A2A protocol specification (a2a.proto) and use camelCase JSON tags matching the JSON-RPC binding convention.
Index ¶
- Constants
- Variables
- func ExtractResponseParts(task *Task) []types.ContentPart
- func ExtractResponseText(task *Task) string
- func InferContentType(mediaType string) string
- func IsJSONRPCBinding(binding string) bool
- func LookupMethod(method string) (op Operation, v ProtocolVersion, ok bool)
- func MessageToMessage(msg *Message) (*types.Message, error)
- func PartToContentPart(part *Part) (types.ContentPart, error)
- func ReadSSE(ctx context.Context, r io.Reader, ch chan<- StreamEvent)
- func ReadSSEWithIdleTimeout(ctx context.Context, r io.Reader, ch chan<- StreamEvent, ...)
- type APIKeySecurityScheme
- type AgentCapabilities
- type AgentCard
- type AgentExtension
- type AgentInterface
- type AgentProvider
- type AgentSkill
- type Artifact
- type CancelTaskRequest
- type Client
- func (c *Client) CancelTask(ctx context.Context, taskID string) error
- func (c *Client) Discover(ctx context.Context) (*AgentCard, error)
- func (c *Client) GetTask(ctx context.Context, taskID string) (*Task, error)
- func (c *Client) ListTasks(ctx context.Context, params *ListTasksRequest) ([]*Task, error)
- func (c *Client) ListTasksPage(ctx context.Context, params *ListTasksRequest) (*ListTasksResponse, error)
- func (c *Client) ProtocolVersion() ProtocolVersion
- func (c *Client) SendMessage(ctx context.Context, params *SendMessageRequest) (*Task, error)
- func (c *Client) SendMessageStream(ctx context.Context, params *SendMessageRequest) (<-chan StreamEvent, error)
- func (c *Client) WaitForTask(ctx context.Context, task *Task) (*Task, error)
- type ClientOption
- func WithAuth(scheme, token string) ClientOption
- func WithHTTPClient(hc *http.Client) ClientOption
- func WithHeaders(headers map[string]string) ClientOption
- func WithProtocolVersion(v ProtocolVersion) ClientOption
- func WithRequestTimeout(d time.Duration) ClientOption
- func WithSSEIdleTimeout(d time.Duration) ClientOption
- type Executor
- func (e *Executor) Close() error
- func (e *Executor) Execute(ctx context.Context, descriptor *tools.ToolDescriptor, args json.RawMessage) (json.RawMessage, error)
- func (e *Executor) ExecuteMultimodal(ctx context.Context, descriptor *tools.ToolDescriptor, args json.RawMessage) (json.RawMessage, []types.ContentPart, error)
- func (e *Executor) Name() string
- type ExecutorOption
- type GetTaskRequest
- type HTTPAuthSecurityScheme
- type HTTPStatusError
- type JSONRPCError
- type JSONRPCRequest
- type JSONRPCResponse
- type ListTasksRequest
- type ListTasksResponse
- type Message
- type MutualTLSSecurityScheme
- type OAuth2SecurityScheme
- type OAuthFlow
- type OAuthFlows
- type OpenIDConnectSecurityScheme
- type Operation
- type Part
- type ProtocolVersion
- func (v ProtocolVersion) Method(op Operation) string
- func (v ProtocolVersion) WireAgentCard(card *AgentCard) any
- func (v ProtocolVersion) WireSendParams(req *SendMessageRequest) any
- func (v ProtocolVersion) WireSendResult(task *Task) any
- func (v ProtocolVersion) WireStreamEvent(event any) (any, error)
- func (v ProtocolVersion) WireTask(task *Task) any
- type RPCError
- type RetryPolicy
- type Role
- type SecurityRequirement
- type SecurityScheme
- type SendMessageConfiguration
- type SendMessageRequest
- type SendMessageResponse
- type StreamEvent
- type StreamResponse
- type SubscribeTaskRequest
- type Task
- type TaskArtifactUpdateEvent
- type TaskState
- type TaskStatus
- type TaskStatusUpdateEvent
- type ToolBridge
Examples ¶
Constants ¶
const ( AgentCardPath = "/.well-known/agent-card.json" LegacyAgentCardPath = "/.well-known/agent.json" )
Agent card discovery paths. A2A 0.3 (§5.3) and 1.0 (§8.2) serve the card at AgentCardPath; 0.2 and earlier servers used LegacyAgentCardPath.
const ( DefaultA2AMaxRetries = 3 DefaultA2AInitialDelay = 500 * time.Millisecond DefaultA2AMaxDelay = 30 * time.Second // DefaultClientTTL is the default time-to-live for cached A2A clients. // Clients not used within this duration are evicted from the cache. DefaultClientTTL = 30 * time.Minute // DefaultMaxClients is the default maximum number of cached A2A clients. // When exceeded, the least recently used client is evicted. DefaultMaxClients = 100 )
Default retry constants for A2A executor.
const ( MethodV1SendMessage = "SendMessage" MethodV1SendStreamingMessage = "SendStreamingMessage" MethodV1GetTask = "GetTask" MethodV1CancelTask = "CancelTask" MethodV1ListTasks = "ListTasks" MethodV1SubscribeToTask = "SubscribeToTask" MethodV1GetExtendedAgentCard = "GetExtendedAgentCard" MethodV1CreateTaskPushNotificationConfig = "CreateTaskPushNotificationConfig" MethodV1GetTaskPushNotificationConfig = "GetTaskPushNotificationConfig" MethodV1ListTaskPushNotificationConfigs = "ListTaskPushNotificationConfigs" MethodV1DeleteTaskPushNotificationConfig = "DeleteTaskPushNotificationConfig" )
A2A 1.0 JSON-RPC method names (A2A 1.0 §5.3).
const ( MethodSendMessage = "message/send" MethodSendStreamingMessage = "message/stream" MethodGetTask = "tasks/get" MethodCancelTask = "tasks/cancel" MethodListTasks = "tasks/list" MethodTaskSubscribe = "tasks/subscribe" )
The method names PromptKit used before it spoke A2A 1.0 and 0.3 by version. They keep their values: a server still answers every one of them, and code comparing against them keeps working.
Deprecated: use the MethodV1* names for A2A 1.0 and MethodV03* for 0.3, or resolve a method with LookupMethod.
const ( MethodV03SendMessage = "message/send" MethodV03SendStreamingMessage = "message/stream" MethodV03GetTask = "tasks/get" MethodV03CancelTask = "tasks/cancel" MethodV03Resubscribe = "tasks/resubscribe" MethodV03GetExtendedCard = "agent/getAuthenticatedExtendedCard" MethodV03SetPushNotificationConfig = "tasks/pushNotificationConfig/set" MethodV03GetPushNotificationConfig = "tasks/pushNotificationConfig/get" MethodV03ListPushNotificationConfig = "tasks/pushNotificationConfig/list" MethodV03DeletePushNotificationConfig = "tasks/pushNotificationConfig/delete" // MethodLegacyListTasks and MethodLegacySubscribe are the names PromptKit // servers before A2A 1.0 conformance answered to; they are in neither // 0.3 nor 1.0 and are accepted only so older PromptKit clients keep // working. MethodLegacyListTasks = MethodListTasks MethodLegacySubscribe = MethodTaskSubscribe )
A2A 0.3 JSON-RPC method names. A 0.3 server knows only these.
const ( ErrCodeTaskNotFound = -32001 ErrCodeTaskNotCancelable = -32002 ErrCodePushNotificationNotSupported = -32003 ErrCodeUnsupportedOperation = -32004 ErrCodeContentTypeNotSupported = -32005 ErrCodeInvalidAgentResponse = -32006 ErrCodeExtendedAgentCardNotConfigured = -32007 ErrCodeExtensionSupportRequired = -32008 ErrCodeVersionNotSupported = -32009 )
A2A-specific JSON-RPC error codes (A2A 1.0 §5.4, identical in 0.3).
const ( ErrCodeParse = -32700 ErrCodeInvalidRequest = -32600 ErrCodeMethodNotFound = -32601 ErrCodeInvalidParams = -32602 ErrCodeInternal = -32603 )
Standard JSON-RPC 2.0 error codes.
const ( // DefaultSSEIdleTimeout is the default idle timeout for SSE streams. // If no event is received within this duration, ReadSSE returns an error // so callers can reconnect. DefaultSSEIdleTimeout = 5 * time.Minute )
HTTP client defaults for A2A communication.
const HeaderVersion = "A2A-Version"
HeaderVersion is the service parameter carrying the protocol version a request speaks. A request without it is 0.3 (A2A 1.0 §3.6.2).
const ProtocolBindingJSONRPC = "JSONRPC"
ProtocolBindingJSONRPC is the AgentInterface binding name of the JSON-RPC transport (0.3 calls the same field "transport").
Variables ¶
var ErrSSEIdleTimeout = fmt.Errorf("a2a: SSE idle timeout exceeded")
ErrSSEIdleTimeout is returned when an SSE stream has not received any event within the configured idle timeout period.
Functions ¶
func ExtractResponseParts ¶
func ExtractResponseParts(task *Task) []types.ContentPart
ExtractResponseParts converts all A2A Parts from a completed task into PromptKit ContentParts. It collects parts from the status message (if present) and all artifacts. Parts that fail conversion (e.g., structured data) are silently skipped.
func ExtractResponseText ¶
ExtractResponseText extracts text from a completed A2A task. It checks the status message first, then artifacts.
func InferContentType ¶
InferContentType maps a MIME type to a PromptKit content type string.
func IsJSONRPCBinding ¶ added in v2.11.0
IsJSONRPCBinding reports whether binding names the JSON-RPC transport: ProtocolBindingJSONRPC in any case, or one of the names PromptKit used for it before A2A 1.0 (jsonrpc+http, json-rpc, jsonrpc2).
func LookupMethod ¶ added in v2.8.0
func LookupMethod(method string) (op Operation, v ProtocolVersion, ok bool)
LookupMethod resolves a JSON-RPC method name to its operation and the version that names it that way. ok is false for an unknown method.
func MessageToMessage ¶
MessageToMessage converts an A2A Message to a PromptKit Message.
Example ¶
ExampleMessageToMessage shows converting an A2A protocol Message into PromptKit's internal types.Message. This is a pure conversion — no network call or running A2A server required. The "agent" role maps to PromptKit's "assistant" role.
package main
import (
"fmt"
"github.com/AltairaLabs/PromptKit/runtime/v2/a2a"
)
func main() {
text := "hello from agent"
msg := &a2a.Message{
MessageID: "m1",
Role: a2a.RoleAgent,
Parts: []a2a.Part{{Text: &text}},
}
out, err := a2a.MessageToMessage(msg)
if err != nil {
fmt.Println("error:", err)
return
}
fmt.Println(out.Role, "->", out.GetContent())
}
Output: assistant -> hello from agent
func PartToContentPart ¶
func PartToContentPart(part *Part) (types.ContentPart, error)
PartToContentPart converts an A2A Part to a PromptKit ContentPart.
func ReadSSE ¶
func ReadSSE(ctx context.Context, r io.Reader, ch chan<- StreamEvent)
ReadSSE reads SSE events from r and sends parsed StreamEvents to ch. It has no idle timeout; use ReadSSEWithIdleTimeout for timeout support.
func ReadSSEWithIdleTimeout ¶
func ReadSSEWithIdleTimeout(ctx context.Context, r io.Reader, ch chan<- StreamEvent, idleTimeout time.Duration)
ReadSSEWithIdleTimeout reads SSE events from r and sends parsed StreamEvents to ch. If idleTimeout is positive and no line is received within that duration, reading stops (callers should reconnect). A zero or negative idleTimeout disables idle detection.
Types ¶
type APIKeySecurityScheme ¶ added in v2.8.0
type APIKeySecurityScheme struct {
Description string `json:"description,omitempty"`
// Location is "header", "query" or "cookie".
Location string `json:"location"`
Name string `json:"name"`
}
APIKeySecurityScheme is an API key sent in a header, query parameter or cookie.
type AgentCapabilities ¶
type AgentCapabilities struct {
Streaming bool `json:"streaming,omitempty"`
PushNotifications bool `json:"pushNotifications,omitempty"`
ExtendedAgentCard bool `json:"extendedAgentCard,omitempty"`
Extensions []AgentExtension `json:"extensions,omitempty"`
}
AgentCapabilities describes what the agent supports.
type AgentCard ¶
type AgentCard struct {
Name string `json:"name"`
Description string `json:"description,omitempty"`
Version string `json:"version,omitempty"`
Provider *AgentProvider `json:"provider,omitempty"`
Capabilities AgentCapabilities `json:"capabilities,omitzero"`
Skills []AgentSkill `json:"skills,omitempty"`
DefaultInputModes []string `json:"defaultInputModes,omitempty"`
DefaultOutputModes []string `json:"defaultOutputModes,omitempty"`
SupportedInterfaces []AgentInterface `json:"supportedInterfaces,omitempty"`
IconURL string `json:"iconUrl,omitempty"`
DocumentationURL string `json:"documentationUrl,omitempty"`
// SecuritySchemes declares the authentication schemes the agent accepts,
// keyed by a name SecurityRequirements refer to (A2A 1.0 §7.3).
SecuritySchemes map[string]SecurityScheme `json:"securitySchemes,omitempty"`
// SecurityRequirements lists the scheme combinations a caller must
// satisfy; any one requirement suffices.
SecurityRequirements []SecurityRequirement `json:"securityRequirements,omitempty"`
}
AgentCard describes an agent's capabilities and endpoints.
func (*AgentCard) PreferredVersion ¶ added in v2.8.0
func (card *AgentCard) PreferredVersion() ProtocolVersion
PreferredVersion picks the protocol version to speak to the agent that published card: 1.0 when any JSON-RPC interface declares it (or the card declares nothing), otherwise 0.3.
func (*AgentCard) UnmarshalJSON ¶ added in v2.8.0
UnmarshalJSON implements json.Unmarshaler. A 0.3 card declares its endpoint in url/preferredTransport/additionalInterfaces rather than supportedInterfaces, and its requirements in "security"; both are folded into the 1.0 fields when the card does not carry them itself.
type AgentExtension ¶
type AgentExtension struct {
URI string `json:"uri"`
Description string `json:"description,omitempty"`
Required bool `json:"required,omitempty"`
}
AgentExtension describes an optional protocol extension.
type AgentInterface ¶
type AgentInterface struct {
URL string `json:"url"`
// ProtocolBinding is the transport: [ProtocolBindingJSONRPC], "GRPC" or
// "HTTP+JSON".
ProtocolBinding string `json:"protocolBinding,omitempty"`
// ProtocolVersion is the A2A Major.Minor version served at URL.
ProtocolVersion string `json:"protocolVersion,omitempty"`
Tenant string `json:"tenant,omitempty"`
}
AgentInterface describes a protocol endpoint.
type AgentProvider ¶
type AgentProvider struct {
Organization string `json:"organization"`
URL string `json:"url,omitempty"`
}
AgentProvider identifies the organization behind an agent.
type AgentSkill ¶
type AgentSkill struct {
ID string `json:"id"`
Name string `json:"name"`
Description string `json:"description,omitempty"`
Tags []string `json:"tags,omitempty"`
Examples []string `json:"examples,omitempty"`
InputModes []string `json:"inputModes,omitempty"`
OutputModes []string `json:"outputModes,omitempty"`
SecurityRequirements []SecurityRequirement `json:"securityRequirements,omitempty"`
}
AgentSkill describes a specific skill an agent can perform.
type Artifact ¶
type Artifact struct {
ArtifactID string `json:"artifactId"`
Name string `json:"name,omitempty"`
Description string `json:"description,omitempty"`
Parts []Part `json:"parts"`
Extensions []string `json:"extensions,omitempty"`
Metadata map[string]any `json:"metadata,omitempty"`
}
Artifact is a named output generated by an agent.
func ContentPartsToArtifacts ¶
func ContentPartsToArtifacts(parts []types.ContentPart) ([]Artifact, error)
ContentPartsToArtifacts converts PromptKit ContentParts into A2A Artifacts. It creates a single Artifact containing all non-empty parts. Returns nil if parts is empty or all parts fail to convert.
type CancelTaskRequest ¶
CancelTaskRequest is the params for CancelTask (0.3: tasks/cancel).
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is an HTTP client for discovering and calling external A2A agents.
func NewClient ¶
func NewClient(baseURL string, opts ...ClientOption) *Client
NewClient creates a Client targeting baseURL.
func (*Client) CancelTask ¶
CancelTask cancels a task by ID (CancelTask; 0.3: tasks/cancel).
func (*Client) Discover ¶
Discover fetches the agent card, trying AgentCardPath first and falling back to LegacyAgentCardPath when the agent does not serve it (404/405). The card is cached after the first successful call.
func (*Client) ListTasks ¶
ListTasks lists one page of tasks (ListTasks, which A2A 1.0 added; to a 0.3 agent the client sends the legacy PromptKit tasks/list, which only PromptKit servers answer). The server returns at most params.PageSize tasks, or its default page size when that is unset (50 on a 1.0 server); use ListTasksPage to read the next-page token and page through the rest.
func (*Client) ListTasksPage ¶ added in v2.13.0
func (c *Client) ListTasksPage(ctx context.Context, params *ListTasksRequest) (*ListTasksResponse, error)
ListTasksPage lists one page of tasks, like ListTasks, and returns the whole response: NextPageToken (empty on the last page), PageSize and TotalSize. To read the next page, send the same params with PageToken set to NextPageToken.
func (*Client) ProtocolVersion ¶ added in v2.8.0
func (c *Client) ProtocolVersion() ProtocolVersion
ProtocolVersion returns the protocol version the client speaks.
func (*Client) SendMessage ¶
SendMessage sends a message (SendMessage; 0.3: message/send) and returns the resulting task.
An agent that answers with a Message rather than a Task gets a completed task synthesized around it, the message as its status message, so callers have one shape to read.
func (*Client) SendMessageStream ¶
func (c *Client) SendMessageStream(ctx context.Context, params *SendMessageRequest) (<-chan StreamEvent, error)
SendMessageStream sends a streaming message (SendStreamingMessage; 0.3: message/stream) and returns a channel of streaming events. The channel is closed when the stream ends or the context is canceled.
func (*Client) WaitForTask ¶ added in v2.8.0
WaitForTask polls task until it finishes or needs the caller (a terminal or interrupted state), and returns it as it then stands. A task that is already there is returned as is. ctx bounds the wait; when it ends, the last state seen is returned with ctx's error.
A SendMessage can come back before its task is done: with returnImmediately, from a 0.3 agent that does not block, or from a server that caps how long it holds a request.
type ClientOption ¶
type ClientOption func(*Client)
ClientOption configures a Client.
func WithAuth ¶
func WithAuth(scheme, token string) ClientOption
WithAuth sets the Authorization header on all requests.
func WithHTTPClient ¶
func WithHTTPClient(hc *http.Client) ClientOption
WithHTTPClient sets the underlying HTTP client.
func WithHeaders ¶
func WithHeaders(headers map[string]string) ClientOption
WithHeaders sets custom headers that are sent on all requests.
func WithProtocolVersion ¶ added in v2.8.0
func WithProtocolVersion(v ProtocolVersion) ClientOption
WithProtocolVersion pins the A2A protocol version the client speaks, disabling negotiation. Without it the client speaks 1.0, or what a discovered agent card prefers, and falls back to 0.3 when the agent rejects a 1.0 method.
func WithRequestTimeout ¶ added in v2.8.0
func WithRequestTimeout(d time.Duration) ClientOption
WithRequestTimeout sets the timeout for non-streaming requests (agent card discovery and message/send, tasks/get, ...). The default is 60s. It does not affect SSE streams, which are bounded by the SSE idle timeout instead. A zero or negative value leaves the default in place.
func WithSSEIdleTimeout ¶
func WithSSEIdleTimeout(d time.Duration) ClientOption
WithSSEIdleTimeout sets the idle timeout for SSE streams. If no event is received within this duration, the stream is considered stale and ReadSSE returns ErrSSEIdleTimeout so callers can reconnect. A zero or negative value disables the idle timeout.
type Executor ¶
type Executor struct {
// contains filtered or unexported fields
}
Executor implements tools.Executor and tools.MultimodalExecutor for A2A agent tools. It dispatches tool calls to remote A2A agents via the A2A client. The executor maintains a cache of A2A clients with TTL-based eviction. Call Close when you are done with the executor to release resources.
func NewExecutor ¶
func NewExecutor(opts ...ExecutorOption) *Executor
NewExecutor creates a new A2A executor with optional configuration. The executor starts a background goroutine for cache cleanup. Call Close when you are done with the executor.
func (*Executor) Execute ¶
func (e *Executor) Execute( ctx context.Context, descriptor *tools.ToolDescriptor, args json.RawMessage, ) (json.RawMessage, error)
Execute calls a remote A2A agent with the tool arguments and returns the response.
func (*Executor) ExecuteMultimodal ¶
func (e *Executor) ExecuteMultimodal( ctx context.Context, descriptor *tools.ToolDescriptor, args json.RawMessage, ) (json.RawMessage, []types.ContentPart, error)
ExecuteMultimodal calls a remote A2A agent and returns both JSON result and multimodal content parts. It implements tools.MultimodalExecutor.
type ExecutorOption ¶
type ExecutorOption func(*Executor)
ExecutorOption configures an Executor.
func WithClientTTL ¶
func WithClientTTL(d time.Duration) ExecutorOption
WithClientTTL sets the time-to-live for cached A2A clients. Clients not used within this duration are evicted from the cache.
func WithMaxClients ¶
func WithMaxClients(n int) ExecutorOption
WithMaxClients sets the maximum number of cached A2A clients. When exceeded, the least recently used client is evicted.
func WithNoRetry ¶
func WithNoRetry() ExecutorOption
WithNoRetry disables retry for the A2A executor.
func WithRetryPolicy ¶
func WithRetryPolicy(policy RetryPolicy) ExecutorOption
WithRetryPolicy sets the retry policy for the A2A executor.
type GetTaskRequest ¶
type GetTaskRequest struct {
Tenant string `json:"tenant,omitempty"`
ID string `json:"id"`
HistoryLength *int `json:"historyLength,omitempty"`
}
GetTaskRequest is the params for GetTask (0.3: tasks/get).
type HTTPAuthSecurityScheme ¶ added in v2.8.0
type HTTPAuthSecurityScheme struct {
Description string `json:"description,omitempty"`
Scheme string `json:"scheme"`
BearerFormat string `json:"bearerFormat,omitempty"`
}
HTTPAuthSecurityScheme is an HTTP Authorization scheme such as Bearer.
type HTTPStatusError ¶
HTTPStatusError is returned when an A2A HTTP request receives a non-200 status code.
func (*HTTPStatusError) Error ¶
func (e *HTTPStatusError) Error() string
type JSONRPCError ¶
type JSONRPCError struct {
Code int `json:"code"`
Message string `json:"message"`
Data any `json:"data,omitempty"`
}
JSONRPCError is a JSON-RPC 2.0 error object.
type JSONRPCRequest ¶
type JSONRPCRequest struct {
JSONRPC string `json:"jsonrpc"`
ID any `json:"id"`
Method string `json:"method"`
Params json.RawMessage `json:"params,omitempty"`
}
JSONRPCRequest is a JSON-RPC 2.0 request.
type JSONRPCResponse ¶
type JSONRPCResponse struct {
JSONRPC string `json:"jsonrpc"`
ID any `json:"id"`
Result json.RawMessage `json:"result,omitempty"`
Error *JSONRPCError `json:"error,omitempty"`
}
JSONRPCResponse is a JSON-RPC 2.0 response.
type ListTasksRequest ¶
type ListTasksRequest struct {
Tenant string `json:"tenant,omitempty"`
ContextID string `json:"contextId,omitempty"`
Status *TaskState `json:"status,omitempty"`
PageSize int `json:"pageSize,omitempty"`
PageToken string `json:"pageToken,omitempty"`
HistoryLength *int `json:"historyLength,omitempty"`
StatusTimestampAfter *time.Time `json:"statusTimestampAfter,omitempty"`
// IncludeArtifacts asks for each task's artifacts; they are omitted by
// default.
IncludeArtifacts bool `json:"includeArtifacts,omitempty"`
}
ListTasksRequest is the params for ListTasks (1.0 only).
type ListTasksResponse ¶
type ListTasksResponse struct {
Tasks []Task `json:"tasks"`
NextPageToken string `json:"nextPageToken"`
PageSize int `json:"pageSize"`
TotalSize int `json:"totalSize"`
}
ListTasksResponse is the result for ListTasks. NextPageToken is empty on the last page.
type Message ¶
type Message struct {
MessageID string `json:"messageId"`
ContextID string `json:"contextId,omitempty"`
TaskID string `json:"taskId,omitempty"`
Role Role `json:"role"`
Parts []Part `json:"parts"`
ReferenceTaskIDs []string `json:"referenceTaskIds,omitempty"`
Extensions []string `json:"extensions,omitempty"`
Metadata map[string]any `json:"metadata,omitempty"`
}
Message is a communication unit in the A2A protocol.
type MutualTLSSecurityScheme ¶ added in v2.8.0
type MutualTLSSecurityScheme struct {
Description string `json:"description,omitempty"`
}
MutualTLSSecurityScheme is mutual TLS.
type OAuth2SecurityScheme ¶ added in v2.8.0
type OAuth2SecurityScheme struct {
Description string `json:"description,omitempty"`
Flows OAuthFlows `json:"flows"`
OAuth2MetadataURL string `json:"oauth2MetadataUrl,omitempty"`
}
OAuth2SecurityScheme is OAuth 2.0.
type OAuthFlow ¶ added in v2.8.0
type OAuthFlow struct {
AuthorizationURL string `json:"authorizationUrl,omitempty"`
DeviceAuthorizationURL string `json:"deviceAuthorizationUrl,omitempty"`
TokenURL string `json:"tokenUrl,omitempty"`
RefreshURL string `json:"refreshUrl,omitempty"`
Scopes map[string]string `json:"scopes"`
PKCERequired bool `json:"pkceRequired,omitempty"`
}
OAuthFlow is one OAuth 2.0 flow; which URLs apply depends on the flow.
type OAuthFlows ¶ added in v2.8.0
type OAuthFlows struct {
AuthorizationCode *OAuthFlow `json:"authorizationCode,omitempty"`
ClientCredentials *OAuthFlow `json:"clientCredentials,omitempty"`
DeviceCode *OAuthFlow `json:"deviceCode,omitempty"`
Implicit *OAuthFlow `json:"implicit,omitempty"`
Password *OAuthFlow `json:"password,omitempty"`
}
OAuthFlows lists the OAuth 2.0 flows the agent supports.
type OpenIDConnectSecurityScheme ¶ added in v2.8.0
type OpenIDConnectSecurityScheme struct {
Description string `json:"description,omitempty"`
OpenIDConnectURL string `json:"openIdConnectUrl"`
}
OpenIDConnectSecurityScheme is OpenID Connect discovery.
type Operation ¶ added in v2.8.0
type Operation int
Operation is a protocol operation, independent of any version's name for it.
type Part ¶
type Part struct {
Text *string `json:"text,omitempty"`
Raw []byte `json:"raw,omitempty"`
URL *string `json:"url,omitempty"`
Data map[string]any `json:"data,omitempty"`
// DataValue holds a data part whose value is not a JSON object: A2A 1.0
// types data as any JSON value (an array, string, number or boolean as
// well). An object is decoded into Data; anything else into DataValue.
// When both are set, Data is sent.
DataValue any `json:"-"`
Metadata map[string]any `json:"metadata,omitempty"`
Filename string `json:"filename,omitempty"`
MediaType string `json:"mediaType,omitempty"`
}
Part represents a piece of content within a message or artifact. Exactly one of Text, Raw, URL, or Data (or DataValue) should be set.
func ContentPartToA2APart ¶
func ContentPartToA2APart(part types.ContentPart) (Part, error)
ContentPartToA2APart converts a PromptKit ContentPart to an A2A Part.
func (Part) MarshalJSON ¶ added in v2.11.0
MarshalJSON implements json.Marshaler. It writes the A2A 1.0 shape, with "data" carrying Data (an empty object included) or DataValue.
func (*Part) UnmarshalJSON ¶ added in v2.8.0
UnmarshalJSON implements json.Unmarshaler. Besides the A2A 1.0 shape it accepts 0.3's kind-tagged parts: {"kind":"text"}, {"kind":"data"} and {"kind":"file","file":{"bytes"|"uri",...}}.
type ProtocolVersion ¶ added in v2.8.0
type ProtocolVersion string
ProtocolVersion is an A2A protocol version, as Major.Minor (A2A 1.0 §3.6).
const ( ProtocolVersion10 ProtocolVersion = "1.0" ProtocolVersion03 ProtocolVersion = "0.3" )
Supported protocol versions.
func ParseProtocolVersion ¶ added in v2.8.0
func ParseProtocolVersion(s string) (ProtocolVersion, error)
ParseProtocolVersion resolves an A2A-Version value to a supported version. Patch numbers are ignored, as the spec requires. An empty value returns ("", nil): the caller decides what an unversioned request means.
func (ProtocolVersion) Method ¶ added in v2.8.0
func (v ProtocolVersion) Method(op Operation) string
Method returns version v's JSON-RPC method name for op (1.0's for any version other than 0.3). 0.3 has no ListTasks; the legacy PromptKit name is returned for it.
func (ProtocolVersion) WireAgentCard ¶ added in v2.8.0
func (v ProtocolVersion) WireAgentCard(card *AgentCard) any
WireAgentCard returns card in version v's shape.
For 1.0 the card is returned as is. For 0.3 (and for a request that names no version, which the spec reads as 0.3) it is the 0.3 card (url, preferredTransport, protocolVersion, additionalInterfaces, 0.3-style security) with supportedInterfaces kept as well, so a 1.0 client reading the same document still finds its interface.
func (ProtocolVersion) WireSendParams ¶ added in v2.8.0
func (v ProtocolVersion) WireSendParams(req *SendMessageRequest) any
WireSendParams returns SendMessage params in version v's shape (0.3 parts are kind-tagged).
func (ProtocolVersion) WireSendResult ¶ added in v2.8.0
func (v ProtocolVersion) WireSendResult(task *Task) any
WireSendResult returns the SendMessage result for task in version v's shape: 1.0 wraps it as {"task": ...}, 0.3 sends the kind-tagged task bare.
func (ProtocolVersion) WireStreamEvent ¶ added in v2.8.0
func (v ProtocolVersion) WireStreamEvent(event any) (any, error)
WireStreamEvent returns one streaming result in version v's shape. event is a *Task, *Message, *TaskStatusUpdateEvent or *TaskArtifactUpdateEvent. 1.0 wraps it in a StreamResponse; 0.3 sends it bare with its "kind" and, on a status update, "final" set when the state ends the stream.
func (ProtocolVersion) WireTask ¶ added in v2.8.0
func (v ProtocolVersion) WireTask(task *Task) any
WireTask returns task in version v's shape (the result of GetTask and CancelTask).
type RPCError ¶
type RPCError struct {
Code int
Message string
// Data is the error object's optional data member (A2A 1.0 §9.5: an
// array of detail objects, each with an "@type").
Data any
}
RPCError represents a JSON-RPC error returned by an A2A agent.
type RetryPolicy ¶
RetryPolicy configures retry behavior for the A2A executor.
func DefaultRetryPolicy ¶
func DefaultRetryPolicy() RetryPolicy
DefaultRetryPolicy returns the default retry policy for A2A calls.
type Role ¶
type Role string
Role identifies the sender of a message.
Like TaskState, a Role marshals to its A2A 1.0 name (ROLE_USER) and unmarshals from either version's spelling.
func (Role) MarshalJSON ¶ added in v2.8.0
MarshalJSON implements json.Marshaler, writing the A2A 1.0 name.
func (*Role) UnmarshalJSON ¶ added in v2.8.0
UnmarshalJSON implements json.Unmarshaler, accepting either version's spelling. An unrecognized role is kept verbatim.
type SecurityRequirement ¶ added in v2.8.0
SecurityRequirement names the schemes (and their scopes) a caller must satisfy together. It marshals in the 1.0 shape ({"schemes": {"bearer": {"list": []}}}) and unmarshals from that or 0.3's {"bearer": []}.
func RequireScheme ¶ added in v2.8.0
func RequireScheme(name string, scopes ...string) SecurityRequirement
RequireScheme returns a requirement for a single scheme with optional scopes.
func (SecurityRequirement) MarshalJSON ¶ added in v2.8.0
func (r SecurityRequirement) MarshalJSON() ([]byte, error)
MarshalJSON implements json.Marshaler in the A2A 1.0 shape.
func (*SecurityRequirement) UnmarshalJSON ¶ added in v2.8.0
func (r *SecurityRequirement) UnmarshalJSON(data []byte) error
UnmarshalJSON implements json.Unmarshaler for both versions' shapes.
type SecurityScheme ¶ added in v2.8.0
type SecurityScheme struct {
APIKey *APIKeySecurityScheme `json:"apiKeySecurityScheme,omitempty"`
HTTPAuth *HTTPAuthSecurityScheme `json:"httpAuthSecurityScheme,omitempty"`
OAuth2 *OAuth2SecurityScheme `json:"oauth2SecurityScheme,omitempty"`
OpenIDConnect *OpenIDConnectSecurityScheme `json:"openIdConnectSecurityScheme,omitempty"`
MutualTLS *MutualTLSSecurityScheme `json:"mtlsSecurityScheme,omitempty"`
}
SecurityScheme declares one way a caller can authenticate (A2A 1.0 §4.5). Exactly one field is set. It marshals in the 1.0 shape ({"httpAuthSecurityScheme": {...}}) and unmarshals from either that or 0.3's OpenAPI-style {"type": "http", ...}.
func (*SecurityScheme) UnmarshalJSON ¶ added in v2.8.0
func (s *SecurityScheme) UnmarshalJSON(data []byte) error
UnmarshalJSON implements json.Unmarshaler for both versions' shapes.
type SendMessageConfiguration ¶
type SendMessageConfiguration struct {
AcceptedOutputModes []string `json:"acceptedOutputModes,omitempty"`
HistoryLength *int `json:"historyLength,omitempty"`
// Blocking is A2A 0.3's switch.
Blocking bool `json:"blocking,omitempty"`
// ReturnImmediately is A2A 1.0's switch.
ReturnImmediately bool `json:"returnImmediately,omitempty"`
}
SendMessageConfiguration controls message handling.
Blocking and ReturnImmediately are the same switch in two versions: A2A 0.3 sends blocking (default false), 1.0 sends returnImmediately (default false, so 1.0 blocks by default). A server reads the one its caller's version defines; see SendMessageConfiguration.WaitsForCompletion.
func (*SendMessageConfiguration) WaitsForCompletion ¶ added in v2.8.0
func (c *SendMessageConfiguration) WaitsForCompletion(v ProtocolVersion) bool
WaitsForCompletion reports whether a SendMessage under version v should wait for the task to finish or be interrupted before answering. A nil configuration takes the version's default.
type SendMessageRequest ¶
type SendMessageRequest struct {
Tenant string `json:"tenant,omitempty"`
Message Message `json:"message"`
Configuration *SendMessageConfiguration `json:"configuration,omitempty"`
Metadata map[string]any `json:"metadata,omitempty"`
}
SendMessageRequest is the params for SendMessage and SendStreamingMessage (0.3: message/send, message/stream).
type SendMessageResponse ¶ added in v2.8.0
type SendMessageResponse struct {
Task *Task `json:"task,omitempty"`
Message *Message `json:"message,omitempty"`
}
SendMessageResponse is the A2A 1.0 result of SendMessage: exactly one of Task or Message is set. (0.3 returns the Task or Message bare.)
type StreamEvent ¶
type StreamEvent struct {
Task *Task
Message *Message
StatusUpdate *TaskStatusUpdateEvent
ArtifactUpdate *TaskArtifactUpdateEvent
// Error is set when the agent ends the stream with a JSON-RPC error
// (an *RPCError). It is the last event on the channel.
Error error
}
StreamEvent represents a single event received during message streaming. Exactly one field will be non-nil. A conforming agent opens a task stream with the Task itself, or answers with a single Message.
type StreamResponse ¶ added in v2.8.0
type StreamResponse struct {
Task *Task `json:"task,omitempty"`
Message *Message `json:"message,omitempty"`
StatusUpdate *TaskStatusUpdateEvent `json:"statusUpdate,omitempty"`
ArtifactUpdate *TaskArtifactUpdateEvent `json:"artifactUpdate,omitempty"`
}
StreamResponse is one A2A 1.0 streaming result: exactly one field is set. (0.3 sends each object bare, discriminated by its "kind".)
type SubscribeTaskRequest ¶
SubscribeTaskRequest is the params for SubscribeToTask (0.3: tasks/resubscribe).
type Task ¶
type Task struct {
ID string `json:"id"`
ContextID string `json:"contextId"`
Status TaskStatus `json:"status"`
Artifacts []Artifact `json:"artifacts,omitempty"`
History []Message `json:"history,omitempty"`
Metadata map[string]any `json:"metadata,omitempty"`
}
Task is the top-level unit of work in the A2A protocol.
type TaskArtifactUpdateEvent ¶
type TaskArtifactUpdateEvent struct {
TaskID string `json:"taskId"`
ContextID string `json:"contextId"`
Artifact Artifact `json:"artifact"`
Append bool `json:"append,omitempty"`
LastChunk bool `json:"lastChunk,omitempty"`
Metadata map[string]any `json:"metadata,omitempty"`
}
TaskArtifactUpdateEvent is sent during streaming when an artifact is produced.
type TaskState ¶
type TaskState string
TaskState represents the state of an A2A task.
The Go values are PromptKit's own and never appear on the wire: a TaskState marshals to its A2A 1.0 name (TASK_STATE_COMPLETED, ...) and unmarshals from the 1.0, 0.3 (input-required) and legacy (input_required) spellings alike.
const ( TaskStateSubmitted TaskState = "submitted" TaskStateWorking TaskState = "working" TaskStateCompleted TaskState = "completed" TaskStateFailed TaskState = "failed" TaskStateCanceled TaskState = "canceled" TaskStateInputRequired TaskState = "input_required" TaskStateRejected TaskState = "rejected" TaskStateAuthRequired TaskState = "auth_required" // TaskStateUnknown is 1.0's TASK_STATE_UNSPECIFIED and 0.3's "unknown". TaskStateUnknown TaskState = "unknown" )
TaskState constants for the A2A protocol.
func ParseTaskState ¶ added in v2.8.0
ParseTaskState resolves a wire spelling (1.0, 0.3 or legacy PromptKit) to a TaskState.
func (TaskState) IsInterrupted ¶ added in v2.8.0
IsInterrupted reports whether s pauses the task for the client (input-required or auth-required). A stream ends at an interrupted state.
func (TaskState) IsTerminal ¶ added in v2.8.0
IsTerminal reports whether no further transitions are possible from s.
func (TaskState) MarshalJSON ¶
MarshalJSON implements json.Marshaler, writing the A2A 1.0 name.
func (*TaskState) UnmarshalJSON ¶
UnmarshalJSON implements json.Unmarshaler, accepting any version's spelling.
type TaskStatus ¶
type TaskStatus struct {
State TaskState `json:"state"`
Message *Message `json:"message,omitempty"`
Timestamp *time.Time `json:"timestamp,omitempty"`
}
TaskStatus describes the current status of a task.
type TaskStatusUpdateEvent ¶
type TaskStatusUpdateEvent struct {
TaskID string `json:"taskId"`
ContextID string `json:"contextId"`
Status TaskStatus `json:"status"`
Metadata map[string]any `json:"metadata,omitempty"`
}
TaskStatusUpdateEvent is sent during streaming when a task's status changes.
type ToolBridge ¶
type ToolBridge struct {
// contains filtered or unexported fields
}
ToolBridge discovers an A2A agent and creates ToolDescriptor entries for each of the agent's skills so they can be invoked through the standard tool registry.
func NewToolBridge ¶
func NewToolBridge(client *Client) *ToolBridge
NewToolBridge creates a ToolBridge backed by the given A2A client.
func NewToolBridgeWithConfig ¶
func NewToolBridgeWithConfig(client *Client, cfg *tools.A2AConfig) *ToolBridge
NewToolBridgeWithConfig creates a ToolBridge that applies the given A2AConfig (headers, auth, retry, skill filter) to all generated tool descriptors.
func (*ToolBridge) GetToolDescriptors ¶
func (b *ToolBridge) GetToolDescriptors() []*tools.ToolDescriptor
GetToolDescriptors returns all tool descriptors accumulated via RegisterAgent calls.
func (*ToolBridge) RegisterAgent ¶
func (b *ToolBridge) RegisterAgent(ctx context.Context) ([]*tools.ToolDescriptor, error)
RegisterAgent discovers the agent card and creates a ToolDescriptor for each skill. The descriptors are appended to the bridge's internal list (supporting multi-agent composition via GetToolDescriptors). Skills excluded by the skill filter are skipped.
func (*ToolBridge) ShareCards ¶ added in v2.11.0
func (b *ToolBridge) ShareCards(e *Executor)
ShareCards hands the agent card the bridge discovered to e, so the tools it registered reach the interface the card declares without e fetching the card again. It does nothing before RegisterAgent has succeeded.