a2a

package
v0.7.0 Latest Latest
Warning

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

 Go to latest Published: Aug 9, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package a2a implements the Agent-to-Agent (A2A) Protocol for agent discovery, authentication, and task delegation.

A2A enables AI agents to discover other agents, negotiate capabilities, and delegate tasks while maintaining accountability through delegation chains.

EXPERIMENTAL

This package implements a draft specification that is subject to change. The API may change in backwards-incompatible ways as the specification evolves.

Protocol Overview

A2A provides three main capabilities:

  • Discovery: Agents publish Agent Cards at well-known endpoints
  • Authentication: Agents authenticate using existing OAuth/SPIFFE infrastructure
  • Delegation: Agents can delegate tasks with constrained scopes

Agent Cards

Agents publish their capabilities via Agent Cards at /.well-known/agent.json: 

{
  "id": "code-review-agent",
  "name": "Code Review Agent",
  "version": "1.0.0",
  "capabilities": [
    {
      "id": "review-pr",
      "description": "Review pull request for issues",
      "input_schema": {...},
      "output_schema": {...}
    }
  ],
  "authentication": {
    "type": "bearer",
    "token_endpoint": "https://auth.example.com/token"
  },
  "endpoints": {
    "invoke": "https://agent.example.com/invoke",
    "status": "https://agent.example.com/status/{task_id}"
  }
}

Task Delegation

When an orchestrator delegates to a specialist:

  1. Orchestrator discovers specialist via Agent Card
  2. Orchestrator requests delegation token from auth server
  3. Delegation token contains full actor chain: user -> orchestrator -> specialist
  4. Specialist uses delegation token to access resources
  5. Resource server logs complete delegation chain for audit

References

Index

Constants

View Source 
const WellKnownPath = "/.well-known/agent.json"

WellKnownPath is the standard path for agent cards.

Variables

View Source 
var (
	// ErrAgentNotFound indicates the agent card was not found.
	ErrAgentNotFound = errors.New("agent not found")

	// ErrCapabilityNotFound indicates the capability was not found.
	ErrCapabilityNotFound = errors.New("capability not found")

	// ErrTaskNotFound indicates the task was not found.
	ErrTaskNotFound = errors.New("task not found")

	// ErrUnauthorized indicates authentication failed.
	ErrUnauthorized = errors.New("unauthorized")

	// ErrForbidden indicates the agent lacks required permissions.
	ErrForbidden = errors.New("forbidden")

	// ErrRateLimited indicates rate limit exceeded.
	ErrRateLimited = errors.New("rate limited")
)

Common errors.

Functions

func HasCapability 

func HasCapability(card *AgentCard, capabilityID string) bool

HasCapability checks if an agent card has a specific capability.

func SupportsAuthentication 

func SupportsAuthentication(card *AgentCard, authType string) bool

SupportsAuthentication checks if the agent supports a specific auth type.

Types

type AgentCard 

type AgentCard struct {
	// ID is the unique identifier for the agent.
	ID string `json:"id"`

	// Name is the human-readable agent name.
	Name string `json:"name"`

	// Description describes the agent's purpose.
	Description string `json:"description,omitempty"`

	// Version is the agent version.
	Version string `json:"version,omitempty"`

	// Capabilities lists what the agent can do.
	Capabilities []Capability `json:"capabilities,omitempty"`

	// Authentication describes how to authenticate to this agent.
	Authentication *Authentication `json:"authentication,omitempty"`

	// Endpoints contains the agent's API endpoints.
	Endpoints *Endpoints `json:"endpoints,omitempty"`

	// Provider identifies the organization providing the agent.
	Provider *Provider `json:"provider,omitempty"`

	// TrustDomain is the SPIFFE trust domain for the agent.
	TrustDomain string `json:"trust_domain,omitempty"`

	// Metadata contains additional agent metadata.
	Metadata map[string]any `json:"metadata,omitempty"`
}

AgentCard describes an agent's capabilities and endpoints. Published at /.well-known/agent.json

type Authentication 

type Authentication struct {
	// Type is the authentication type: "bearer", "mtls", "none".
	Type string `json:"type"`

	// TokenEndpoint is the OAuth token endpoint for bearer auth.
	TokenEndpoint string `json:"token_endpoint,omitempty"`

	// Scopes lists available OAuth scopes.
	Scopes []string `json:"scopes,omitempty"`

	// TrustBundle is the SPIFFE trust bundle URL for mTLS.
	TrustBundle string `json:"trust_bundle,omitempty"`
}

Authentication describes how to authenticate to the agent.

type Capability 

type Capability struct {
	// ID is the unique identifier for the capability.
	ID string `json:"id"`

	// Name is the human-readable capability name.
	Name string `json:"name,omitempty"`

	// Description describes what this capability does.
	Description string `json:"description,omitempty"`

	// InputSchema is the JSON Schema for capability inputs.
	InputSchema json.RawMessage `json:"input_schema,omitempty"`

	// OutputSchema is the JSON Schema for capability outputs.
	OutputSchema json.RawMessage `json:"output_schema,omitempty"`

	// RequiredScopes lists OAuth scopes needed to invoke this capability.
	RequiredScopes []string `json:"required_scopes,omitempty"`

	// RateLimit describes rate limiting for this capability.
	RateLimit *RateLimit `json:"rate_limit,omitempty"`
}

Capability describes something an agent can do.

func GetCapability 

func GetCapability(card *AgentCard, capabilityID string) *Capability

GetCapability returns a capability by ID, or nil if not found.

type Client 

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

Client invokes agent capabilities.

func NewClient 

func NewClient(card *AgentCard, opts ...ClientOption) (*Client, error)

NewClient creates a new A2A client for the given agent.

func (*Client) AgentCard 

func (c *Client) AgentCard() *AgentCard

AgentCard returns the agent card this client is configured for.

func (*Client) Cancel 

func (c *Client) Cancel(ctx context.Context, taskID string) error

Cancel cancels a running task.

func (*Client) GetStatus 

func (c *Client) GetStatus(ctx context.Context, taskID string) (*TaskStatusResponse, error)

GetStatus checks the status of a task.

func (*Client) Invoke 

func (c *Client) Invoke(ctx context.Context, req *TaskRequest) (*TaskResponse, error)

Invoke invokes an agent capability.

func (*Client) InvokeAndWait 

func (c *Client) InvokeAndWait(ctx context.Context, req *TaskRequest, pollInterval time.Duration) (*TaskStatusResponse, error)

InvokeAndWait invokes a capability and waits for completion.

type ClientOption 

type ClientOption func(*Client)

ClientOption configures the Client.

func WithClientBearerToken 

func WithClientBearerToken(token string) ClientOption

WithClientBearerToken sets a bearer token for authentication.

func WithClientHTTPClient 

func WithClientHTTPClient(client *http.Client) ClientOption

WithClientHTTPClient sets a custom HTTP client.

func WithClientHeader 

func WithClientHeader(key, value string) ClientOption

WithClientHeader adds a custom header.

func WithDelegationToken 

func WithDelegationToken(token *DelegationToken) ClientOption

WithDelegationToken sets a delegation token for agent-to-agent calls.

type DelegationRequest 

type DelegationRequest struct {
	// DelegateTo is the ID of the agent to delegate to.
	DelegateTo string `json:"delegate_to"`

	// CapabilityID is the capability being delegated.
	CapabilityID string `json:"capability_id"`

	// Scope is the constrained scope for the delegation.
	Scope string `json:"scope"`

	// Constraints are additional delegation constraints.
	Constraints []string `json:"constraints,omitempty"`

	// ExpiresIn is how long the delegation is valid (seconds).
	ExpiresIn int `json:"expires_in,omitempty"`
}

DelegationRequest is used when an orchestrator delegates to another agent.

type DelegationToken 

type DelegationToken struct {
	// Token is the delegation token value.
	Token string `json:"token"`

	// TokenType is the token type (typically "Bearer").
	TokenType string `json:"token_type"`

	// ExpiresIn is the token lifetime in seconds.
	ExpiresIn int `json:"expires_in,omitempty"`

	// Scope is the delegated scope.
	Scope string `json:"scope,omitempty"`

	// ActorChain contains the delegation chain.
	// Format: ["user:alice", "agent:orchestrator", "agent:specialist"]
	ActorChain []string `json:"actor_chain,omitempty"`
}

DelegationToken represents a delegation token for agent-to-agent calls.

type DiscoveryClient 

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

DiscoveryClient discovers agents via their Agent Cards.

func NewDiscoveryClient 

func NewDiscoveryClient(opts ...DiscoveryOption) *DiscoveryClient

NewDiscoveryClient creates a new agent discovery client.

func (*DiscoveryClient) DiscoverAgent 

func (c *DiscoveryClient) DiscoverAgent(ctx context.Context, baseURL string) (*AgentCard, error)

