Documentation
¶
Overview ¶
Package a2a exposes the HTTP+JSON binding for the durable HumanAgent surface. Protocol DTOs and wire framing come from the official A2A Go SDK; task identity, state, idempotency, leases, and Artifacts remain owned by agent.Agent.
Index ¶
- Constants
- Variables
- func DecodeApplyArtifact(authority agent.AuthorityID, artifact *sdk.Artifact) (workspace.ApplyIntent, error)
- func NewHandler(config Config) (http.Handler, error)
- type AuthenticateFunc
- type AuthorizeApplyReceiptFunc
- type Config
- type Principal
- type RecordApplyReceiptRequest
- type RecordApplyReceiptResponse
- type ResolveWorkspaceFunc
- type Service
Constants ¶
const ApplyReceiptExtensionURI = "https://github.com/vibe-agi/human/extensions/apply-receipt/v1"
ApplyReceiptExtensionURI activates Human's authenticated caller-side CAS outcome endpoint. It is deliberately separate from the Workspace metadata extension: advertising Artifact identities does not authorize state changes.
const WorkspaceExtensionURI = "https://github.com/vibe-agi/human/extensions/workspace/v1"
WorkspaceExtensionURI identifies Human's Workspace/CAS metadata on A2A Task and Artifact values. It carries identities only; applying an Artifact still requires the separate durable caller-side CAS journal.
Variables ¶
var ErrInvalidApplyArtifact = errors.New("a2a: invalid Human workspace Artifact")
ErrInvalidApplyArtifact reports an Artifact or journal result that cannot be mapped to Human's exact caller-side apply protocol.
Functions ¶
func DecodeApplyArtifact ¶
func DecodeApplyArtifact(authority agent.AuthorityID, artifact *sdk.Artifact) (workspace.ApplyIntent, error)
DecodeApplyArtifact converts one negotiated Human workspace Artifact into the exact caller-side CAS intent. Authority must come from the caller's authenticated account configuration, never from Artifact metadata.
Human workspace Artifacts deliberately carry their payload as Raw even for text and JSON media types. That preserves the exact bytes bound by payloadDigest instead of normalizing whitespace, Unicode, or object order.
Types ¶
type AuthenticateFunc ¶
AuthenticateFunc authenticates one HTTP request before its A2A payload is decoded. Implementations may inspect TLS state, headers, host routing, or an embedding application's own session context. Non-anonymous requirements must be declared consistently in the public Agent Card's security contract. Return framework CodeUnauthenticated/CodeForbidden Faults with RetryNever for terminal rejection and CodeUnavailable with a retryable mode for dependency failure. The A2A SDK's unauthenticated/unauthorized sentinels are also recognized; every unclassified error fails closed as 503 without exposing its cause.
type AuthorizeApplyReceiptFunc ¶
type AuthorizeApplyReceiptFunc func(context.Context, Principal, agent.Task, *RecordApplyReceiptRequest) error
AuthorizeApplyReceiptFunc authorizes the caller-side CAS journal to report a terminal outcome for one published Artifact. A terminal denial must be a framework CodeUnauthenticated or CodeForbidden Fault with RetryNever. Every unavailable or unclassified error is projected as retryable service failure, never as a permanent denial; cause text is not exposed on the wire.
type Config ¶
type Config struct {
// Agent is the durable domain instance served by this handler.
Agent Service
// Card is snapshotted at construction and served at the standard well-known
// path. Its interfaces, security, extensions, skills, and MIME modes must
// describe the mounted handler and its workers truthfully.
Card *sdka2a.AgentCard
// Authenticate establishes the Authority/Subject for every non-Card request.
Authenticate AuthenticateFunc
// ResolveWorkspace selects the correctness scope for a new Task only.
ResolveWorkspace ResolveWorkspaceFunc
// AuthorizeApplyReceipt must be configured if and only if Card advertises
// ApplyReceiptExtensionURI.
AuthorizeApplyReceipt AuthorizeApplyReceiptFunc
// PollInterval controls durable event polling. Zero selects 250ms.
PollInterval time.Duration
// KeepAliveInterval enables SDK SSE keepalive comments when positive. Zero
// leaves keepalives disabled.
KeepAliveInterval time.Duration
// MaxRequestBytes bounds buffered request bodies. Zero selects 8 MiB.
MaxRequestBytes int64
}
Config composes the official A2A HTTP+JSON transport over an existing durable Agent. NewHandler does not take ownership of Agent and does not close it.
type Principal ¶
type Principal struct {
Authority agent.AuthorityID `json:"authority"`
Subject string `json:"subject"`
Attributes map[string]any `json:"attributes,omitempty"`
}
Principal is the authenticated identity from which every authority-scoped domain key is constructed. Tenant, message metadata, and other request-body fields must never be substituted for Authority.
type RecordApplyReceiptRequest ¶
type RecordApplyReceiptRequest struct {
CommandID string `json:"commandId"`
ReceiptID string `json:"receiptId"`
ArtifactID string `json:"artifactId"`
ArtifactDigest workspace.Digest `json:"artifactDigest"`
BaseRevision workspace.Revision `json:"baseRevision"`
ResultRevision workspace.Revision `json:"resultRevision"`
Decision workspace.ApplyDecision `json:"decision"`
ObservedRevision workspace.Revision `json:"observedRevision,omitempty"`
Code string `json:"code,omitempty"`
Message string `json:"message,omitempty"`
}
RecordApplyReceiptRequest is emitted only after the caller-side durable apply journal has reached a terminal outcome. Every identity is echoed so neither a retry nor a compromised UI can move a receipt to a different Artifact.
func NewApplyReceiptRequest ¶
func NewApplyReceiptRequest( commandID string, receiptID string, result workspace.ApplyResult, ) (RecordApplyReceiptRequest, error)
NewApplyReceiptRequest maps a terminal caller-side journal record to the authenticated A2A apply-receipt extension. commandID and receiptID are stable caller-generated idempotency identities and must be reused on HTTP retry.
type RecordApplyReceiptResponse ¶
type RecordApplyReceiptResponse struct {
ReceiptID string `json:"receiptId"`
ArtifactID string `json:"artifactId"`
ArtifactDigest workspace.Digest `json:"artifactDigest"`
BaseRevision workspace.Revision `json:"baseRevision"`
ResultRevision workspace.Revision `json:"resultRevision"`
Decision workspace.ApplyDecision `json:"decision"`
ObservedRevision workspace.Revision `json:"observedRevision,omitempty"`
Code string `json:"code,omitempty"`
Message string `json:"message,omitempty"`
RecordedAt time.Time `json:"recordedAt"`
}
type ResolveWorkspaceFunc ¶
type ResolveWorkspaceFunc func(context.Context, Principal, *sdka2a.SendMessageRequest) (agent.WorkspaceID, error)
ResolveWorkspaceFunc maps a new A2A task to an authenticated Workspace. It is called only for task creation; continuations resolve the already-committed task key and cannot move it to a different Workspace.
type Service ¶
type Service interface {
CreateTask(context.Context, agent.CreateTaskCommand) (agent.Task, error)
ReplyTask(context.Context, agent.MessageCommand) (agent.Task, error)
CancelTask(context.Context, agent.TaskCommand) (agent.Task, error)
ResolveTask(context.Context, agent.AuthorityID, agent.TaskID) (agent.TaskRef, error)
GetTask(context.Context, agent.TaskRef) (agent.Task, error)
GetMessage(context.Context, agent.AuthorityID, agent.MessageID) (agent.Message, error)
SnapshotTask(context.Context, agent.TaskRef) (agent.TaskSnapshot, error)
ListAuthorityTasks(context.Context, agent.AuthorityID, agent.TaskQuery) (agent.TaskQueryPage, error)
ListMessages(context.Context, agent.TaskRef, agent.PageRequest) (agent.MessagePage, error)
ReadEvents(context.Context, agent.TaskRef, agent.PageRequest) (agent.EventPage, error)
GetArtifact(context.Context, agent.ArtifactRef) (agent.ArtifactContent, error)
RecordApplyReceipt(context.Context, agent.RecordApplyReceiptCommand) (agent.ApplyReceipt, error)
}
Service is the transport-facing HumanAgent domain surface used by this A2A adapter. It intentionally contains no lifecycle or transport methods: NewHandler borrows the service, and another caller protocol can consume the same domain instance concurrently. Implementations must preserve the Agent package's idempotency, revision, event-cursor, Artifact, and receipt contracts; the official *agent.Agent is the reference implementation.
Source Files