sdk

package
v0.2.58 Latest Latest
Warning

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

Go to latest
Published: Feb 26, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Index

Constants

View Source
const (
	TurnEventDelta       = "delta"
	TurnEventAssistant   = "assistant_message"
	TurnEventInterim     = "interim_message"
	TurnEventElicitation = "elicitation"
	TurnEventTool        = "tool"
)

Variables

This section is empty.

Functions

func IsElicitationMessage

func IsElicitationMessage(msg *conv.Message) bool

IsElicitationMessage reports whether a message carries an elicitation id.

func IsElicitationPending

func IsElicitationPending(msg *conv.Message) bool

IsElicitationPending reports whether a message is an active elicitation. Pending/open (or empty) status is considered active.

func IsPreamble

func IsPreamble(ev *StreamEventEnvelope) bool

IsPreamble reports whether the event carries a preamble marker.

func ToolCallID

func ToolCallID(ev *StreamEventEnvelope) string

ToolCallID returns the tool call id from content when present.

func ToolName

func ToolName(ev *StreamEventEnvelope) string

ToolName returns the tool name from content when present.

func ToolPhase

func ToolPhase(ev *StreamEventEnvelope) string

ToolPhase returns "request" or "response" when present.

func ToolPhaseFromEvent

func ToolPhaseFromEvent(ev *StreamEventEnvelope) string

ToolPhaseFromEvent maps SSE event names to tool phases when the tool call payload is embedded in the message rather than content metadata.

Types

type AuthProvider

type AuthProvider struct {
	Name  string `json:"name"`
	Label string `json:"label"`
	Mode  string `json:"mode"`
}

AuthProvider mirrors /v1/api/auth/providers.

type ChatTurnUpdate

type ChatTurnUpdate struct {
	MessageID string
	Text      string
	IsFinal   bool
}

ChatTurnUpdate carries merged output for a message.

type Client

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

Client is a minimal HTTP SDK for Agently REST APIs.

func New

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

New constructs a new SDK client.

func (*Client) AuthBrowserSession

func (c *Client) AuthBrowserSession(ctx context.Context) error

AuthBrowserSession performs browser OAuth (PKCE) on the client, then exchanges id_token for a session cookie.

func (*Client) AuthLocalLogin

func (c *Client) AuthLocalLogin(ctx context.Context, name string) error

AuthLocalLogin sets a session cookie for local auth.

func (*Client) AuthLogout

func (c *Client) AuthLogout(ctx context.Context) error

AuthLogout clears the current session.

func (*Client) AuthMe

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

AuthMe returns the current user profile (cookie or bearer).

func (*Client) AuthOAuthConfig

func (c *Client) AuthOAuthConfig(ctx context.Context) (*OAuthConfigResponse, error)

AuthOAuthConfig fetches server OAuth config (ConfigURL and scopes).

func (*Client) AuthOAuthInitiate

func (c *Client) AuthOAuthInitiate(ctx context.Context) (*OAuthInitiateResponse, error)

AuthOAuthInitiate returns an auth URL for BFF OAuth flows.

func (*Client) AuthOOBLogin

func (c *Client) AuthOOBLogin(ctx context.Context, configURL, secretsURL string, scopes []string) (*oauth2.Token, error)

AuthOOBLogin performs an out-of-band OAuth login using scy and installs a token provider. It prefers id_token when available; otherwise it falls back to access_token. The provider refreshes the token when expired if a refresh token is present.

func (*Client) AuthOOBSession

func (c *Client) AuthOOBSession(ctx context.Context, secretsURL string, scopes []string) error

AuthOOBSession performs server-side OOB login and establishes a session cookie. It requires a BFF-capable server with /v1/api/auth/oob enabled.

func (*Client) AuthProviders

func (c *Client) AuthProviders(ctx context.Context) ([]AuthProvider, error)

AuthProviders lists configured auth providers.

func (*Client) AuthSessionExchange

func (c *Client) AuthSessionExchange(ctx context.Context, idToken string) error

AuthSessionExchange posts a bearer id_token to /v1/api/auth/session and expects a session cookie.

func (*Client) CreateConversation

func (c *Client) CreateConversation(ctx context.Context, req *CreateConversationRequest) (*CreateConversationResponse, error)

CreateConversation creates a new conversation.

func (*Client) GetMessages

func (c *Client) GetMessages(ctx context.Context, conversationID string, since string) (*conv.Conversation, error)

GetMessages fetches a conversation transcript via GET /messages.

func (*Client) GetMessagesWithOptions

func (c *Client) GetMessagesWithOptions(ctx context.Context, conversationID string, opts *GetMessagesOptions) (*conv.Conversation, error)

GetMessagesWithOptions fetches messages with extended query options.

