a2a

Documentation

Index

• Constants
• type AgentCapabilities
• type AgentCard
  • func BuildAgentCard(cfg *config.AgentConfig, baseURL string) *AgentCard
• type AgentProvider
• type AgentSkill
• type Artifact
• type AuthConfig
• type FileContent
• type Handler
  • func NewHandler(cfg *config.Config, db *sql.DB, eventBus *events.EventBus, port string) *Handler
  • func (h *Handler) HandleAgentCard(w http.ResponseWriter, r *http.Request)
  • func (h *Handler) HandleJSONRPC(w http.ResponseWriter, r *http.Request)
• type JSONRPCRequest
• type JSONRPCResponse
• type Message
• type MessageSendParams
• type Part
• type PushNotificationConfig
• type PushNotificationConfigParams
• type RPCError
• type SecurityScheme
• type SendMessageConfig
• type Task
• type TaskArtifactUpdateEvent
• type TaskCancelParams
• type TaskGetParams
• type TaskStatus
• type TaskStatusUpdateEvent

Constants

const (
	ErrCodeParseError     = -32700
	ErrCodeInvalidRequest = -32600
	ErrCodeMethodNotFound = -32601
	ErrCodeInvalidParams  = -32602
	ErrCodeInternalError  = -32603
	ErrCodeServerError    = -32000 // Application-level error
)

Standard JSON-RPC error codes.

const (
	TaskStateSubmitted     = "submitted"
	TaskStateWorking       = "working"
	TaskStateCompleted     = "completed"
	TaskStateFailed        = "failed"
	TaskStateCanceled      = "canceled"
	TaskStateInputRequired = "input-required"
	TaskStateAuthRequired  = "auth-required"
	TaskStateRejected      = "rejected"
)

Task state constants following the A2A spec.

const (
	// A2AProtocolVersion is the A2A protocol version we implement.
	A2AProtocolVersion = "0.3"
)

Types

type AgentCapabilities

type AgentCapabilities struct {
	Streaming              bool `json:"streaming"`
	PushNotifications      bool `json:"pushNotifications"`
	StateTransitionHistory bool `json:"stateTransitionHistory"`
}

AgentCapabilities declares what protocol features the agent supports.

type AgentCard

type AgentCard struct {
	Name               string                    `json:"name"`
	Description        string                    `json:"description"`
	URL                string                    `json:"url"`
	Version            string                    `json:"version"`
	IconURL            string                    `json:"iconUrl,omitempty"`
	DocumentationURL   string                    `json:"documentationUrl,omitempty"`
	Provider           *AgentProvider            `json:"provider,omitempty"`
	Capabilities       AgentCapabilities         `json:"capabilities"`
	Skills             []AgentSkill              `json:"skills"`
	DefaultInputModes  []string                  `json:"defaultInputModes"`
	DefaultOutputModes []string                  `json:"defaultOutputModes"`
	SecuritySchemes    map[string]SecurityScheme `json:"securitySchemes,omitempty"`
	Security           []map[string][]string     `json:"security,omitempty"`
}

AgentCard describes an agent's identity, capabilities, and skills. Served at /.well-known/agent.json for A2A discovery.

func BuildAgentCard

func BuildAgentCard(cfg *config.AgentConfig, baseURL string) *AgentCard

BuildAgentCard generates an A2A Agent Card from the agent configuration. The card is served at /.well-known/agent.json for discovery.

type AgentProvider

type AgentProvider struct {
	Organization string `json:"organization"`
	URL          string `json:"url,omitempty"`
}

AgentProvider identifies the organization behind the agent.

type AgentSkill

type AgentSkill struct {
	ID          string   `json:"id"`
	Name        string   `json:"name"`
	Description string   `json:"description"`
	Tags        []string `json:"tags,omitempty"`
	InputModes  []string `json:"inputModes,omitempty"`
	OutputModes []string `json:"outputModes,omitempty"`
	Examples    []string `json:"examples,omitempty"`
}

AgentSkill describes a specific capability the agent offers.

type Artifact

type Artifact struct {
	ArtifactID  string `json:"artifactId,omitempty"`
	Name        string `json:"name,omitempty"`
	Description string `json:"description,omitempty"`
	Parts       []Part `json:"parts"`
	Index       int    `json:"index,omitempty"`
	Append      bool   `json:"append,omitempty"`
	LastChunk   bool   `json:"lastChunk,omitempty"`
}

Artifact is a tangible output generated during task execution.

type AuthConfig

type AuthConfig struct {
	Schemes []string `json:"schemes"`
	Token   string   `json:"token,omitempty"`
}

AuthConfig specifies authentication for push notification delivery.

type FileContent

type FileContent struct {
	Name     string `json:"name,omitempty"`
	MimeType string `json:"mimeType,omitempty"`
	Bytes    string `json:"bytes,omitempty"` // base64-encoded
	URI      string `json:"uri,omitempty"`
}

FileContent represents a file attachment (inline bytes or URI reference).

type Handler

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

Handler serves A2A protocol endpoints.

func NewHandler

func NewHandler(cfg *config.Config, db *sql.DB, eventBus *events.EventBus, port string) *Handler

NewHandler creates a new A2A protocol handler.

func (*Handler) HandleAgentCard

func (h *Handler) HandleAgentCard(w http.ResponseWriter, r *http.Request)

