a2a

package
v0.19.0 Latest Latest
Warning

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

 Go to latest Published: Jul 24, 2026 License: Apache-2.0 Imports: 32 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	LabelA2ATaskID     = "orloj.dev/a2a-task-id"
	LabelA2AContextID  = "orloj.dev/a2a-context-id"
	LabelA2AClient     = "orloj.dev/a2a-client"
	LabelA2ACancelled  = "orloj.dev/a2a-cancelled"
	LabelBlockedReason = "orloj.dev/blocked-reason"

	BlockedReasonA2AInput = "a2a-input-required"
	BlockedKindA2AInput   = "A2AInputRequest"
)

A2A label keys used on Orloj Tasks for A2A correlation.

View Source 
const (
	ErrCodeParse          = -32700
	ErrCodeInvalidRequest = -32600
	ErrCodeMethodNotFound = -32601
	ErrCodeInvalidParams  = -32602
	ErrCodeInternal       = -32603
	ErrCodeTaskNotFound   = -32001
	ErrCodeTaskCancelled  = -32002
	ErrCodeAgentNotFound  = -32003
)

Standard JSON-RPC error codes

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

A2A Task states

View Source 
const (
	MethodTaskSend      = "tasks/send"
	MethodTaskGet       = "tasks/get"
	MethodTaskCancel    = "tasks/cancel"
	MethodTaskSubscribe = "tasks/sendSubscribe"
)

A2A method names (current and legacy)

View Source 
const (
	LabelA2AMessageID       = "orloj.dev/a2a-message-id"
	LabelA2AProtocolVersion = "orloj.dev/a2a-protocol-version"
)

Variables

This section is empty.

Functions

func AgentCardSignatureKeyID added in v0.19.0 

func AgentCardSignatureKeyID(signature AgentCardSignature) (string, error)

AgentCardSignatureKeyID returns the protected JWS kid value.

func CreateOrlojTaskFromA2A 

func CreateOrlojTaskFromA2A(params TaskSendParams, system string, namespace string) resources.Task

CreateOrlojTaskFromA2A builds an Orloj Task from an A2A send request.

func CreateOrlojTaskFromV1 added in v0.19.0 

func CreateOrlojTaskFromV1(req *lf.SendMessageRequest, system, namespace string) (resources.Task, error)

CreateOrlojTaskFromV1 builds an Orloj task from a normative A2A v1 request. The A2A task and context IDs are generated server-side when omitted.

func IsTerminal 

func IsTerminal(state string) bool

IsTerminal returns true if the A2A state represents a terminal condition.

func IsV1Error added in v0.19.0 

func IsV1Error(err error) bool

IsV1Error reports whether err belongs to the normative A2A error taxonomy.

func LoadPEMCardPublicKey added in v0.19.0 

func LoadPEMCardPublicKey(path string) (crypto.PublicKey, error)

LoadPEMCardPublicKey loads a PKIX, PKCS#1 RSA, or certificate public key.

func MarshalV1Metadata added in v0.19.0 

func MarshalV1Metadata(value map[string]any) string

MarshalV1Metadata preserves arbitrary A2A metadata in string-only Orloj fields when an adapter needs to persist it.

func OrlojPhaseToA2AState 

func OrlojPhaseToA2AState(task resources.Task) string

OrlojPhaseToA2AState converts an Orloj Task phase to an A2A task state.

func OrlojPhaseToV1State added in v0.19.0 

func OrlojPhaseToV1State(task resources.Task) lf.TaskState

OrlojPhaseToV1State converts Orloj phases to A2A v1 enum values.

func OrlojTaskToV1 added in v0.19.0 

func OrlojTaskToV1(task resources.Task) *lf.Task

OrlojTaskToV1 converts an Orloj task to the normative A2A v1 task shape.

func V1MessageText added in v0.19.0 

func V1MessageText(message *lf.Message) (string, error)

V1MessageText converts a v1 message into Orloj's text task input.

Orloj currently advertises text/plain input. Rejecting other part types is preferable to silently dropping content that could affect the requested work.

func VerifyAgentCardSignature added in v0.19.0 

func VerifyAgentCardSignature(card AgentCard, signature AgentCardSignature, publicKey crypto.PublicKey) error

VerifyAgentCardSignature verifies one signature against a public key.

Types

type AgentCard 

type AgentCard struct {
	Name                 string                    `json:"name"`
	Description          string                    `json:"description"`
	URL                  string                    `json:"url,omitempty"`
	Version              string                    `json:"version"`
	ProtocolVersion      string                    `json:"protocolVersion,omitempty"`
	SupportedInterfaces  []AgentInterface          `json:"supportedInterfaces"`
	Capabilities         CardCapabilities          `json:"capabilities"`
	DefaultInputModes    []string                  `json:"defaultInputModes"`
	DefaultOutputModes   []string                  `json:"defaultOutputModes"`
	Skills               []CardSkill               `json:"skills"`
	Authentication       *CardAuth                 `json:"authentication,omitempty"`
	SecuritySchemes      map[string]map[string]any `json:"securitySchemes,omitempty"`
	SecurityRequirements []map[string][]string     `json:"securityRequirements,omitempty"`
	Signatures           []AgentCardSignature      `json:"signatures,omitempty"`
	Provider             *CardProvider             `json:"provider,omitempty"`
}

AgentCard represents an A2A Agent Card as defined by the A2A protocol.

func GenerateAgentCard 

func GenerateAgentCard(agent resources.Agent, tools []resources.Tool, config CardGeneratorConfig) AgentCard

GenerateAgentCard builds an A2A Agent Card from an Orloj Agent and its tools.

func GenerateSystemCard 

func GenerateSystemCard(system resources.AgentSystem, agents []resources.Agent, tools []resources.Tool, config CardGeneratorConfig) AgentCard

GenerateSystemCard builds a card from an AgentSystem. It aggregates skills from all agents in the system.

func SignAgentCard added in v0.19.0 

func SignAgentCard(card AgentCard, signer CardSigner) (AgentCard, error)

SignAgentCard returns a card with a newly appended signature. Existing signatures are excluded from the signed payload, as required by A2A.

func (AgentCard) EffectiveProtocolVersion added in v0.19.0 

func (c AgentCard) EffectiveProtocolVersion() string

EffectiveProtocolVersion returns the preferred interface version while retaining compatibility with cards that only carry the legacy top-level field.

func (AgentCard) PreferredInterface added in v0.19.0 

func (c AgentCard) PreferredInterface(binding, version string) (AgentInterface, bool)

PreferredInterface returns the first matching interface in server preference order. Empty binding or version values do not constrain selection.

type AgentCardSignature added in v0.19.0 

type AgentCardSignature struct {
	Protected string         `json:"protected"`
	Signature string         `json:"signature"`
	Header    map[string]any `json:"header,omitempty"`
}

type AgentInterface added in v0.19.0 

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

type CardAuth 

type CardAuth struct {
	Schemes []string `json:"schemes,omitempty"`
}

type CardCapabilities 

type CardCapabilities struct {
	Streaming         bool            `json:"streaming,omitempty"`
	PushNotifications bool            `json:"pushNotifications,omitempty"`
	ExtendedAgentCard bool            `json:"extendedAgentCard,omitempty"`
	StateTransitions  bool            `json:"stateTransitionHistory,omitempty"`
	Extensions        []CardExtension `json:"extensions,omitempty"`
}

type CardExtension added in v0.19.0 

type CardExtension struct {
	URI         string         `json:"uri,omitempty"`
	Description string         `json:"description,omitempty"`
	Required    bool           `json:"required,omitempty"`
	Params      map[string]any `json:"params,omitempty"`
}

type CardGeneratorConfig 

type CardGeneratorConfig struct {
	PublicBaseURL        string
	GRPCPublicURL        string
	ProtocolVersion      string
	AgentVersion         string
	StreamingEnabled     bool
	WebhooksEnabled      bool
	AuthSchemes          []string
	AdditionalInterfaces []AgentInterface
	Namespace            string
}

CardGeneratorConfig controls Agent Card generation.

type CardKeyResolver added in v0.19.0 

type CardKeyResolver func(context.Context, string) (crypto.PublicKey, error)

CardKeyResolver resolves a trusted public key for a protected JWS kid.

type CardProvider 

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

type CardSigner added in v0.19.0 

type CardSigner interface {
	Sign(card AgentCard) (AgentCardSignature, error)
}

CardSigner signs the RFC 8785 canonical representation of an Agent Card using the detached-payload JWS form defined by the A2A specification.

func LoadPEMCardSigner added in v0.19.0 

func LoadPEMCardSigner(path, keyID string) (CardSigner, error)

LoadPEMCardSigner loads an RSA, P-256 ECDSA, or Ed25519 private key.

func NewPEMCardSigner added in v0.19.0 

func NewPEMCardSigner(data []byte, keyID string) (CardSigner, error)

NewPEMCardSigner creates a signer from PKCS#8, PKCS#1, or SEC1 PEM data.

type CardSkill 

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

type Client 

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

Client handles outbound A2A requests to remote agents.

func NewClient 

func NewClient(config ClientConfig) *Client

NewClient creates a new outbound A2A client with SSRF-safe HTTP.

func (*Client) CacheStatus 

func (c *Client) CacheStatus(agentURL string) (lastRefreshed time.Time, hasError bool)

CacheStatus returns info about a cached card entry for observability.

func (*Client) CancelTask 

func (c *Client) CancelTask(ctx context.Context, agentURL string, params TaskCancelParams, extraHeaders map[string]string) (TaskResult, error)

CancelTask cancels a task on a remote A2A agent.

func (*Client) FetchCard 

func (c *Client) FetchCard(ctx context.Context, agentURL string, extraHeaders map[string]string) (AgentCard, error)

FetchCard retrieves and caches a remote Agent Card. Optional extraHeaders are applied to the HTTP request (e.g. auth).

func (*Client) GetTask 

func (c *Client) GetTask(ctx context.Context, agentURL string, params TaskGetParams, extraHeaders map[string]string) (TaskResult, error)

GetTask retrieves a task status from a remote A2A agent.

func (*Client) SendTask 

func (c *Client) SendTask(ctx context.Context, agentURL string, params TaskSendParams, extraHeaders map[string]string) (TaskResult, error)

SendTask sends a task to a remote A2A agent via JSON-RPC.

type ClientConfig 

type ClientConfig struct {
	AllowPrivate       bool
	CardCacheTTL       time.Duration
	RequireSignedCards bool
	ResolveCardKey     CardKeyResolver
}

ClientConfig configures the outbound A2A client.

type JSONRPCError 

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

type JSONRPCRequest 

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

JSON-RPC types

type JSONRPCResponse 

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

type Registry 

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

Registry maintains a cache of remote A2A agent cards.

func NewRegistry 

func NewRegistry(client *Client, configs []RemoteAgentConfig, ttl time.Duration, logger *log.Logger) *Registry

NewRegistry creates a registry backed by static config.

func (*Registry) Get 

func (r *Registry) Get(name string) (RemoteAgentEntry, bool)

Get returns a specific remote agent entry by name.

func (*Registry) List 

func (r *Registry) List() []RemoteAgentEntry

List returns all registered remote agents with their cache status, sorted by name.

func (*Registry) Start 

func (r *Registry) Start(ctx context.Context)

Start begins periodic card refresh in the background. Safe to call multiple times.

func (*Registry) Stop 

func (r *Registry) Stop()

Stop signals the refresh loop to terminate. Safe to call multiple times.

type RegistryResponse 

type RegistryResponse struct {
	LocalAgents  []AgentCard        `json:"localAgents"`
	RemoteAgents []RemoteAgentEntry `json:"remoteAgents"`
}

RegistryResponse is the response for GET /v1/a2a/agents

type RemoteAgentConfig 

type RemoteAgentConfig struct {
	Name      string `json:"name" yaml:"name"`
	URL       string `json:"url" yaml:"url"`
	AuthType  string `json:"authType,omitempty" yaml:"authType,omitempty"`
	SecretRef string `json:"secretRef,omitempty" yaml:"secretRef,omitempty"`
}

RemoteAgentConfig defines a static remote agent entry from Helm/server config.

type RemoteAgentEntry 

type RemoteAgentEntry struct {
	Name            string     `json:"name"`
	URL             string     `json:"url"`
	ProtocolVersion string     `json:"protocolVersion,omitempty"`
	CacheStatus     string     `json:"cacheStatus,omitempty"`
	LastRefreshed   string     `json:"lastRefreshed,omitempty"`
	CacheTTL        string     `json:"cacheTTL,omitempty"`
	Error           string     `json:"error,omitempty"`
	Card            *AgentCard `json:"card,omitempty"`
}

RemoteAgentEntry represents a configured remote A2A agent in the registry.

type SafePushSender added in v0.19.0 

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

SafePushSender delivers A2A task events while enforcing Orloj's dial-time SSRF policy, including DNS rebinding protection.

func NewSafePushSender added in v0.19.0 

func NewSafePushSender(allowPrivate bool, timeout time.Duration) *SafePushSender

func (*SafePushSender) SendPush added in v0.19.0 

func (s *SafePushSender) SendPush(ctx context.Context, config *lf.PushConfig, event lf.Event) error

type TaskArtifact 

type TaskArtifact struct {
	Name        string     `json:"name,omitempty"`
	Description string     `json:"description,omitempty"`
	Parts       []TaskPart `json:"parts"`
	Index       int        `json:"index"`
}

type TaskArtifactEvent 

type TaskArtifactEvent struct {
	ID       string       `json:"id"`
	Artifact TaskArtifact `json:"artifact"`
}

type TaskCancelParams 

type TaskCancelParams struct {
	ID     string `json:"id"`
	Reason string `json:"reason,omitempty"`
}

type TaskGetParams 

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

type TaskMessage 

type TaskMessage struct {
	Role  string     `json:"role"`
	Parts []TaskPart `json:"parts"`
}

type TaskPart 

type TaskPart struct {
	Type     string         `json:"type"`
	Text     string         `json:"text,omitempty"`
	Data     any            `json:"data,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

type TaskResult 

type TaskResult struct {
	ID        string            `json:"id"`
	Status    TaskStatus        `json:"status"`
	Artifacts []TaskArtifact    `json:"artifacts,omitempty"`
	History   []TaskMessage     `json:"history,omitempty"`
	Metadata  map[string]string `json:"metadata,omitempty"`
}

func OrlojTaskToA2AResult 

func OrlojTaskToA2AResult(task resources.Task) TaskResult

OrlojTaskToA2AResult converts an Orloj Task to an A2A TaskResult.

type TaskSendParams 

type TaskSendParams struct {
	ID            string            `json:"id"`
	Message       TaskMessage       `json:"message"`
	Metadata      map[string]string `json:"metadata,omitempty"`
	HistoryLength *int              `json:"historyLength,omitempty"`
}

A2A Task types

type TaskStatus 

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

type TaskStatusEvent 

type TaskStatusEvent struct {
	ID     string     `json:"id"`
	Status TaskStatus `json:"status"`
	Final  bool       `json:"final,omitempty"`
}

SSE event types

type ToolRuntime 

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

ToolRuntime executes outbound A2A tool calls against remote agents.

func NewToolRuntime 

func NewToolRuntime(client *Client, registry agentruntime.ToolCapabilityRegistry, secrets agentruntime.SecretResolver) *ToolRuntime

NewToolRuntime creates an A2A tool runtime. If secrets is non-nil, auth injection for tools with spec.auth is enabled automatically.

func (*ToolRuntime) Call 

func (r *ToolRuntime) Call(ctx context.Context, tool string, input string) (string, error)

func (*ToolRuntime) WithNamespace 

func (r *ToolRuntime) WithNamespace(namespace string) agentruntime.ToolRuntime

WithNamespace returns a copy scoped to the given namespace.

func (*ToolRuntime) WithRegistry 

func (r *ToolRuntime) WithRegistry(registry agentruntime.ToolCapabilityRegistry) agentruntime.ToolRuntime

WithRegistry returns a copy scoped to the given registry.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.