agentclient

Documentation

Overview

Package agentclient is the agent side of the Agent Auth Protocol: a Go program (an agent runtime, a CLI, an MCP server) that holds a host key discovers a provider, registers agents, waits for the user's approval, and executes capabilities with short-lived, request-bound JWTs. It is the Go counterpart of better-auth's @auth/agent SDK, for the parts of the protocol plugin/agentauth serves, and Tools exposes it as MCP-style tools.

The client keeps no state of its own: the host key is the caller's, and Connect returns an Agent (its id, key and provider) for the caller to keep wherever it keeps secrets.

Index

• Constants
• Variables
• func SignAgentJWT(a Agent, now time.Time, aud, method, target string, body []byte) (string, error)
• type Agent
• type Client
  • func New(host Key, opts ...Option) *Client
  • func (c *Client) CIBAAuthorize(ctx context.Context, a Agent, loginHint, bindingMessage string, caps []string) (agentauth.CIBAAuthorizeResult, error)
  • func (c *Client) Connect(ctx context.Context, p Provider, in ConnectRequest) (Agent, agentauth.RegisterResult, error)
  • func (c *Client) DescribeCapability(ctx context.Context, p Provider, name string) (agentauth.CapabilityView, error)
  • func (c *Client) Disconnect(ctx context.Context, a Agent) error
  • func (c *Client) Discover(ctx context.Context, providerURL string) (Provider, error)
  • func (c *Client) Execute(ctx context.Context, a Agent, capability, location string, args map[string]any) (json.RawMessage, error)
  • func (c *Client) ListCapabilities(ctx context.Context, p Provider, a *Agent) (agentauth.CapabilityList, error)
  • func (c *Client) OptionErr() error
  • func (c *Client) RequestCapability(ctx context.Context, a Agent, caps []agentauth.CapabilityRequest, ...) (agentauth.RequestCapabilityResult, error)
  • func (c *Client) Status(ctx context.Context, a Agent) (agentauth.AgentStatusView, error)
  • func (c *Client) Tools(store Store) []Tool
  • func (c *Client) WaitForApproval(ctx context.Context, a Agent, interval time.Duration) (agentauth.AgentStatusView, error)
• type ConnectRequest
• type Error
  • func (e *Error) Error() string
• type Key
  • func KeyFrom(priv ed25519.PrivateKey) Key
  • func NewKey() (Key, error)
  • func (k Key) PrivateKey() ed25519.PrivateKey
• type MemoryStore
  • func (m *MemoryStore) LoadAgent(_ context.Context, id string) (Agent, error)
  • func (m *MemoryStore) SaveAgent(_ context.Context, a Agent) error
• type Option
  • func WithClock(now func() time.Time) Option
  • func WithHTTPClient(hc *http.Client) Option
  • func WithHostName(name string) Option
• type Provider
• type Store
• type Tool

Constants

const (
	ToolDiscoverProvider   = "discover_provider"
	ToolListCapabilities   = "list_capabilities"
	ToolDescribeCapability = "describe_capability"
	ToolConnectAgent       = "connect_agent"
	ToolAgentStatus        = "agent_status"
	ToolRequestCapability  = "request_capability"
	ToolExecuteCapability  = "execute_capability"
	ToolDisconnectAgent    = "disconnect_agent"
)

Tool names, better-auth's SDK tool names for what this client serves.

Variables

var ErrNoKey = errors.New("agentclient: the key has no private key")

ErrNoKey is a Key without its private half.

var ErrUnknownAgent = errors.New("agentclient: unknown agent_id; call connect_agent first")

ErrUnknownAgent is an agent id the Store does not hold.

Functions

func SignAgentJWT

func SignAgentJWT(a Agent, now time.Time, aud, method, target string, body []byte) (string, error)

SignAgentJWT signs an agent token for aud, bound to the request when method and target are set (htm, htu) and to its body when body is not nil (ath). It is what an app route that verifies agents with VerifyAgentRequest receives.

Types

type Agent

type Agent struct {
	ID       string
	HostID   string
	Key      Key
	Provider Provider
}

Agent is a registered agent: what the caller stores to act as it later.

type Client

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

Client talks to providers for one host.

func New

func New(host Key, opts ...Option) *Client

New builds a client for the host whose key is host.

func (*Client) CIBAAuthorize

func (c *Client) CIBAAuthorize(ctx context.Context, a Agent, loginHint, bindingMessage string, caps []string) (agentauth.CIBAAuthorizeResult, error)

CIBAAuthorize asks the user named by loginHint to approve the host's agent through CIBA.

func (*Client) Connect

func (c *Client) Connect(ctx context.Context, p Provider, in ConnectRequest) (Agent, agentauth.RegisterResult, error)

Connect registers a new agent with its own fresh key, better-auth's connectAgent. The result says whether the agent is active or waits for the user (its Approval); WaitForApproval waits.

func (*Client) DescribeCapability

