Documentation
¶
Index ¶
- Constants
- func IsElicitationMessage(msg *conv.Message) bool
- func IsElicitationPending(msg *conv.Message) bool
- func IsPreamble(ev *StreamEventEnvelope) bool
- func ToolCallID(ev *StreamEventEnvelope) string
- func ToolName(ev *StreamEventEnvelope) string
- func ToolPhase(ev *StreamEventEnvelope) string
- func ToolPhaseFromEvent(ev *StreamEventEnvelope) string
- type AuthProvider
- type ChatTurnUpdate
- type Client
- func (c *Client) AuthBrowserSession(ctx context.Context) error
- func (c *Client) AuthLocalLogin(ctx context.Context, name string) error
- func (c *Client) AuthLogout(ctx context.Context) error
- func (c *Client) AuthMe(ctx context.Context) (map[string]interface{}, error)
- func (c *Client) AuthOAuthConfig(ctx context.Context) (*OAuthConfigResponse, error)
- func (c *Client) AuthOAuthInitiate(ctx context.Context) (*OAuthInitiateResponse, error)
- func (c *Client) AuthOOBLogin(ctx context.Context, configURL, secretsURL string, scopes []string) (*oauth2.Token, error)
- func (c *Client) AuthOOBSession(ctx context.Context, secretsURL string, scopes []string) error
- func (c *Client) AuthProviders(ctx context.Context) ([]AuthProvider, error)
- func (c *Client) AuthSessionExchange(ctx context.Context, idToken string) error
- func (c *Client) CreateConversation(ctx context.Context, req *CreateConversationRequest) (*CreateConversationResponse, error)
- func (c *Client) GetMessages(ctx context.Context, conversationID string, since string) (*conv.Conversation, error)
- func (c *Client) GetMessagesWithOptions(ctx context.Context, conversationID string, opts *GetMessagesOptions) (*conv.Conversation, error)
- func (c *Client) GetPayload(ctx context.Context, payloadID string) (*PayloadResponse, error)
- func (c *Client) ListConversations(ctx context.Context) ([]ConversationSummary, error)
- func (c *Client) ListPendingElicitations(ctx context.Context, conversationID string) ([]*Elicitation, error)
- func (c *Client) PollEvents(ctx context.Context, conversationID string, since string, include []string, ...) (*PollResponse, error)
- func (c *Client) PostAndStream(ctx context.Context, conversationID string, req *PostMessageRequest, ...) (string, <-chan *StreamEventEnvelope, <-chan error, error)
- func (c *Client) PostAndStreamConversation(ctx context.Context, conversationID string, req *PostMessageRequest) (string, <-chan ChatTurnUpdate, <-chan error, error)
- func (c *Client) PostMessage(ctx context.Context, conversationID string, req *PostMessageRequest) (*PostMessageResponse, error)
- func (c *Client) ResolveElicitation(ctx context.Context, conversationID, elicitationID, action string, ...) error
- func (c *Client) RunTool(ctx context.Context, conversationID string, req *ToolRunRequest) (ToolRunResponse, error)
- func (c *Client) StreamConversation(ctx context.Context, conversationID string, since string) (<-chan ChatTurnUpdate, <-chan error, error)
- func (c *Client) StreamEvents(ctx context.Context, conversationID string, since string, include []string) (<-chan *StreamEventEnvelope, <-chan error, error)
- func (c *Client) StreamEventsWithOptions(ctx context.Context, conversationID string, since string, include []string, ...) (<-chan *StreamEventEnvelope, <-chan error, error)
- func (c *Client) StreamTurnEvents(ctx context.Context, conversationID string, since string, include []string, ...) (<-chan *TurnEvent, <-chan error, error)
- func (c *Client) UploadAttachment(ctx context.Context, name string, r io.Reader) (*UploadResponse, error)
- type ConversationSummary
- type CreateConversationRequest
- type CreateConversationResponse
- type Elicitation
- type GetMessagesOptions
- type HTTPError
- type LocalLoginRequest
- type MessageBuffer
- type OAuthConfigResponse
- type OAuthInitiateResponse
- type OOBRequest
- type Option
- func WithCookieJar(jar http.CookieJar) Option
- func WithHTTPClient(hc *http.Client) Option
- func WithHeader(key, value string) Option
- func WithRequestHook(hook func(*http.Request) error) Option
- func WithResponseHook(hook func(*http.Response) error) Option
- func WithRetryPolicy(p RetryPolicy) Option
- func WithTimeout(d time.Duration) Option
- func WithTokenProvider(tp TokenProvider) Option
- type PayloadResponse
- type PollResponse
- type PostMessageRequest
- type PostMessageResponse
- type RetryPolicy
- type StreamEventEnvelope
- type StreamEventType
- type TokenProvider
- type ToolRunRequest
- type ToolRunResponse
- type TurnEvent
- type UploadResponse
- type UploadedAttachment
Constants ¶
const ( TurnEventDelta = "delta" TurnEventAssistant = "assistant_message" TurnEventInterim = "interim_message" TurnEventElicitation = "elicitation" TurnEventTool = "tool" )
Variables ¶
This section is empty.
Functions ¶
func IsElicitationMessage ¶
IsElicitationMessage reports whether a message carries an elicitation id.
func IsElicitationPending ¶
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 ¶
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 (*Client) AuthBrowserSession ¶
AuthBrowserSession performs browser OAuth (PKCE) on the client, then exchanges id_token for a session cookie.
func (*Client) AuthLocalLogin ¶
AuthLocalLogin sets a session cookie for local auth.
func (*Client) AuthLogout ¶
AuthLogout clears the current session.
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 ¶
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 ¶
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 ¶
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"`
}
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 ¶
GetMessagesOptions configures transcript fetch.
type LocalLoginRequest ¶
type LocalLoginRequest struct {
Name string `json:"name"`
}
LocalLoginRequest mirrors /v1/api/auth/local/login.
type MessageBuffer ¶
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 ¶
WithCookieJar sets the cookie jar on the HTTP client.
func WithHTTPClient ¶
WithHTTPClient supplies a custom HTTP client.
func WithHeader ¶
WithHeader sets a static header on all requests.
func WithRequestHook ¶
WithRequestHook adds a hook executed before every request is sent.
func WithResponseHook ¶
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 ¶
WithTimeout sets the HTTP client timeout.
func WithTokenProvider ¶
func WithTokenProvider(tp TokenProvider) Option
WithTokenProvider supplies a bearer token provider.
type PayloadResponse ¶
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 ¶
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.