func (*Client) GetPayload

func (c *Client) GetPayload(ctx context.Context, payloadID string) (*PayloadResponse, error)

GetPayload downloads a payload by id.

func (*Client) ListConversations

func (c *Client) ListConversations(ctx context.Context) ([]ConversationSummary, error)

ListConversations lists conversation summaries.

func (*Client) ListPendingElicitations

func (c *Client) ListPendingElicitations(ctx context.Context, conversationID string) ([]*Elicitation, error)

ListPendingElicitations scans the transcript and returns active elicitation requests.

func (*Client) PollEvents

func (c *Client) PollEvents(ctx context.Context, conversationID string, since string, include []string, wait time.Duration) (*PollResponse, error)

PollEvents long-polls /events with wait=ms and returns any events.

func (*Client) PostAndStream

func (c *Client) PostAndStream(ctx context.Context, conversationID string, req *PostMessageRequest, include []string) (string, <-chan *StreamEventEnvelope, <-chan error, error)

PostAndStream posts a message then streams events for the conversation. The caller should cancel ctx to stop the stream.

func (*Client) PostAndStreamConversation

func (c *Client) PostAndStreamConversation(ctx context.Context, conversationID string, req *PostMessageRequest) (string, <-chan ChatTurnUpdate, <-chan error, error)

PostAndStreamConversation posts a message and returns merged updates for assistant output.

func (*Client) PostMessage

func (c *Client) PostMessage(ctx context.Context, conversationID string, req *PostMessageRequest) (*PostMessageResponse, error)

PostMessage sends a message to a conversation and returns the message id.

func (*Client) ResolveElicitation

func (c *Client) ResolveElicitation(ctx context.Context, conversationID, elicitationID, action string, payload map[string]interface{}, reason string) error

ResolveElicitation posts an accept/decline action for an elicitation request.

func (*Client) RunTool

func (c *Client) RunTool(ctx context.Context, conversationID string, req *ToolRunRequest) (ToolRunResponse, error)

RunTool executes a tool in the context of a conversation.

func (*Client) StreamConversation

func (c *Client) StreamConversation(ctx context.Context, conversationID string, since string) (<-chan ChatTurnUpdate, <-chan error, error)

StreamConversation emits merged updates for assistant output, combining deltas and final messages.

func (*Client) StreamEvents

func (c *Client) StreamEvents(ctx context.Context, conversationID string, since string, include []string) (<-chan *StreamEventEnvelope, <-chan error, error)

StreamEvents opens an SSE stream to /events and emits envelopes and deltas. The caller should cancel ctx to stop the stream.

func (*Client) StreamEventsWithOptions

func (c *Client) StreamEventsWithOptions(ctx context.Context, conversationID string, since string, include []string, includeHistory bool) (<-chan *StreamEventEnvelope, <-chan error, error)

StreamEventsWithOptions opens an SSE stream with additional query options.

func (*Client) StreamTurnEvents

func (c *Client) StreamTurnEvents(ctx context.Context, conversationID string, since string, include []string, includeHistory bool) (<-chan *TurnEvent, <-chan error, error)

StreamTurnEvents wraps StreamEventsWithOptions and emits normalized events. It only returns assistant deltas, tool events, and elicitation events.

func (*Client) UploadAttachment

func (c *Client) UploadAttachment(ctx context.Context, name string, r io.Reader) (*UploadResponse, error)

UploadAttachment uploads a file to /upload and returns its staging descriptor.

type ConversationSummary

type ConversationSummary struct {
	ID         string   `json:"id"`
	Title      string   `json:"title"`
	Summary    *string  `json:"summary,omitempty"`
	Visibility string   `json:"visibility,omitempty"`
	Agent      string   `json:"agent,omitempty"`
	Model      string   `json:"model,omitempty"`
	Tools      []string `json:"tools,omitempty"`
}

ConversationSummary mirrors conversation list items.

type CreateConversationRequest

type CreateConversationRequest struct {
	Model      string `json:"model,omitempty"`
	Agent      string `json:"agent,omitempty"`
	Tools      string `json:"tools,omitempty"` // comma-separated
	Title      string `json:"title,omitempty"`
	Visibility string `json:"visibility,omitempty"`
	Shareable  bool   `json:"shareable,omitempty"`
}

CreateConversationRequest mirrors POST /v1/api/conversations.

type CreateConversationResponse

type CreateConversationResponse struct {
	ID        string `json:"id"`
	Title     string `json:"title"`
	CreatedAt string `json:"createdAt"`
	Model     string `json:"model,omitempty"`
	Agent     string `json:"agent,omitempty"`
	Tools     string `json:"tools,omitempty"`
}

