Documentation
¶
Overview ¶
Package daguito is the official Go SDK for the Daguito conversational AI platform — text, voice, image, audio, document and video agent flows.
It mirrors the public surface of the Python and TypeScript SDKs:
- RunWebhook one-shot HTTP call to a flow.
- WebhookStreamSession long-lived WebSocket; streams tokens and events.
- UploadFile presigned upload for media attachments.
- KnowledgeSession HTTP client for KB ingest + search.
Every public function that performs I/O takes a context.Context as its first argument and honours cancellation. The wire protocol (routes, frame types, base_input shape, scope filter, media envelope) is identical to the Python and JS SDKs — they are interchangeable from the server's point of view.
Index ¶
- Variables
- type ClosedEvent
- type ErrorEvent
- type EventType
- type FlowCompletedEvent
- type FlowFailedEvent
- type IngestTextInput
- type IngestTextResult
- type KnowledgeSession
- type KnowledgeSessionOptions
- type MediaKind
- type NodeCompletedEvent
- type NodeEmitEvent
- type NodeFailedEvent
- type NodeStartedEvent
- type NodeTokenEvent
- type ReadyEvent
- type SearchHit
- type SearchInput
- type SearchResult
- type SendableMessage
- func FormResponseMessage(formID string, payload map[string]any) SendableMessage
- func ImageMultiMessage(imageURLs []string, text string) SendableMessage
- func ImageURLMessage(imageURL, text string) SendableMessage
- func MediaKeyMessage(kind MediaKind, mediaKey, mimeType string, sizeBytes int64, text string) SendableMessage
- func TextMessage(text string) SendableMessage
- type StreamEvent
- type ToolHandler
- type ToolProgressEvent
- type ToolProgressItem
- type ToolProgressResource
- type ToolProgressResult
- type ToolSpec
- type UploadInput
- type UploadResult
- type WebhookRunInput
- type WebhookRunResult
- type WebhookStreamOptions
- type WebhookStreamSession
- func (s *WebhookStreamSession) Close() error
- func (s *WebhookStreamSession) Connect(ctx context.Context) error
- func (s *WebhookStreamSession) Events() <-chan StreamEvent
- func (s *WebhookStreamSession) RegisterTool(spec ToolSpec, handler ToolHandler) error
- func (s *WebhookStreamSession) Send(ctx context.Context, msg SendableMessage, baseInput map[string]any) error
- func (s *WebhookStreamSession) SendRaw(ctx context.Context, frame map[string]any) error
Constants ¶
This section is empty.
Variables ¶
var ( // ErrInvalidToken is returned when a webhook or KB key is rejected. ErrInvalidToken = errors.New("daguito: invalid token") // ErrUploadFailed is returned when either the presign POST or the // follow-up PUT to object storage fails. ErrUploadFailed = errors.New("daguito: upload failed") // ErrKnowledge is returned for KB ingest/search failures. ErrKnowledge = errors.New("daguito: knowledge request failed") // ErrWebhook is returned when a one-shot webhook call fails (network or // non-2xx response). ErrWebhook = errors.New("daguito: webhook request failed") // ErrStream is returned for protocol-level streaming session errors. ErrStream = errors.New("daguito: stream session error") )
Sentinel errors. Use errors.Is to branch on the well-known failure modes.
Functions ¶
This section is empty.
Types ¶
type ClosedEvent ¶
ClosedEvent fires when the transport closes. Code/Reason are best-effort — some closures (peer drop, network) leave them empty.
type ErrorEvent ¶
type ErrorEvent struct {
Message string
}
ErrorEvent carries a protocol-level error (auth failure, malformed frame, etc.). It is not the same as NodeFailedEvent / FlowFailedEvent — those are flow-execution failures.
type EventType ¶
type EventType string
EventType is the wire-level event name for a StreamEvent. Mirrors the Python `StreamEvent` literal union.
const ( EventReady EventType = "ready" EventClosed EventType = "closed" EventNodeStarted EventType = "node.started" EventNodeToken EventType = "node.token" EventNodeCompleted EventType = "node.completed" EventNodeFailed EventType = "node.failed" EventNodeEmit EventType = "node.emit" EventFlowCompleted EventType = "flow.completed" EventFlowFailed EventType = "flow.failed" EventError EventType = "error" )
type FlowCompletedEvent ¶
FlowCompletedEvent fires when the engine finishes the run. ElapsedMs is measured client-side from session.started.
type FlowFailedEvent ¶
type FlowFailedEvent struct {
Error string
}
FlowFailedEvent fires when the engine errors out.
type IngestTextInput ¶
type IngestTextInput struct {
Text string
Metadata map[string]any
SourceID string // overrides DefaultSourceID when set
}
IngestTextInput is the input to KnowledgeSession.IngestText.
type IngestTextResult ¶
IngestTextResult is the response of a successful text-ingest.
type KnowledgeSession ¶
type KnowledgeSession struct {
// contains filtered or unexported fields
}
KnowledgeSession is an HTTP client for the Daguito KB ingest + search endpoints. It is safe to reuse across goroutines.
func NewKnowledgeSession ¶
func NewKnowledgeSession(opts KnowledgeSessionOptions) *KnowledgeSession
NewKnowledgeSession constructs a KB client. No I/O happens here.
func (*KnowledgeSession) IngestText ¶
func (s *KnowledgeSession) IngestText(ctx context.Context, in IngestTextInput) (*IngestTextResult, error)
IngestText ingests a text blob into the configured source. The server chunks, embeds, and indexes the text. Returns the chunk + token counts so the caller can audit cost.
func (*KnowledgeSession) Search ¶
func (s *KnowledgeSession) Search(ctx context.Context, in SearchInput) (*SearchResult, error)
Search runs a hybrid (BM25 + vector) search against the KB.
type KnowledgeSessionOptions ¶
type KnowledgeSessionOptions struct {
APIURL string
APIKey string // sk_dgt_... — kb:read / kb:write scoped key
DefaultSourceID string // optional default sourceId for IngestText
Timeout time.Duration
HTTPClient *http.Client
}
KnowledgeSessionOptions configures a KnowledgeSession.
type MediaKind ¶
type MediaKind string
MediaKind enumerates the message kinds that carry an uploaded attachment. The values match the canonical MessageKind enum in @daguito/core (packages/core/src/messages/kinds.ts).
type NodeCompletedEvent ¶
NodeCompletedEvent fires when a node finishes successfully. DurationMs is populated when the server reports it; Output may be any JSON-shaped value.
type NodeEmitEvent ¶
NodeEmitEvent carries custom telemetry. Kind discriminates the payload; common values: "tool_progress" (use ParseToolProgress), "intent", "agent.tool_call_started".
type NodeFailedEvent ¶
NodeFailedEvent fires when a node errors out.
type NodeStartedEvent ¶
type NodeStartedEvent struct {
NodeID string
}
NodeStartedEvent fires when the engine enters a flow node.
type NodeTokenEvent ¶
NodeTokenEvent carries a single LLM token (or the smallest unit the model streamed). Concatenate Text across consecutive events to reconstruct the full response.
type ReadyEvent ¶
type ReadyEvent struct {
WebhookID string
}
ReadyEvent fires after the WS upgrade and bearer-token auth succeed.
type SearchHit ¶
type SearchHit struct {
ID string
SourceID string
Content string
Score float64
Metadata map[string]any
}
SearchHit is a single chunk returned by the KB search.
type SearchInput ¶
type SearchInput struct {
Query string
TopK *int
SourceIDs []string
EnableRewrite *bool
EnableRerank *bool
EnableCache *bool
}
SearchInput is the input to KnowledgeSession.Search. Set pointers via the helper constructors below — the SDK omits nil pointers from the wire body so server defaults apply.
type SearchResult ¶
type SearchResult struct {
Hits []SearchHit
QueryOriginal string
QueryRewritten string
Raw map[string]any
}
SearchResult is the response of a KB search.
type SendableMessage ¶
type SendableMessage struct {
Kind string `json:"kind"`
Text string `json:"text,omitempty"`
ImageURL string `json:"image_url,omitempty"`
ImageURLs []string `json:"image_urls,omitempty"`
MediaKey string `json:"media_key,omitempty"`
MimeType string `json:"mime_type,omitempty"`
SizeBytes int64 `json:"size_bytes,omitempty"`
FormID string `json:"form_id,omitempty"`
Payload map[string]any `json:"payload,omitempty"`
}
SendableMessage is the wire shape accepted by WebhookStreamSession.Send. In TypeScript this is a discriminated union; in Go we model it as a struct with optional fields and a Kind tag. Use the helper constructors below — they fill the correct subset of fields for each kind.
Wire kinds:
- "text"
- "image" with ImageURL or MediaKey (pre-uploaded)
- "image-multi" with ImageURLs
- "audio" / "document" / "video" with MediaKey
- "form-response" with FormID + Payload
func FormResponseMessage ¶
func FormResponseMessage(formID string, payload map[string]any) SendableMessage
FormResponseMessage resumes a flow that paused on a form node.
func ImageMultiMessage ¶
func ImageMultiMessage(imageURLs []string, text string) SendableMessage
ImageMultiMessage attaches several public image URLs for comparison / multi-image prompts.
func ImageURLMessage ¶
func ImageURLMessage(imageURL, text string) SendableMessage
ImageURLMessage attaches a single public image URL. The flow's vision tool fetches it server-side — no upload happens here.
func MediaKeyMessage ¶
func MediaKeyMessage(kind MediaKind, mediaKey, mimeType string, sizeBytes int64, text string) SendableMessage
MediaKeyMessage attaches a previously uploaded media object identified by the key returned from UploadFile. kind is one of MediaKindImage, MediaKindAudio, MediaKindDocument, MediaKindVideo.
func TextMessage ¶
func TextMessage(text string) SendableMessage
TextMessage builds a plain text message.
type StreamEvent ¶
type StreamEvent struct {
Type EventType
Ready *ReadyEvent
Closed *ClosedEvent
NodeStarted *NodeStartedEvent
NodeToken *NodeTokenEvent
NodeCompleted *NodeCompletedEvent
NodeFailed *NodeFailedEvent
NodeEmit *NodeEmitEvent
FlowCompleted *FlowCompletedEvent
FlowFailed *FlowFailedEvent
Error *ErrorEvent
}
StreamEvent is the sum type delivered on WebhookStreamSession.Events(). The Type field selects which of the typed payload pointers is populated; at most one is non-nil. Switch on Type when handling, or use the helper accessor methods.
type ToolHandler ¶
ToolHandler runs locally when the agent invokes a registered tool. Return any JSON-serialisable value as the tool result. Return an error to surface a failure to the LLM.
type ToolProgressEvent ¶
type ToolProgressEvent struct {
Tool string
Stage string
Progress float64 // 0..1; -1 when not reported
Resource *ToolProgressResource
Result *ToolProgressResult
TraceID string
Attempt int
}
ToolProgressEvent is the typed view over a NodeEmitEvent whose Kind is "tool_progress". Returned by ParseToolProgress. Consumers compose the user-facing copy from (Tool, Stage, Resource, Result) via their own i18n layer — the SDK never localises strings.
func ParseToolProgress ¶
func ParseToolProgress(evt *NodeEmitEvent) *ToolProgressEvent
ParseToolProgress narrows a NodeEmitEvent into a ToolProgressEvent when Kind is "tool_progress". Returns nil otherwise so callers can use it as a discriminator inside their node.emit handler.
type ToolProgressItem ¶
ToolProgressItem is one hit in a search-like tool result.
type ToolProgressResource ¶
ToolProgressResource describes what a tool is operating on. Every field is optional — the server only fills what's relevant for the stage.
type ToolProgressResult ¶
type ToolProgressResult struct {
Summary string
Items []ToolProgressItem
}
ToolProgressResult carries the data the tool produced. Summary is the raw caption/transcript text for a single-resource tool; Items lists multiple hits for search-like tools.
type ToolSpec ¶
type ToolSpec struct {
Name string `json:"name"`
Description string `json:"description"`
Parameters map[string]any `json:"parameters"`
// TimeoutMS caps how long the SDK waits for the local handler before
// reporting a tool error back to the LLM. Defaults to 30s.
TimeoutMS int `json:"client_timeout_ms,omitempty"`
}
ToolSpec is the OpenAI-shaped declaration the LLM sees. Parameters is a JSON Schema fragment (typically `{"type":"object","properties":{...}}`).
type UploadInput ¶
type UploadInput struct {
APIURL string
WebhookID string
Token string
Kind MediaKind
Path string
Data []byte
Filename string
MimeType string
Timeout time.Duration // optional; defaults to 30s
// HTTPClient is an optional override. When nil, UploadFile uses
// http.DefaultClient.
HTTPClient *http.Client
}
UploadInput is the input to UploadFile. Exactly one of Path or Data must be set. When Data is provided, Filename is required (used for both the extension-based MIME fallback and the storage key suffix).
type UploadResult ¶
UploadResult is the output of a successful presign + PUT.
func UploadFile ¶
func UploadFile(ctx context.Context, input UploadInput) (*UploadResult, error)
UploadFile uploads a local file (or in-memory bytes) to Daguito object storage and returns the media_key. Hand the key to MediaKeyMessage on a subsequent WebhookStreamSession.Send.
The upload is a two-step dance: (1) POST /v1/webhooks/:id/upload to mint a presigned PUT URL, (2) PUT bytes straight to object storage. Bytes never stream through the Daguito API. The presigned signature embeds kind/mime/ size so a client cannot upload a different file than it announced.
type WebhookRunInput ¶
type WebhookRunInput struct {
APIURL string
Token string
Input map[string]any
Timeout time.Duration // optional; defaults to 90s
// HTTPClient is an optional override. When nil, RunWebhook uses
// http.DefaultClient with the configured timeout applied via context.
HTTPClient *http.Client
}
WebhookRunInput is the input to RunWebhook. ApiURL is the Daguito API root (e.g. https://api.daguito.com); Token is the raw sk_wh_... bearer.
type WebhookRunResult ¶
WebhookRunResult is the typed response of /h/:token. Output is the JSON value the flow produced — its shape is flow-dependent.
func RunWebhook ¶
func RunWebhook(ctx context.Context, input WebhookRunInput) (*WebhookRunResult, error)
RunWebhook fires a one-shot HTTP POST to /h/:token and returns the final flow output. Use WebhookStreamSession instead for token-by-token streaming.
The context controls both connection and read deadlines — cancel it to abort an in-flight request.
type WebhookStreamOptions ¶
type WebhookStreamOptions struct {
APIURL string
WebhookID string
Token string
// SessionKey is an optional caller-supplied id for resuming a session.
// When empty, the SDK mints a random one.
SessionKey string
// BaseInput is applied to every send when the caller doesn't pass one
// explicitly. Useful for static metadata (user_id, locale, …).
BaseInput map[string]any
// Scope is the server-enforced metadata filter for KB searches in this
// session. Only primitive values (string, int, float, bool) are
// forwarded — arrays/objects are silently dropped at the wire boundary.
// The LLM never sees these values; Daguito injects them at the tool
// boundary so a hallucinated id can't widen scope or leak across
// conversations.
Scope map[string]any
}
WebhookStreamOptions configures a WebhookStreamSession.
type WebhookStreamSession ¶
type WebhookStreamSession struct {
// contains filtered or unexported fields
}
WebhookStreamSession is a long-lived bidirectional session for streaming webhooks (WS /v1/webhooks/:id/stream).
Lifecycle:
s := NewWebhookStreamSession(opts)
if err := s.Connect(ctx); err != nil { ... }
defer s.Close()
for evt := range s.Events() {
switch evt.Type {
case EventNodeToken: ...
case EventFlowCompleted: return
}
}
All methods are safe for concurrent use. Events() is single-consumer — call it once per session.
func NewWebhookStreamSession ¶
func NewWebhookStreamSession(opts WebhookStreamOptions) *WebhookStreamSession
NewWebhookStreamSession constructs a session. No I/O happens here — call Connect to open the socket.
func (*WebhookStreamSession) Close ¶
func (s *WebhookStreamSession) Close() error
Close tears down the session. Safe to call multiple times.
func (*WebhookStreamSession) Connect ¶
func (s *WebhookStreamSession) Connect(ctx context.Context) error
Connect opens the WebSocket and runs the auth + session.start handshake. Subsequent calls are no-ops. The provided context governs only the dial; the long-lived recv loop runs until Close.
func (*WebhookStreamSession) Events ¶
func (s *WebhookStreamSession) Events() <-chan StreamEvent
Events returns the channel of typed StreamEvents. The channel is closed when the session ends (either Close was called or the server closed the socket). Range over it in a single goroutine.
func (*WebhookStreamSession) RegisterTool ¶
func (s *WebhookStreamSession) RegisterTool(spec ToolSpec, handler ToolHandler) error
RegisterTool registers a client-side function tool the LLM may invoke. The spec is auto-injected into base_input.client_tools on every send; when the server emits agent.tool_call_started for this tool, handler runs locally and its return value is fed back via a tool_result frame.
RegisterTool can be called before or after Connect. Registering twice with the same name replaces the previous handler.
func (*WebhookStreamSession) Send ¶
func (s *WebhookStreamSession) Send(ctx context.Context, msg SendableMessage, baseInput map[string]any) error
Send pushes a message into the active session. If the session has not completed its handshake yet, the message is queued and dispatched once session.started arrives — callers do not need to wait themselves.
baseInput overrides the session-level BaseInput for this single send. Pass nil to fall back to the session default.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
run_webhook
command
One-shot webhook example.
|
One-shot webhook example. |
|
stream_session
command
Streaming session example.
|
Streaming session example. |