a2a

package
v0.7.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 17, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package a2a implements the A2A 1.0 JSON-RPC binding, agent cards and task storage without depending on a protocol SDK.

Index

Constants

View Source
const (
	MethodSendMessage          = "SendMessage"
	MethodSendStreamingMessage = "SendStreamingMessage"
	MethodGetTask              = "GetTask"
	MethodListTasks            = "ListTasks"
	MethodCancelTask           = "CancelTask"
	MethodSubscribeToTask      = "SubscribeToTask"
)

JSON-RPC 2.0 method names used by A2A 1.0.

View Source
const (
	CodeParseError     = -32700
	CodeInvalidRequest = -32600
	CodeMethodNotFound = -32601
	CodeInvalidParams  = -32602
	CodeInternalError  = -32603
)

JSON-RPC 2.0 error codes.

View Source
const (
	RoleUser  = "ROLE_USER"
	RoleAgent = "ROLE_AGENT"
)

Message roles defined by A2A 1.0.

View Source
const (
	StateSubmitted     = "TASK_STATE_SUBMITTED"
	StateWorking       = "TASK_STATE_WORKING"
	StateInputRequired = "TASK_STATE_INPUT_REQUIRED"
	StateCompleted     = "TASK_STATE_COMPLETED"
	StateCanceled      = "TASK_STATE_CANCELED"
	StateFailed        = "TASK_STATE_FAILED"
	StateRejected      = "TASK_STATE_REJECTED"
	StateAuthRequired  = "TASK_STATE_AUTH_REQUIRED"
)

Task states defined by A2A 1.0.

View Source
const ProtocolVersion = "1.0"

Variables

This section is empty.

Functions

func CanonicalMethod

func CanonicalMethod(method string) string

CanonicalMethod maps supported 0.3 slash names to their A2A 1.0 names.

func IsAgentRole

func IsAgentRole(role string) bool

IsAgentRole reports whether role is the A2A 1.0 agent role. The 0.3 form is accepted as well.

func IsUserRole

func IsUserRole(role string) bool

IsUserRole reports whether role is the A2A 1.0 user role. The 0.3 form is accepted as well.

func NormalizeRole

func NormalizeRole(role string) string

NormalizeRole maps A2A 0.3 lowercase roles and 1.0 enum values to the 1.0 wire form.

Types

type AgentCapabilities

type AgentCapabilities struct {
	Streaming         bool `json:"streaming"`
	PushNotifications bool `json:"pushNotifications"`
	ExtendedAgentCard bool `json:"extendedAgentCard,omitempty"`
}

AgentCapabilities declares optional A2A features.

type AgentCard

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

AgentCard is the discovery document published at the well-known path.

type AgentInterface

type AgentInterface struct {
	URL             string `json:"url"`
	ProtocolBinding string `json:"protocolBinding"`
	ProtocolVersion string `json:"protocolVersion"`
}

AgentInterface is one URL/transport/protocol combination.

type AgentProvider

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

AgentProvider identifies the operator of an agent.

type AgentSkill

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

AgentSkill describes one capability exposed by an agent.

type Artifact

type Artifact struct {
	ArtifactID string         `json:"artifactId"`
	Name       string         `json:"name,omitempty"`
	Parts      []Part         `json:"parts"`
	Metadata   map[string]any `json:"metadata,omitempty"`
}

Artifact is a result generated by a task.

type CancelTaskRequest

type CancelTaskRequest struct {
	ID       string         `json:"id"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

CancelTaskRequest cancels a running task.

type FilePart

type FilePart struct {
	Name     string `json:"name,omitempty"`
	MimeType string `json:"mimeType,omitempty"`
	Bytes    string `json:"bytes,omitempty"`
	URI      string `json:"uri,omitempty"`
}

FilePart is a file referenced by URI or supplied inline.

type GetTaskRequest

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

GetTaskRequest is the task lookup parameter object.

type ListTasksRequest

type ListTasksRequest struct {
	ContextID     string `json:"contextId,omitempty"`
	Status        string `json:"status,omitempty"`
	PageSize      int    `json:"pageSize,omitempty"`
	PageToken     string `json:"pageToken,omitempty"`
	HistoryLength *int   `json:"historyLength,omitempty"`
}

ListTasksRequest filters the task list.

type ListTasksResponse

type ListTasksResponse struct {
	Tasks         []*Task `json:"tasks"`
	TotalSize     int     `json:"totalSize"`
	PageSize      int     `json:"pageSize"`
	NextPageToken string  `json:"nextPageToken"`
}

ListTasksResponse is the result of tasks/list.

type Message

type Message struct {
	Kind             string         `json:"kind,omitempty"`
	MessageID        string         `json:"messageId"`
	ContextID        string         `json:"contextId,omitempty"`
	TaskID           string         `json:"taskId,omitempty"`
	Role             string         `json:"role"`
	Parts            []Part         `json:"parts"`
	Metadata         map[string]any `json:"metadata,omitempty"`
	ReferenceTaskIDs []string       `json:"referenceTaskIds,omitempty"`
}

Message is one A2A message.

func (Message) Text

func (m Message) Text() string

Text returns the concatenated text of all text parts.

type Part

type Part struct {
	Kind      string         `json:"kind,omitempty"`
	Text      string         `json:"text,omitempty"`
	File      *FilePart      `json:"file,omitempty"`
	Data      any            `json:"data,omitempty"`
	URL       string         `json:"url,omitempty"`
	Raw       []byte         `json:"raw,omitempty"`
	Filename  string         `json:"filename,omitempty"`
	MediaType string         `json:"mediaType,omitempty"`
	Metadata  map[string]any `json:"metadata,omitempty"`
}

Part is a text, file or structured-data message part. The kind field is accepted for A2A 0.3 compatibility; A2A 1.0 infers it from the set field.

func TextPart

func TextPart(text string) Part

TextPart builds a text part.

type RPCError

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

RPCError is a JSON-RPC error object.

func (*RPCError) Error

func (e *RPCError) Error() string

type Request

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

Request is one JSON-RPC request.

type Response

type Response struct {
	JSONRPC string          `json:"jsonrpc"`
	ID      json.RawMessage `json:"id"`
	Result  any             `json:"result,omitempty"`
	Error   *RPCError       `json:"error,omitempty"`
}

Response is one JSON-RPC response.

type SecurityScheme

type SecurityScheme struct {
	Type         string `json:"type"`
	Scheme       string `json:"scheme,omitempty"`
	BearerFormat string `json:"bearerFormat,omitempty"`
	Description  string `json:"description,omitempty"`
	Name         string `json:"name,omitempty"`
	In           string `json:"in,omitempty"`
}

SecurityScheme follows the OpenAPI security scheme object.

type SendMessageRequest

type SendMessageRequest struct {
	Message       *Message       `json:"message"`
	Configuration map[string]any `json:"configuration,omitempty"`
	Metadata      map[string]any `json:"metadata,omitempty"`
}

SendMessageRequest is the message/send and message/stream parameter object.

func (*SendMessageRequest) UnmarshalJSON

func (r *SendMessageRequest) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts both {"message":{...}} and a bare message object.

type Server

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

Server implements the A2A JSON-RPC binding and agent-card endpoints.

func New

func New(cfg *config.Config, runner *runtime.Runner, defaultAgent, version string, tokenEnabled bool) (*Server, error)

New creates an A2A server using the default task store.

func NewWithStore

func NewWithStore(cfg *config.Config, runner *runtime.Runner, defaultAgent, version string, tokenEnabled bool, store *Store) (*Server, error)

NewWithStore creates an A2A server with a specific task store.

func (*Server) CardHandler

func (s *Server) CardHandler(agentOverride string) http.Handler

CardHandler serves the agent card for agentOverride, or the default agent.

func (*Server) Handler

func (s *Server) Handler(agentOverride string) http.Handler

Handler returns the JSON-RPC endpoint for one agent. An empty override uses the default agent.

type Store

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

Store persists tasks as individual JSON files and keeps loaded tasks in memory for fast polling.

func NewStore

func NewStore(dir string) *Store

NewStore creates a task store under dir. An empty dir uses ~/.oni3/a2a/tasks.

func (*Store) Get

func (s *Store) Get(id string) (*Task, bool)

Get returns a task snapshot, loading it from disk when necessary.

func (*Store) List

func (s *Store) List(contextID, state string) []*Task

List returns tasks, newest first, filtered by context and state.

func (*Store) Save

func (s *Store) Save(task *Task) error

Save persists a snapshot of task. The caller must not mutate task while Save runs.

type StreamResponse

type StreamResponse struct {
	Task           *Task                    `json:"task,omitempty"`
	Message        *Message                 `json:"message,omitempty"`
	StatusUpdate   *TaskStatusUpdateEvent   `json:"statusUpdate,omitempty"`
	ArtifactUpdate *TaskArtifactUpdateEvent `json:"artifactUpdate,omitempty"`
}

StreamResponse wraps one event with the A2A 1.0 oneof field name.

type SubscribeToTaskRequest

type SubscribeToTaskRequest struct {
	ID string `json:"id"`
}

SubscribeToTaskRequest subscribes to future updates of a task.

type Task

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

Task is one stateful A2A operation.

type TaskArtifactUpdateEvent

type TaskArtifactUpdateEvent struct {
	Kind      string         `json:"kind,omitempty"`
	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 reports an artifact chunk.

type TaskStatus

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

TaskStatus is the current state plus an optional explanatory message.

type TaskStatusUpdateEvent

type TaskStatusUpdateEvent struct {
	Kind      string         `json:"kind,omitempty"`
	TaskID    string         `json:"taskId"`
	ContextID string         `json:"contextId"`
	Status    TaskStatus     `json:"status"`
	Final     bool           `json:"final,omitempty"`
	Metadata  map[string]any `json:"metadata,omitempty"`
}

TaskStatusUpdateEvent reports a state transition.

Directories

Path Synopsis
Package client implements the non-streaming A2A 1.0 JSON-RPC client.
Package client implements the non-streaming A2A 1.0 JSON-RPC client.
Package wire contains the A2A 1.0 wire types shared by the server and the non-streaming client.
Package wire contains the A2A 1.0 wire types shared by the server and the non-streaming client.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL