client

Documentation

Index

• Constants
• type APIError
  • func (e *APIError) Error() string
• type ApprovalStatusResponse
• type Client
  • func New(baseURL string, opts ...Option) (*Client, error)
  • func (c *Client) AcknowledgeAction(ctx context.Context, nodeID string, payload types.ActionAckRequest) (*types.LeaseResponse, error)
  • func (c *Client) DID() string
  • func (c *Client) DIDAuthConfigured() bool
  • func (c *Client) GetApprovalStatus(ctx context.Context, nodeID, executionID string) (*ApprovalStatusResponse, error)
  • func (c *Client) GetNode(ctx context.Context, nodeID string) (map[string]interface{}, error)
  • func (c *Client) PostExecutionLogs(ctx context.Context, executionID string, payload any) error
  • func (c *Client) RegisterNode(ctx context.Context, payload types.NodeRegistrationRequest) (*types.NodeRegistrationResponse, error)
  • func (c *Client) RequestApproval(ctx context.Context, nodeID, executionID string, req RequestApprovalRequest) (*RequestApprovalResponse, error)
  • func (c *Client) SetDIDCredentials(did, privateKeyJWK string) error
  • func (c *Client) Shutdown(ctx context.Context, nodeID string, payload types.ShutdownRequest) (*types.LeaseResponse, error)
  • func (c *Client) SignBody(body []byte) map[string]string
  • func (c *Client) SignHTTPRequest(req *http.Request, body []byte)
  • func (c *Client) UpdateStatus(ctx context.Context, nodeID string, payload types.NodeStatusUpdate) (*types.LeaseResponse, error)
  • func (c *Client) WaitForApproval(ctx context.Context, nodeID, executionID string, opts *WaitForApprovalOptions) (*ApprovalStatusResponse, error)
• type DIDAuthenticator
  • func NewDIDAuthenticator(did string, privateKeyJWK string) (*DIDAuthenticator, error)
  • func (a *DIDAuthenticator) DID() string
  • func (a *DIDAuthenticator) IsConfigured() bool
  • func (a *DIDAuthenticator) SignRequest(body []byte) map[string]string
• type Option
  • func WithAPIKey(key string) Option
  • func WithBearerToken(token string) Option
  • func WithDIDAuth(did, privateKeyJWK string) Option
  • func WithHTTPClient(h *http.Client) Option
• type RequestApprovalRequest
• type RequestApprovalResponse
• type WaitForApprovalOptions

Constants

const (
	HeaderCallerDID    = "X-Caller-DID"
	HeaderDIDSignature = "X-DID-Signature"
	HeaderDIDTimestamp = "X-DID-Timestamp"
	HeaderDIDNonce     = "X-DID-Nonce"
)

DID Authentication header names

Types

type APIError

type APIError struct {
	StatusCode int
	Body       []byte
}

APIError captures non-success responses from the AgentField API.

func (*APIError) Error

func (e *APIError) Error() string

type ApprovalStatusResponse

type ApprovalStatusResponse struct {
	Status      string                 `json:"status"` // pending, approved, rejected, expired
	Response    map[string]interface{} `json:"response,omitempty"`
	RequestURL  string                 `json:"request_url,omitempty"`
	RequestedAt string                 `json:"requested_at,omitempty"`
	RespondedAt string                 `json:"responded_at,omitempty"`
}

ApprovalStatusResponse is returned by the approval status endpoint.

type Client

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

Client provides a thin wrapper over the AgentField control plane REST API.

func New

func New(baseURL string, opts ...Option) (*Client, error)

New creates a new Client instance.

func (*Client) AcknowledgeAction

func (c *Client) AcknowledgeAction(ctx context.Context, nodeID string, payload types.ActionAckRequest) (*types.LeaseResponse, error)

AcknowledgeAction notifies the control plane that a pushed action completed.

func (*Client) DID

func (c *Client) DID() string

DID returns the configured DID identifier, or empty string if not configured.

func (*Client) DIDAuthConfigured

func (c *Client) DIDAuthConfigured() bool

DIDAuthConfigured returns true if DID authentication is configured.

func (*Client) GetApprovalStatus

func (c *Client) GetApprovalStatus(ctx context.Context, nodeID, executionID string) (*ApprovalStatusResponse, error)

GetApprovalStatus returns the current approval status for an execution.

Calls GET /api/v1/agents/{nodeID}/executions/{executionID}/approval-status.

func (*Client) GetNode

func (c *Client) GetNode(ctx context.Context, nodeID string) (map[string]interface{}, error)

GetNode retrieves node information from the control plane.

func (*Client) PostExecutionLogs

func (c *Client) PostExecutionLogs(ctx context.Context, executionID string, payload any) error

PostExecutionLogs sends one structured execution log entry or a batch payload to the control plane execution-log ingestion API.