CreateConversationResponse mirrors POST /v1/api/conversations response.

type Elicitation

type Elicitation struct {
	ConversationID string                 `json:"conversationId,omitempty"`
	MessageID      string                 `json:"messageId,omitempty"`
	ElicitationID  string                 `json:"elicitationId,omitempty"`
	Role           string                 `json:"role,omitempty"`
	Status         string                 `json:"status,omitempty"`
	CreatedAt      time.Time              `json:"createdAt,omitempty"`
	Content        string                 `json:"content,omitempty"`
	Request        map[string]interface{} `json:"request,omitempty"`
}

Elicitation represents a pending elicitation request surfaced by the API.

func ElicitationFromEvent

func ElicitationFromEvent(ev *StreamEventEnvelope) *Elicitation

ElicitationFromEvent returns a parsed elicitation from a stream event when present.

func ElicitationFromMessage

func ElicitationFromMessage(conversationID string, msg *conv.Message) *Elicitation

ElicitationFromMessage builds an Elicitation snapshot from a message.

type GetMessagesOptions

type GetMessagesOptions struct {
	Since                   string
	IncludeModelCallPayload bool
	IncludeLinked           bool
}

GetMessagesOptions configures transcript fetch.

type HTTPError

type HTTPError struct {
	StatusCode int
	Status     string
	Body       string
}

HTTPError wraps non-2xx responses.

func (*HTTPError) Error

func (e *HTTPError) Error() string

type LocalLoginRequest

type LocalLoginRequest struct {
	Name string `json:"name"`
}

LocalLoginRequest mirrors /v1/api/auth/local/login.

type MessageBuffer

type MessageBuffer struct {
	ByMessageID map[string]string
}

MessageBuffer accumulates assistant deltas and reconciles with final messages.

func NewMessageBuffer

func NewMessageBuffer() *MessageBuffer

NewMessageBuffer creates a message buffer for delta reconciliation.

func (*MessageBuffer) ApplyEvent

func (b *MessageBuffer) ApplyEvent(ev *StreamEventEnvelope) (string, string, bool)

ApplyEvent merges a stream envelope into the buffer. It returns the message id and current text when it changed.

func (*MessageBuffer) ReconcileFromTranscript

func (b *MessageBuffer) ReconcileFromTranscript(conv *conv.Conversation)

ReconcileFromTranscript replaces buffered text with final assistant messages.

type OAuthConfigResponse

type OAuthConfigResponse struct {
	ConfigURL string   `json:"configURL"`
	Scopes    []string `json:"scopes,omitempty"`
}

OAuthConfigResponse mirrors /v1/api/auth/oauth/config.

type OAuthInitiateResponse

type OAuthInitiateResponse struct {
	AuthURL string `json:"authURL"`
}

OAuthInitiateResponse mirrors /v1/api/auth/oauth/initiate.

type OOBRequest

type OOBRequest struct {
	SecretsURL string   `json:"secretsURL"`
	Scopes     []string `json:"scopes,omitempty"`
}

OOBRequest mirrors /v1/api/auth/oob request payload.

type Option

type Option func(c *Client)

Option customizes the SDK client.

func WithCookieJar

func WithCookieJar(jar http.CookieJar) Option

WithCookieJar sets the cookie jar on the HTTP client.

func WithHTTPClient

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient supplies a custom HTTP client.

func WithHeader

func WithHeader(key, value string) Option

WithHeader sets a static header on all requests.

func WithRequestHook

func WithRequestHook(hook func(*http.Request) error) Option

WithRequestHook adds a hook executed before every request is sent.

func WithResponseHook

func WithResponseHook(hook func(*http.Response) error) Option

WithResponseHook adds a hook executed after every response is received.

func WithRetryPolicy

func WithRetryPolicy(p RetryPolicy) Option

WithRetryPolicy sets a retry policy for requests.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the HTTP client timeout.

func WithTokenProvider

func WithTokenProvider(tp TokenProvider) Option

WithTokenProvider supplies a bearer token provider.

type PayloadResponse

type PayloadResponse struct {
	ContentType string
	Body        []byte
}

PayloadResponse wraps raw payload bytes and content type.

type PollResponse

type PollResponse struct {
	Events []*StreamEventEnvelope `json:"events"`
	Since  string                 `json:"since,omitempty"`
}

PollResponse is returned by long-poll events.

type PostMessageRequest