func (c *Client) DescribeCapability(ctx context.Context, p Provider, name string) (agentauth.CapabilityView, error)

DescribeCapability returns one capability with its schemas.

func (*Client) Disconnect

func (c *Client) Disconnect(ctx context.Context, a Agent) error

Disconnect revokes the agent, better-auth's disconnectAgent.

func (*Client) Discover

func (c *Client) Discover(ctx context.Context, providerURL string) (Provider, error)

Discover reads the discovery document of the provider at providerURL (any URL on its origin).

func (*Client) Execute

func (c *Client) Execute(ctx context.Context, a Agent, capability, location string, args map[string]any) (json.RawMessage, error)

Execute runs a capability, better-auth's executeCapability. location is the capability's own Location, or "" for the provider's execute endpoint; the token's audience follows it. The capability's result is returned as the provider sent it.

func (*Client) ListCapabilities

func (c *Client) ListCapabilities(ctx context.Context, p Provider, a *Agent) (agentauth.CapabilityList, error)

ListCapabilities lists the provider's capabilities; with an agent, each says whether the agent holds it.

func (*Client) OptionErr

func (c *Client) OptionErr() error

OptionErr is every error the options recorded, such as auth.ErrNilOption naming an option given nil (WithClock(nil)). The client has no start-up check of its own, so every call that signs a token returns it.

func (*Client) RequestCapability

func (c *Client) RequestCapability(ctx context.Context, a Agent, caps []agentauth.CapabilityRequest, reason string, hints agentauth.ApprovalHints) (agentauth.RequestCapabilityResult, error)

RequestCapability asks for more capabilities for the agent.

func (*Client) Status

func (c *Client) Status(ctx context.Context, a Agent) (agentauth.AgentStatusView, error)

Status reads the agent's status with the host's key.

func (*Client) Tools

func (c *Client) Tools(store Store) []Tool

Tools returns the client's tools over store, better-auth's SDK tools for an MCP server: discover a provider, list and describe its capabilities, connect an agent, read its status, request more, execute, disconnect.

func (*Client) WaitForApproval

func (c *Client) WaitForApproval(ctx context.Context, a Agent, interval time.Duration) (agentauth.AgentStatusView, error)

WaitForApproval polls Status every interval (zero takes the provider's default of five seconds) until the agent is no longer pending or ctx ends.

type ConnectRequest

type ConnectRequest struct {
	Name         string
	Capabilities []agentauth.CapabilityRequest
	Mode         agentauth.Mode
	Reason       string
	agentauth.ApprovalHints
	ForceApproval bool
}

ConnectRequest is what Connect registers.

type Error

type Error struct {
	Status  int
	Code    string `json:"error"`
	Message string `json:"message"`
}

Error is a provider's protocol error answer.

func (*Error) Error

func (e *Error) Error() string

type Key

type Key struct {
	Public agentauth.PublicKey
	// contains filtered or unexported fields
}

Key is an Ed25519 key pair in the protocol's JWK form.

func KeyFrom

func KeyFrom(priv ed25519.PrivateKey) Key

KeyFrom wraps a stored Ed25519 private key.

func NewKey

func NewKey() (Key, error)

NewKey generates an Ed25519 key.

func (Key) PrivateKey

func (k Key) PrivateKey() ed25519.PrivateKey

PrivateKey is the key to store.

type MemoryStore

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

MemoryStore is a Store in memory, for a process that never restarts its agents. The zero value is ready.

func (*MemoryStore) LoadAgent

func (m *MemoryStore) LoadAgent(_ context.Context, id string) (Agent, error)

LoadAgent returns the agent with id.

func (*MemoryStore) SaveAgent

func (m *MemoryStore) SaveAgent(_ context.Context, a Agent) error

SaveAgent keeps a.

type Option

type Option func(*Client)

Option configures a Client.

func WithClock

func WithClock(now func() time.Time) Option

WithClock sets the time JWTs are issued at, for tests.

func WithHTTPClient

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient sends requests with hc instead of http.DefaultClient.

func WithHostName

func WithHostName(name string) Option

WithHostName names the host to the provider and to the approving user.

type Provider

type Provider = agentauth.Configuration

Provider is a provider's discovery document.

type Store

type Store interface {
	SaveAgent(ctx context.Context, a Agent) error
	// LoadAgent returns ErrUnknownAgent for an id it does not hold.
	LoadAgent(ctx context.Context, id string) (Agent, error)
}

Store keeps the agents the tools connect, by id: an agent's private key is a secret, so where it lives is the caller's decision.

type Tool

type Tool struct {
	Name        string
	Description string
	InputSchema json.RawMessage
	// Call runs the tool with its JSON arguments and returns a value for
	// the JSON encoder.
	Call func(ctx context.Context, args json.RawMessage) (any, error)
}

Tool is one MCP-style tool: a name, a description and a JSON Schema for its arguments, and the function that runs it. Register each with any MCP server library (its tool name, description and input schema, and a handler that passes the raw arguments to Call); the package depends on none.