func (*Client) RegisterNode

func (c *Client) RegisterNode(ctx context.Context, payload types.NodeRegistrationRequest) (*types.NodeRegistrationResponse, error)

RegisterNode registers or updates the agent node with the control plane.

func (*Client) RequestApproval

func (c *Client) RequestApproval(ctx context.Context, nodeID, executionID string, req RequestApprovalRequest) (*RequestApprovalResponse, error)

RequestApproval requests human approval for an execution, transitioning it to the "waiting" state on the control plane.

Calls POST /api/v1/agents/{nodeID}/executions/{executionID}/request-approval.

func (*Client) SetDIDCredentials

func (c *Client) SetDIDCredentials(did, privateKeyJWK string) error

SetDIDCredentials configures DID authentication credentials after client creation. Returns an error if the credentials are invalid.

func (*Client) Shutdown

func (c *Client) Shutdown(ctx context.Context, nodeID string, payload types.ShutdownRequest) (*types.LeaseResponse, error)

Shutdown informs the control plane that the node is shutting down gracefully.

func (*Client) SignBody

func (c *Client) SignBody(body []byte) map[string]string

SignBody returns DID authentication headers for the given request body. Returns nil if DID auth is not configured. This is used by the DID client to sign VC generation and other authenticated requests.

func (*Client) SignHTTPRequest

func (c *Client) SignHTTPRequest(req *http.Request, body []byte)

SignHTTPRequest applies DID authentication headers to an existing HTTP request. This is useful for code paths that construct their own requests (e.g., execute calls) rather than going through the client's do() method. If DID auth is not configured, this is a no-op.

func (*Client) UpdateStatus

func (c *Client) UpdateStatus(ctx context.Context, nodeID string, payload types.NodeStatusUpdate) (*types.LeaseResponse, error)

UpdateStatus renews the node lease and optionally reports lifecycle changes.

func (*Client) WaitForApproval

func (c *Client) WaitForApproval(ctx context.Context, nodeID, executionID string, opts *WaitForApprovalOptions) (*ApprovalStatusResponse, error)

WaitForApproval polls the approval status endpoint with exponential backoff until the status is no longer "pending" or the context is cancelled.

type DIDAuthenticator

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

DIDAuthenticator handles DID authentication for agent requests.

func NewDIDAuthenticator

func NewDIDAuthenticator(did string, privateKeyJWK string) (*DIDAuthenticator, error)

NewDIDAuthenticator creates a new DID authenticator.

func (*DIDAuthenticator) DID

func (a *DIDAuthenticator) DID() string

DID returns the configured DID identifier.

func (*DIDAuthenticator) IsConfigured

func (a *DIDAuthenticator) IsConfigured() bool

IsConfigured returns true if DID authentication is configured.

func (*DIDAuthenticator) SignRequest

func (a *DIDAuthenticator) SignRequest(body []byte) map[string]string

SignRequest creates DID authentication headers for a request body.

type Option

type Option func(*Client)

Option mutates Client configuration.

func WithAPIKey

func WithAPIKey(key string) Option

WithAPIKey sets the X-API-Key header for each request.

func WithBearerToken

func WithBearerToken(token string) Option

WithBearerToken sets the Authorization header for each request.

func WithDIDAuth

func WithDIDAuth(did, privateKeyJWK string) Option

WithDIDAuth configures DID authentication for agent-to-agent calls. The did parameter should be the agent's DID identifier (e.g., "did:web:example.com:agents:my-agent"). The privateKeyJWK should be the JWK-formatted Ed25519 private key for signing.

func WithHTTPClient

func WithHTTPClient(h *http.Client) Option

WithHTTPClient allows custom HTTP transport configuration.

type RequestApprovalRequest

type RequestApprovalRequest struct {
	ApprovalRequestID  string `json:"approval_request_id"`
	ApprovalRequestURL string `json:"approval_request_url,omitempty"`
	CallbackURL        string `json:"callback_url,omitempty"`
	ExpiresInHours     int    `json:"expires_in_hours,omitempty"`
}

RequestApprovalRequest is the payload for requesting human approval.

type RequestApprovalResponse

type RequestApprovalResponse struct {
	ApprovalRequestID  string `json:"approval_request_id"`
	ApprovalRequestURL string `json:"approval_request_url"`
}

RequestApprovalResponse is returned after tracking an approval request.

type WaitForApprovalOptions

type WaitForApprovalOptions struct {
	// PollInterval is the initial polling interval (default: 5s).
	PollInterval time.Duration
	// MaxInterval is the maximum polling interval (default: 60s).
	MaxInterval time.Duration
	// BackoffFactor is the multiplier applied to the interval each iteration (default: 2).
	BackoffFactor float64
}

WaitForApprovalOptions configures the blocking WaitForApproval helper.