DiscoverAgent fetches an Agent Card from the given base URL. The URL should be the agent's base URL (e.g., "https://agent.example.com"). The client will fetch /.well-known/agent.json from this URL.

func (*DiscoveryClient) DiscoverAgentByURL 

func (c *DiscoveryClient) DiscoverAgentByURL(ctx context.Context, url string) (*AgentCard, error)

DiscoverAgentByURL fetches an Agent Card from a full URL. Use this when you have the complete URL to the agent card.

type DiscoveryOption 

type DiscoveryOption func(*DiscoveryClient)

DiscoveryOption configures the DiscoveryClient.

func WithDiscoveryHTTPClient 

func WithDiscoveryHTTPClient(client *http.Client) DiscoveryOption

WithDiscoveryHTTPClient sets a custom HTTP client.

type Endpoints 

type Endpoints struct {
	// Invoke is the URL for invoking agent capabilities.
	Invoke string `json:"invoke,omitempty"`

	// Status is the URL template for checking task status.
	// May contain {task_id} placeholder.
	Status string `json:"status,omitempty"`

	// Cancel is the URL template for canceling tasks.
	Cancel string `json:"cancel,omitempty"`

	// Health is the URL for health checks.
	Health string `json:"health,omitempty"`
}

Endpoints contains the agent's API endpoints.

type LogEntry 

type LogEntry struct {
	// Timestamp is when the log entry was created.
	Timestamp string `json:"timestamp"`

	// Level is the log level (debug, info, warn, error).
	Level string `json:"level"`

	// Message is the log message.
	Message string `json:"message"`
}

LogEntry is a single log entry from task execution.

type Provider 

type Provider struct {
	// Name is the provider name.
	Name string `json:"name"`

	// URL is the provider's website.
	URL string `json:"url,omitempty"`
}

Provider identifies the organization providing the agent.

type RateLimit 

type RateLimit struct {
	// RequestsPerMinute is the maximum requests per minute.
	RequestsPerMinute int `json:"requests_per_minute,omitempty"`

	// RequestsPerHour is the maximum requests per hour.
	RequestsPerHour int `json:"requests_per_hour,omitempty"`
}

RateLimit describes rate limiting for a capability.

type TaskRequest 

type TaskRequest struct {
	// CapabilityID is the capability to invoke.
	CapabilityID string `json:"capability_id"`

	// Input is the capability input data.
	Input json.RawMessage `json:"input"`

	// CallbackURL is an optional URL for async result delivery.
	CallbackURL string `json:"callback_url,omitempty"`

	// Context contains additional request context.
	Context map[string]any `json:"context,omitempty"`
}

TaskRequest is the request body for invoking an agent capability.

type TaskResponse 

type TaskResponse struct {
	// TaskID is the unique identifier for the task.
	TaskID string `json:"task_id"`

	// Status is the task status.
	Status TaskStatus `json:"status"`

	// Output is the task output (if completed synchronously).
	Output json.RawMessage `json:"output,omitempty"`

	// Error is the error message (if failed).
	Error string `json:"error,omitempty"`

	// StatusURL is the URL to check task status.
	StatusURL string `json:"status_url,omitempty"`
}

TaskResponse is the response from invoking an agent.

type TaskStatus 

type TaskStatus string

TaskStatus represents the status of a task. 

const (
	TaskStatusPending   TaskStatus = "pending"
	TaskStatusRunning   TaskStatus = "running"
	TaskStatusCompleted TaskStatus = "completed"
	TaskStatusFailed    TaskStatus = "failed"
	TaskStatusCanceled  TaskStatus = "canceled"
)

Task status values.

func (TaskStatus) IsTerminal 

func (s TaskStatus) IsTerminal() bool

IsTerminal returns true if the status is terminal (completed, failed, canceled).

type TaskStatusResponse 

type TaskStatusResponse struct {
	// TaskID is the task identifier.
	TaskID string `json:"task_id"`

	// Status is the current task status.
	Status TaskStatus `json:"status"`

	// Progress is optional progress information (0-100).
	Progress *int `json:"progress,omitempty"`

	// Output is the task output (if completed).
	Output json.RawMessage `json:"output,omitempty"`

	// Error is the error message (if failed).
	Error string `json:"error,omitempty"`

	// Logs contains task execution logs.
	Logs []LogEntry `json:"logs,omitempty"`
}

TaskStatusResponse is the response from checking task status.

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.