Documentation
¶
Overview ¶
Package a2aprovider exposes agents over the Agent2Agent (A2A) protocol, adapting A2A messages to and from the framework message model and including server and hosting support.
Index ¶
- func NewAgent(aclient *a2aclient.Client, config AgentConfig) *agent.Agent
- func NewAgentFromCard(ctx context.Context, card *a2a.AgentCard, config AgentConfig, ...) (*agent.Agent, error)
- func NewAgentFromResolver(ctx context.Context, resolver *agentcard.Resolver, baseURL string, ...) (*agent.Agent, error)
- func NewExecutor(hostedAgent *agent.Agent, cfg ExecutorConfig) a2asrv.AgentExecutor
- func NewHandler(hostedAgent *agent.Agent, cfg ExecutorConfig, ...) a2asrv.RequestHandler
- func NewIsolationKeyScopedTaskStore(inner taskstore.Store, config IsolationKeyScopedTaskStoreConfig) taskstore.Store
- func TaskIDFromSession(session *agent.Session) string
- func TaskStateFromSession(session *agent.Session) a2a.TaskState
- func WithConfiguration(configuration *a2a.SendMessageConfig) agent.Option
- func WithMetadata(metadata map[string]any) agent.Option
- func WithTaskID(taskID string) agent.Option
- type AgentConfig
- type AgentRunMode
- type ExecutorConfig
- type IsolationKeyScopedTaskStoreConfig
- type SessionStore
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func NewAgent ¶
func NewAgent(aclient *a2aclient.Client, config AgentConfig) *agent.Agent
NewAgent creates a new agent.Agent that delegates runs to a remote agent over the A2A (Agent-to-Agent) protocol via the a2a client. It panics if aclient is nil.
func NewAgentFromCard ¶ added in v0.1.1
func NewAgentFromCard(ctx context.Context, card *a2a.AgentCard, config AgentConfig, options ...a2aclient.FactoryOption) (*agent.Agent, error)
NewAgentFromCard creates an agent using the card's supported interfaces. Empty Name and Description fields in config default to the card's values; other agent configuration is preserved. Neither card nor config is modified. The card is assumed to be trusted; use NewAgentFromResolver for discovery. By default HTTP+JSON is preferred over JSON-RPC. Client options are applied after this default and can customize transports, HTTP clients and preferences. Transports must not require client destruction: this constructor does not expose the created client. For resource-owning transports, create the client with a2aclient.NewFromCard, pass it to NewAgent, and retain it for Destroy.
func NewAgentFromResolver ¶ added in v0.1.1
func NewAgentFromResolver(ctx context.Context, resolver *agentcard.Resolver, baseURL string, config AgentConfig, options ...a2aclient.FactoryOption) (*agent.Agent, error)
NewAgentFromResolver resolves the public agent card at baseURL and creates an agent using NewAgentFromCard. The resolver uses its own HTTP client to fetch the card; client options configure communication with the resolved agent, not discovery. Discovery and client creation errors are returned unchanged. The transport ownership requirements of NewAgentFromCard also apply here.
func NewExecutor ¶
func NewExecutor(hostedAgent *agent.Agent, cfg ExecutorConfig) a2asrv.AgentExecutor
NewExecutor creates a new a2asrv.AgentExecutor using the provided configuration.
For native request handling, use NewHandler, then wrap it with a2asrv.NewJSONRPCHandler or a2asrv.NewRESTHandler. Using a2asrv.NewHandler directly does not forward incoming send configuration or suppress executor errors after terminal status updates.
func NewHandler ¶ added in v0.1.1
func NewHandler(hostedAgent *agent.Agent, cfg ExecutorConfig, options ...a2asrv.RequestHandlerOption) a2asrv.RequestHandler
NewHandler creates a native A2A request handler for the hosted agent. It forwards incoming send configuration and preserves terminal task events on failures. Native options configure task storage, authentication and transport processing; the executor's session store remains independently configured.
func NewIsolationKeyScopedTaskStore ¶ added in v0.1.1
func NewIsolationKeyScopedTaskStore(inner taskstore.Store, config IsolationKeyScopedTaskStoreConfig) taskstore.Store
NewIsolationKeyScopedTaskStore partitions inner by a context-resolved isolation key. It panics if inner is nil. Task and context identifiers are scoped on writes and restored on reads, including typed identifiers in messages and events. Identifiers are always scoped, even if they already resemble scoped values. Absent optional message task and context identifiers remain empty. Create does not generate identifiers; callers supply native task objects.
The wrapper copies the objects and slices whose identifiers it changes; other payloads remain shared and read-only. It does not mutate caller-owned inputs or inner-owned results. Native ownership checks, versions, errors and context values are preserved; isolation does not replace authentication.
List scopes nonempty context filters and walks native pages until the requested page is filled with partition-local tasks or the results are exhausted. It uses native cursors without caching tasks or introducing another cursor format. PageSize reports the returned task count. TotalSize counts partition-local tasks matching the filters before pagination. Computing it requires enumerating all matching native pages on each call; only the requested visible page is retained. Native cursors can contain scoped identifiers; configure inner to conceal them if necessary. Concurrent writes retain the inner store's pagination semantics; the enumeration does not provide a snapshot across native pages. Supply the result to github.com/a2aproject/a2a-go/v2/a2asrv.WithTaskStore when constructing a native handler.
func TaskIDFromSession ¶
TaskIDFromSession returns the current A2A task ID stored in session state.
func TaskStateFromSession ¶ added in v0.1.1
TaskStateFromSession returns the last A2A task state stored in session state. It returns a2a.TaskStateUnspecified if the session is nil or has no task state.
func WithConfiguration ¶ added in v0.1.1
func WithConfiguration(configuration *a2a.SendMessageConfig) agent.Option
WithConfiguration supplies a read-only snapshot of the incoming A2A send configuration to a hosted-agent run. It does not enable background responses.
func WithMetadata ¶
WithMetadata sets A2A request-level metadata for a run. When hosting an agent, the executor supplies incoming request metadata through this option.
func WithTaskID ¶
WithTaskID sets the existing A2A task to resume when creating a session. Supply it to agent.Agent.CreateSession together with a nonblank agent.WithServiceID context ID.
Types ¶
type AgentConfig ¶
AgentConfig contains configuration for NewAgent.
type AgentRunMode ¶ added in v0.1.1
type AgentRunMode struct {
// contains filtered or unexported fields
}
AgentRunMode selects the response shape for a new hosted-agent request. The zero value returns a message. Modes can be copied; copying a dynamic mode retains its callback. Existing task continuations do not evaluate the mode.
func ReturnMessage ¶ added in v0.1.1
func ReturnMessage() AgentRunMode
ReturnMessage returns a mode that collects all streaming agent updates into one message, even for streaming or immediate-response requests.
func ReturnTask ¶ added in v0.1.1
func ReturnTask() AgentRunMode
ReturnTask returns a mode that produces a completed task for non-streaming requests unless an immediate response is requested. Streaming and immediate requests receive submitted, working, artifact, and terminal updates. Continuation tokens do not interrupt the stream.
func ReturnTaskWhen ¶ added in v0.1.1
func ReturnTaskWhen(decide func(context.Context, *a2asrv.ExecutorContext) (bool, error)) AgentRunMode
ReturnTaskWhen returns a mode whose callback selects a task (true) or message (false) for each new request. The callback receives the caller's context and a read-only executor context. It must support concurrent calls. Callback errors are returned without invoking the agent. Existing tasks do not invoke it. ReturnTaskWhen panics if decide is nil.
func (AgentRunMode) String ¶ added in v0.1.1
func (m AgentRunMode) String() string
String returns "message", "task", or "dynamic".
type ExecutorConfig ¶
type ExecutorConfig struct {
// SessionStore persists sessions by A2A context ID. Nil creates a private
// in-memory store for this executor. A supplied store must be scoped to the
// hosted agent and trusted caller identity before looking up context IDs.
SessionStore SessionStore
// AgentRunMode selects the shape of new responses. The zero value aggregates
// streaming agent updates into one message on both send endpoints, regardless
// of immediate-response configuration. Use [ReturnTaskWhen] for dynamic selection.
// Existing task continuations are unchanged.
AgentRunMode AgentRunMode
}
ExecutorConfig defines the configuration for NewExecutor.
type IsolationKeyScopedTaskStoreConfig ¶ added in v0.1.1
type IsolationKeyScopedTaskStoreConfig struct {
// ResolveKey resolves the isolation key for each operation. A nil resolver or
// an empty key means no key is available. Resolver errors are always returned.
// The resolver must be safe for concurrent calls and use a trusted identity,
// not an unvalidated client-supplied tenant or task identifier.
ResolveKey func(context.Context) (string, error)
// AllowUnscoped permits native, unpartitioned access when no key is available.
// The default is false: missing keys fail before accessing the inner store.
AllowUnscoped bool
}
IsolationKeyScopedTaskStoreConfig configures task-store partitioning.
type SessionStore ¶ added in v0.1.1
type SessionStore interface {
// Get retrieves a session, or returns (nil, nil) when contextID is not stored.
Get(ctx context.Context, contextID string) (*agent.Session, error)
// Save replaces the snapshot for contextID. session must be non-nil.
// The session must be serializable using encoding/json.
Save(ctx context.Context, contextID string, session *agent.Session) error
}
SessionStore persists hosted agent sessions by A2A context ID. A context ID is independent of agent.Session.ServiceID.
Implementations must support concurrent calls. Get must return an independently owned session, and Save must snapshot the session without retaining its pointer. The caller must not mutate a session concurrently with Save.
A store must be scoped to one hosted agent. Hosts serving multiple users or tenants must also isolate keys using trusted caller identity; context IDs alone are not an authorization boundary. A shared custom store must enforce these namespaces, for example by wrapping its keys using trusted context values.
func NewInMemorySessionStore ¶ added in v0.1.1
func NewInMemorySessionStore() SessionStore
NewInMemorySessionStore creates a concurrency-safe SessionStore that stores JSON snapshots in memory. Each Get returns a new session, including its provider-specific state and locally retained history.
Snapshots are lost when the store is discarded or the process exits. Concurrent saves to the same context ID replace one another; the last save wins. The store does not serialize entire agent runs or merge concurrent session branches.
Source Files