HandleAgentCard serves the A2A Agent Card at /.well-known/agent.json

func (*Handler) HandleJSONRPC

func (h *Handler) HandleJSONRPC(w http.ResponseWriter, r *http.Request)

HandleJSONRPC is the main A2A endpoint handling JSON-RPC 2.0 requests.

type JSONRPCRequest

type JSONRPCRequest struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      interface{}     `json:"id"`
	Method  string          `json:"method"`
	Params  json.RawMessage `json:"params,omitempty"`
}

JSONRPCRequest is the JSON-RPC 2.0 request envelope.

type JSONRPCResponse

type JSONRPCResponse struct {
	JSONRPC string      `json:"jsonrpc"`
	ID      interface{} `json:"id"`
	Result  interface{} `json:"result,omitempty"`
	Error   *RPCError   `json:"error,omitempty"`
}

JSONRPCResponse is the JSON-RPC 2.0 response envelope.

type Message

type Message struct {
	Role      string `json:"role"` // "user" or "agent"
	MessageID string `json:"messageId,omitempty"`
	Parts     []Part `json:"parts"`
}

Message is a single communication turn containing one or more Parts.

type MessageSendParams

type MessageSendParams struct {
	Message       Message            `json:"message"`
	ContextID     string             `json:"contextId,omitempty"`
	TaskID        string             `json:"taskId,omitempty"`
	Configuration *SendMessageConfig `json:"configuration,omitempty"`
}

MessageSendParams are the params for message/send and message/stream.

type Part

type Part struct {
	Kind     string                 `json:"kind"` // "text", "file", "data"
	Text     string                 `json:"text,omitempty"`
	File     *FileContent           `json:"file,omitempty"`
	Data     map[string]interface{} `json:"data,omitempty"`
	Metadata map[string]interface{} `json:"metadata,omitempty"`
}

Part is the fundamental content container. Each holds exactly one content type.

type PushNotificationConfig

type PushNotificationConfig struct {
	URL            string      `json:"url"`
	Token          string      `json:"token,omitempty"`
	Authentication *AuthConfig `json:"authentication,omitempty"`
}

PushNotificationConfig configures webhook delivery for task updates.

type PushNotificationConfigParams

type PushNotificationConfigParams struct {
	TaskID                 string                  `json:"id"`
	PushNotificationConfig *PushNotificationConfig `json:"pushNotificationConfig,omitempty"`
}

PushNotificationConfigParams are used for push notification CRUD operations.

type RPCError

type RPCError struct {
	Code    int         `json:"code"`
	Message string      `json:"message"`
	Data    interface{} `json:"data,omitempty"`
}

RPCError represents a JSON-RPC 2.0 error object.

type SecurityScheme

type SecurityScheme struct {
	Type        string `json:"type"`             // "apiKey", "http", "oauth2", "openIdConnect"
	In          string `json:"in,omitempty"`     // "header", "query"
	Name        string `json:"name,omitempty"`   // Header/param name
	Scheme      string `json:"scheme,omitempty"` // "bearer", "basic"
	Description string `json:"description,omitempty"`
}

SecurityScheme defines an authentication method (aligned with OpenAPI).

type SendMessageConfig

type SendMessageConfig struct {
	AcceptedOutputModes    []string                `json:"acceptedOutputModes,omitempty"`
	Blocking               *bool                   `json:"blocking,omitempty"`
	HistoryLength          *int                    `json:"historyLength,omitempty"`
	PushNotificationConfig *PushNotificationConfig `json:"pushNotificationConfig,omitempty"`
}

SendMessageConfig controls request behavior.

type Task

type Task struct {
	Kind      string                 `json:"kind"` // Always "task"
	ID        string                 `json:"id"`
	ContextID string                 `json:"contextId,omitempty"`
	Status    TaskStatus             `json:"status"`
	History   []Message              `json:"history,omitempty"`
	Artifacts []Artifact             `json:"artifacts,omitempty"`
	Metadata  map[string]interface{} `json:"metadata,omitempty"`
}

Task is the A2A representation of a unit of work.

type TaskArtifactUpdateEvent

type TaskArtifactUpdateEvent struct {
	Kind     string   `json:"kind"` // "artifact-update"
	TaskID   string   `json:"taskId"`
	Artifact Artifact `json:"artifact"`
}

TaskArtifactUpdateEvent is sent via SSE for incremental artifact delivery.

type TaskCancelParams

type TaskCancelParams struct {
	TaskID string `json:"id"`
}

TaskCancelParams are the params for tasks/cancel.

type TaskGetParams

type TaskGetParams struct {
	TaskID        string `json:"id"`
	HistoryLength *int   `json:"historyLength,omitempty"`
}

TaskGetParams are the params for tasks/get.

type TaskStatus

type TaskStatus struct {
	State     string   `json:"state"`
	Message   *Message `json:"message,omitempty"`
	Timestamp string   `json:"timestamp,omitempty"`
}

TaskStatus represents the current state of a task.

type TaskStatusUpdateEvent

type TaskStatusUpdateEvent struct {
	Kind   string     `json:"kind"` // "status-update"
	TaskID string     `json:"taskId"`
	Status TaskStatus `json:"status"`
	Final  bool       `json:"final"`
}

TaskStatusUpdateEvent is sent via SSE when a task's status changes.