type PostMessageRequest struct {
	Content string                 `json:"content"`
	Agent   string                 `json:"agent,omitempty"`
	Model   string                 `json:"model,omitempty"`
	Tools   []string               `json:"tools,omitempty"`
	Context map[string]interface{} `json:"context,omitempty"`

	ToolCallExposure *string  `json:"toolCallExposure,omitempty"`
	AutoSummarize    *bool    `json:"autoSummarize,omitempty"`
	AutoSelectTools  *bool    `json:"autoSelectTools,omitempty"`
	DisableChains    bool     `json:"disableChains,omitempty"`
	AllowedChains    []string `json:"allowedChains,omitempty"`

	Attachments []UploadedAttachment `json:"attachments,omitempty"`
}

PostMessageRequest mirrors POST /v1/api/conversations/{id}/messages.

type PostMessageResponse

type PostMessageResponse struct {
	ID             string `json:"id"`
	TurnID         string `json:"turnId,omitempty"`
	ConversationID string `json:"conversationId,omitempty"`
}

PostMessageResponse is a minimal wrapper for message id.

type RetryPolicy

type RetryPolicy struct {
	MaxAttempts   int
	Delay         time.Duration
	RetryStatuses map[int]struct{}
	RetryMethods  map[string]struct{}
	RetryOnError  bool
}

RetryPolicy controls request retry behavior.

type StreamEventEnvelope

type StreamEventEnvelope struct {
	Seq            uint64                 `json:"seq"`
	Time           string                 `json:"time"`
	ConversationID string                 `json:"conversationId"`
	Message        *conv.Message          `json:"message"`
	ContentType    string                 `json:"contentType,omitempty"`
	Content        map[string]interface{} `json:"content,omitempty"`
	Event          StreamEventType        `json:"-"`
}

StreamEventEnvelope mirrors the server /events envelope.

type StreamEventType

type StreamEventType string
const (
	StreamEventMessage            StreamEventType = "message"
	StreamEventDelta              StreamEventType = "delta"
	StreamEventAssistantMessage   StreamEventType = "assistant_message"
	StreamEventInterimMessage     StreamEventType = "interim_message"
	StreamEventUserMessage        StreamEventType = "user_message"
	StreamEventToolCallStarted    StreamEventType = "tool_call_started"
	StreamEventToolCallCompleted  StreamEventType = "tool_call_completed"
	StreamEventToolCallFailed     StreamEventType = "tool_call_failed"
	StreamEventModelCallStarted   StreamEventType = "model_call_started"
	StreamEventModelCallCompleted StreamEventType = "model_call_completed"
	StreamEventModelCallFailed    StreamEventType = "model_call_failed"
	StreamEventAttachmentLinked   StreamEventType = "attachment_linked"
	StreamEventElicitation        StreamEventType = "elicitation"
	StreamEventError              StreamEventType = "error"
)

func (StreamEventType) IsAssistantMessage

func (e StreamEventType) IsAssistantMessage() bool

func (StreamEventType) IsDelta

func (e StreamEventType) IsDelta() bool

func (StreamEventType) IsElicitation

func (e StreamEventType) IsElicitation() bool

func (StreamEventType) IsInterimMessage

func (e StreamEventType) IsInterimMessage() bool

type TokenProvider

type TokenProvider func(ctx context.Context) (string, error)

TokenProvider returns a bearer token for the request.

type ToolRunRequest

type ToolRunRequest struct {
	Service string                 `json:"service"`
	Method  string                 `json:"method"`
	Args    map[string]interface{} `json:"args,omitempty"`
}

ToolRunRequest mirrors POST /v1/api/conversations/{id}/tools/run.

type ToolRunResponse

type ToolRunResponse map[string]interface{}

ToolRunResponse is a generic tool response payload.

type TurnEvent

type TurnEvent struct {
	Type           string
	ConversationID string
	TurnID         string
	MessageID      string
	Role           string
	MessageType    string
	CreatedAt      time.Time

	// Text holds the incremental delta for assistant output.
	// TextFull holds the reconstructed full text (best effort).
	Text     string
	TextFull string

	// Tool events (if present).
	ToolName  string
	ToolPhase string

	// Elicitation payload (if present).
	Elicitation *Elicitation
}

TurnEvent is a normalized SDK-level event emitted by StreamTurnEvents. It intentionally hides provider-specific payloads and focuses on conversation-visible semantics.

type UploadResponse

type UploadResponse struct {
	Name          string `json:"name"`
	Size          int64  `json:"size,omitempty"`
	URI           string `json:"uri"`
	StagingFolder string `json:"stagingFolder,omitempty"`
}

UploadResponse mirrors /upload response.

type UploadedAttachment

type UploadedAttachment struct {
	Name          string `json:"name"`
	Size          int    `json:"size,omitempty"`
	StagingFolder string `json:"stagingFolder,omitempty"`
	URI           string `json:"uri"`
	Mime          string `json:"mime,omitempty"`
}

UploadedAttachment mirrors staged upload descriptor for message attachments.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL