Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
package types
import (
"context"
"database/sql/driver"
"encoding/json"
"strings"
"time"
)
// DefaultMaxContextTokens is the context window assumed for a model that does
// not declare one. 200k matches typical windows on current chat/VLM models
// (GPT-4.1, Claude, Gemini, Qwen, etc.).
//
// It is still below the largest windows on the market. Guessing high is
// the dangerous direction: compaction never fires, and the first sign of
// trouble is the provider rejecting the request. Guessing low only costs some
// history that would have fit.
const DefaultMaxContextTokens = 200000
// AgentMaxContextTokens picks the context window for one agent run. An
// explicit agent setting wins, then whatever the model declares, then the
// assumed default.
func AgentMaxContextTokens(configured, modelContextWindow int) int {
if configured > 0 {
return configured
}
if modelContextWindow > 0 {
return modelContextWindow
}
return DefaultMaxContextTokens
}
// DefaultSmartReasoningMaxCompletionTokens is the per-round budget when the
// agent has no sandbox. Leave room for complete reports as well as tool calls.
const DefaultSmartReasoningMaxCompletionTokens = 24576
// DefaultAgentMaxCompletionTokens is the per-round budget when the agent
// can write or edit sandbox files. Those tool calls carry the file body in
// JSON; a 4096 cap truncates mid-stream (finish_reason=length).
const DefaultAgentMaxCompletionTokens = 24576
// DefaultQuickAnswerMaxCompletionTokens is the RAG answer budget.
const DefaultQuickAnswerMaxCompletionTokens = 2048
// NeedsSandboxWriteCompletionBudget reports whether this agent may register
// write_sandbox_file / edit_sandbox_file. Those tools follow the bound
// sandbox, not the allowed_tools checklist.
func NeedsSandboxWriteCompletionBudget(sandboxConfigID string) bool {
return strings.TrimSpace(sandboxConfigID) != ""
}
// DefaultMaxCompletionTokens is the unset-config default for one agent:
// quick-answer 2048, smart-reasoning 24576 with or without a sandbox.
func DefaultMaxCompletionTokens(agentMode, sandboxConfigID string) int {
if agentMode == AgentModeSmartReasoning {
if NeedsSandboxWriteCompletionBudget(sandboxConfigID) {
return DefaultAgentMaxCompletionTokens
}
return DefaultSmartReasoningMaxCompletionTokens
}
return DefaultQuickAnswerMaxCompletionTokens
}
// AgentRoundMaxCompletionTokens returns the completion-token budget for one
// ReAct LLM round when no sandbox is bound. Zero (unset) uses
// DefaultSmartReasoningMaxCompletionTokens. An explicit configured value is
// honored as-is.
func AgentRoundMaxCompletionTokens(configured int) int {
return AgentRoundMaxCompletionTokensFor(configured, "")
}
// MinSandboxWriteCompletionTokens is the floor applied to an explicitly
// configured per-round budget when a sandbox is bound. write_sandbox_file and
// edit_sandbox_file carry the whole file body inside the tool-call JSON, so a
// cap sized for ordinary chat truncates the arguments mid-string on every
// attempt — the agent then burns its rounds rewriting a file it can never
// finish. Below this the setting is not a preference, it is a deadlock.
const MinSandboxWriteCompletionTokens = 8192
// AgentRoundMaxCompletionTokensFor is AgentRoundMaxCompletionTokens with
// the agent's sandbox: unset + sandbox uses the large write-file budget, and a
// configured value too small to hold a file write is raised to the floor.
func AgentRoundMaxCompletionTokensFor(configured int, sandboxConfigID string) int {
if configured > 0 {
if NeedsSandboxWriteCompletionBudget(sandboxConfigID) &&
configured < MinSandboxWriteCompletionTokens {
return MinSandboxWriteCompletionTokens
}
return configured
}
return DefaultMaxCompletionTokens(AgentModeSmartReasoning, sandboxConfigID)
}
// UnlimitedMaxIterations is the stored MaxIterations value meaning the ReAct
// loop has no round cap. Zero still means "unset, apply default" so agents
// that omit the field keep their current behaviour.
const UnlimitedMaxIterations = -1
// AgentConfig represents the full agent configuration (used at tenant level and runtime)
// This includes all configuration parameters for agent execution
type AgentConfig struct {
// MaxIterations caps ReAct rounds. Zero is unset (filled with a default);
// a negative value is unlimited — the loop runs until the model stops,
// the user cancels, or another guard fires. See UnlimitedMaxIterations.
MaxIterations int `json:"max_iterations"`
AllowedTools []string `json:"allowed_tools"` // List of allowed tool names
Temperature float64 `json:"temperature"` // LLM temperature for agent
KnowledgeBases []string `json:"knowledge_bases"` // Accessible knowledge base IDs
KnowledgeIDs []string `json:"knowledge_ids"` // Accessible knowledge IDs (individual documents)
SystemPrompt string `json:"system_prompt,omitempty"` // Unified system prompt (uses web_search_status placeholder for dynamic behavior)
// Deprecated: Use SystemPrompt instead. Kept for backward compatibility during migration.
SystemPromptWebEnabled string `json:"system_prompt_web_enabled,omitempty"` // Deprecated: Custom prompt when web search is enabled
SystemPromptWebDisabled string `json:"system_prompt_web_disabled,omitempty"` // Deprecated: Custom prompt when web search is disabled
UseCustomSystemPrompt bool `json:"use_custom_system_prompt"` // Whether to use custom system prompt instead of default
LocalBrowserEnabled bool `json:"-"` // Per-turn local_browser gate
WebSearchEnabled bool `json:"web_search_enabled"` // Whether web search tool is enabled
WebSearchMaxResults int `json:"web_search_max_results"` // Maximum number of web search results (default: 5)
WebSearchProviderID string `json:"web_search_provider_id,omitempty"` // WebSearchProviderEntity ID (resolved from agent config)
MultiTurnEnabled bool `json:"multi_turn_enabled"` // Whether multi-turn conversation is enabled
MemoryEnabled *bool `json:"memory_enabled,omitempty"` // nil inherits workspace
SearchTargets SearchTargets `json:"-"` // Pre-computed unified search targets (runtime only)
// MCP service selection
MCPSelectionMode string `json:"mcp_selection_mode"` // MCP selection mode: "all", "selected", "none"
MCPServices []string `json:"mcp_services"` // Selected MCP service IDs (when mode is "selected")
// MCPAuthWaitTimeout is how many seconds an agent run waits for
// in-conversation OAuth authorization before skipping. <=0 falls back to
// the gate's configured timeout. The wait is always bounded (no leak).
MCPAuthWaitTimeout int `json:"mcp_auth_wait_timeout,omitempty"`
// AttachmentParseWaitTimeoutSec bounds how long reading an attachment waits for
// a file that is still being parsed. <=0 uses the server default.
AttachmentParseWaitTimeoutSec int `json:"-"`
// AttachmentSandboxCopies maps a sandbox path staged for this turn to the
// attachment:// path of the same stored attachment.
AttachmentSandboxCopies map[string]string `json:"-"`
// Whether to enable thinking mode (for models that support extended thinking)
Thinking *bool `json:"thinking"`
// ReasoningEffort is the graded thinking level; empty falls back to Thinking.
ReasoningEffort string `json:"reasoning_effort,omitempty"`
// Whether final answers include knowledge/web source citations. Nil defaults to true.
CitationEnabled *bool `json:"citation_enabled"`
// Whether to retrieve knowledge base only when explicitly mentioned with @ (default: false)
RetrieveKBOnlyWhenMentioned bool `json:"retrieve_kb_only_when_mentioned"`
// Whether to retain retrieval history (like wiki_read_page results) across turns (default: false)
RetainRetrievalHistory bool `json:"retain_retrieval_history"`
// Skills configuration (Progressive Disclosure pattern)
SkillsEnabled bool `json:"skills_enabled"` // Whether skills are enabled (default: false)
SkillDirs []string `json:"skill_dirs"` // Directories to search for skills
AllowedSkills []string `json:"allowed_skills"` // Skill names whitelist (empty = allow all)
// Runtime-only fields (not persisted)
ChatModelSupportsVision bool `json:"-"` // Resolved model capability, never supplied by tool input.
VLMModelID string `json:"-"` // VLM model ID for tool images, resolved from CustomAgent config.
SandboxConfigID string `json:"-"` // Workspace sandbox config ID for skill execution.
// TenantSkills are the skills installed into the selected sandbox config's
// snapshot image, already narrowed to the ones this run can actually
// invoke. Runtime only: it is derived per turn from the config the agent
// selected, never stored on the agent record.
TenantSkills []*TenantSkillEntity `json:"-"`
// Per-request @mention pins (runtime only; injected as <must_use> in the user message).
PinnedMCPServiceIDs []string `json:"-"`
PinnedSkillNames []string `json:"-"`
// QuestionOrigin is the knowledge source of a suggested question the user
// picked, already checked to be inside KnowledgeBases (runtime only;
// rendered into runtime_context as a retrieval hint).
QuestionOrigin *QuestionOrigin `json:"-"`
// PageContext is the page the user has open, already narrowed to this
// turn's search targets (runtime only; rendered into runtime_context).
PageContext *PageContext `json:"-"`
// SharedAgentReadOnly prevents a shared agent from mutating resources in
// its source workspace. It is set from the verified share relation, never
// inferred from a client-provided tenant ID.
SharedAgentReadOnly bool `json:"-"`
// OperationsAgentID, when set, grants this run the WeKnora operation
// catalog (find_operations / run_operation) and attributes its changes to
// that agent. It is set server-side for built-in management agents only,
// never read from an agent record, so a tenant cannot opt a custom agent
// into it. Runtime only.
OperationsAgentID string `json:"-"`
// AssistantAccess is how far an OperationsAgentID run may act without
// asking, already capped by the workspace. Runtime only.
AssistantAccess AssistantAccessLevel `json:"-"`
// AssistantName is what the workspace calls the assistant; empty keeps
// the system prompt's. Runtime only.
AssistantName string `json:"-"`
// ProductDocs grants the bundled WeKnora documentation tools (runtime only).
ProductDocs bool `json:"-"`
// WritableKBIDs are the SearchTargets KBs this caller may modify (its own
// workspace's, or shared to it as editor+). Search targets only need read
// access, so tools that write (wiki pages and issues) are limited to this
// set; empty means read-only. Runtime only, derived per turn.
WritableKBIDs []string `json:"-"`
// LLM call timeout in seconds (default: 120). Controls the maximum time for a single LLM call.
LLMCallTimeout int `json:"llm_call_timeout,omitempty"`
// Maximum completion tokens for each ReAct LLM round. Zero means
// DefaultMaxCompletionTokens for this agent's mode and sandbox.
// Explicit values are sent as-is.
MaxCompletionTokens int `json:"max_completion_tokens,omitempty"`
// ModelMaxOutputTokens is the resolved model's per-response output limit,
// or zero when unknown. It caps the round budget and is resolved per run.
ModelMaxOutputTokens int `json:"-"`
// Maximum character length for tool output (default: 16000).
// Outputs exceeding this limit are truncated with head + tail preservation.
MaxToolOutputChars int `json:"max_tool_output_chars,omitempty"`
// Maximum context window tokens for the agent. Zero means "use the
// model's context_window, or DefaultMaxContextTokens (200000)".
MaxContextTokens int `json:"max_context_tokens,omitempty"`
// ContextTokenScale is the provider's tokens per estimated token that the
// session's last calibrated turn measured (TokenUsage.ContextTokenScale).
// The engine starts its estimator at this scale. Zero means uncalibrated.
// Runtime only.
ContextTokenScale float64 `json:"-"`
// How much recent conversation a compaction keeps verbatim. Zero means
// compaction.DefaultKeepRecentTokens, scaled down on small windows. This
// is the knob that decides how often compaction runs: whatever the context
// grew to, it comes out of a compaction at roughly this size.
CompactionKeepRecentTokens int `json:"compaction_keep_recent_tokens,omitempty"`
// Whether to execute independent tool calls in parallel (default: false).
// When enabled and the LLM returns multiple tool calls, they run concurrently via errgroup.
ParallelToolCalls bool `json:"parallel_tool_calls,omitempty"`
// skillInstallMode routes this run's shell_exec to the privileged
// install-mode executor (root, skills image root writable). It is
// unexported on purpose: JSON cannot reach it, so no stored agent record
// and no API payload can request the privilege, and no other package can
// assign it. EnableSkillInstallMode is the only way in and it refuses
// every agent except the built-in skill installer.
skillInstallMode bool
// skillInstallDir is the one skill directory this install owns. The skill
// file tools are scoped to it, so an installer cannot write a neighbouring
// skill in the shared image. Unexported for the same reason as
// skillInstallMode: the scope of a privilege must not be settable by
// anything a tenant can store or send.
skillInstallDir string
}
// EnableSkillInstallMode grants install-mode shell execution to the built-in
// skill installer agent and to nothing else, scoped to the skill directory it
// was started for. The agent ID is checked here rather than at the call site
// so there is exactly one place to audit.
//
// The privilege and its scope are granted together: a caller cannot obtain the
// root shell without naming the directory the file tools will be confined to.
// skillDir is stored verbatim and validated where the tools are constructed —
// types cannot import the sandbox package that owns the path rules.
func (c *AgentConfig) EnableSkillInstallMode(agentID, skillDir string) {
if c == nil || agentID != BuiltinSkillInstallerID {
return
}
c.skillInstallMode = true
c.skillInstallDir = skillDir
}
// SkillInstallMode reports whether this run may use the privileged
// install-mode shell.
func (c *AgentConfig) SkillInstallMode() bool {
return c != nil && c.skillInstallMode
}
// SkillInstallDir is the skill directory this install may write, or "" when
// this run is not an install.
func (c *AgentConfig) SkillInstallDir() string {
if c == nil || !c.skillInstallMode {
return ""
}
return c.skillInstallDir
}
// UnlimitedIterations reports whether the ReAct loop has no round cap.
func (c *AgentConfig) UnlimitedIterations() bool {
return c != nil && c.MaxIterations < 0
}
// CitationsEnabled preserves citation output for legacy runtime configs that
// predate the setting and therefore have a nil CitationEnabled value.
func (c *AgentConfig) CitationsEnabled() bool {
return c == nil || c.CitationEnabled == nil || *c.CitationEnabled
}
// SessionAgentConfig represents session-level agent configuration
// Sessions only store Enabled and KnowledgeBases; other configs are read from Tenant at runtime
type SessionAgentConfig struct {
AgentModeEnabled bool `json:"agent_mode_enabled"` // Whether agent mode is enabled for this session
WebSearchEnabled bool `json:"web_search_enabled"` // Whether web search is enabled for this session
KnowledgeBases []string `json:"knowledge_bases"` // Accessible knowledge base IDs for this session
KnowledgeIDs []string `json:"knowledge_ids"` // Accessible knowledge IDs (individual documents) for this session
}
// Value implements driver.Valuer interface for AgentConfig
func (c AgentConfig) Value() (driver.Value, error) {
return json.Marshal(c)
}
// Scan implements sql.Scanner interface for AgentConfig
func (c *AgentConfig) Scan(value interface{}) error {
if value == nil {
return nil
}
var b []byte
switch v := value.(type) {
case []byte:
b = v
case string:
b = []byte(v)
default:
return nil
}
return json.Unmarshal(b, c)
}
// Value implements driver.Valuer interface for SessionAgentConfig
func (c SessionAgentConfig) Value() (driver.Value, error) {
return json.Marshal(c)
}
// Scan implements sql.Scanner interface for SessionAgentConfig
func (c *SessionAgentConfig) Scan(value interface{}) error {
if value == nil {
return nil
}
var b []byte
switch v := value.(type) {
case []byte:
b = v
case string:
b = []byte(v)
default:
return nil
}
return json.Unmarshal(b, c)
}
// ResolveSystemPrompt returns the prompt template for the given web search state.
// It uses the unified SystemPrompt field, falling back to deprecated fields for backward compatibility.
func (c *AgentConfig) ResolveSystemPrompt(webSearchEnabled bool) string {
if c == nil {
return ""
}
// First, try the new unified SystemPrompt field
if c.SystemPrompt != "" {
return c.SystemPrompt
}
// Fallback to deprecated fields for backward compatibility
if webSearchEnabled {
if c.SystemPromptWebEnabled != "" {
return c.SystemPromptWebEnabled
}
} else {
if c.SystemPromptWebDisabled != "" {
return c.SystemPromptWebDisabled
}
}
return ""
}
// Tool defines the interface that all agent tools must implement
type Tool interface {
// Name returns the unique identifier for this tool
Name() string
// Description returns a human-readable description of what the tool does
Description() string
// Parameters returns the JSON Schema for the tool's parameters
Parameters() json.RawMessage
// Execute runs the tool with the given arguments
Execute(ctx context.Context, args json.RawMessage) (*ToolResult, error)
}
// Cleanable is an optional interface that tools can implement to release resources.
// Tools implementing this interface will have their Cleanup method called during
// registry cleanup (e.g., at the end of an agent session).
type Cleanable interface {
Cleanup(ctx context.Context)
}
// ToolResult represents the result of a tool execution
type ToolResult struct {
// OutputFiles holds sandbox references for this live result only. History
// uses the final answer's persistent resource references instead.
// A non-nil empty slice means output inspection found no eligible changes;
// nil means no output inspection result is available.
OutputFiles []string `json:"-"`
Success bool `json:"success"` // Whether the tool executed successfully
Output string `json:"output"` // Human-readable output
Data map[string]interface{} `json:"data,omitempty"` // Structured data for programmatic use
Error string `json:"error,omitempty"` // Error message if execution failed
Images []string `json:"images,omitempty"` // Base64 data URIs from tool (e.g. MCP image content)
// ImageDescriptions is aligned with Images and holds a vision model's
// description of each for a chat model that cannot view them ("" when an
// image could not be described). Live only.
ImageDescriptions []string `json:"-"`
// ImageDetail ("brief" or "full") and ImageFocus carry how closely the
// model asked to read Images when it cannot view them. Live only.
ImageDetail string `json:"-"`
ImageFocus string `json:"-"`
// Suspend, when set, means the call did not run: it is waiting on a user
// prompt and the run must end so it can be resumed later. Live only.
Suspend *PromptSuspension `json:"-"`
}
// Image description detail levels requested by a file read.
const (
ImageDetailBrief = "brief"
ImageDetailFull = "full"
)
// ToolCall represents a single tool invocation within an agent step
type ToolCall struct {
// Target identifies the actual proxy target; Name/Args retain the model call for replay.
Target *ToolCallTarget `json:"target,omitempty"`
ID string `json:"id"` // Function call ID from LLM
Name string `json:"name"` // Tool name
Args map[string]interface{} `json:"args"` // Tool arguments
Result *ToolResult `json:"result"` // Execution result (contains Output)
Reflection string `json:"reflection,omitempty"` // Agent's reflection on this tool call result (if enabled)
Duration int64 `json:"duration"` // Execution time in milliseconds
ProviderMetadata ToolCallMetadata `json:"provider_metadata,omitempty"` // Provider-specific tool-call state for replay
}
// ToolCallTarget identifies a resolved invocation without rewriting the model's
// function call, which must be preserved for history replay and provider state.
type ToolCallTarget struct {
Name string `json:"name"`
Args map[string]interface{} `json:"args"`
ServiceName string `json:"service_name"`
ToolName string `json:"tool_name"`
}
// ExecutionName returns the resolved target name for presentation and tracing.
func (t ToolCall) ExecutionName() string {
if t.Target != nil {
return t.Target.Name
}
return t.Name
}
// ExecutionArgs returns the resolved target arguments without changing replay data.
func (t ToolCall) ExecutionArgs() map[string]interface{} {
if t.Target != nil {
return t.Target.Args
}
return t.Args
}
// PipelineToolCallIDPrefix marks a persisted tool call the model never made.
// The fast-answer (KnowledgeQA) pipeline records its retrieval stages as tool
// calls so a reloaded conversation can redraw the same timeline it showed while
// streaming. History replay must skip them: asking the model to account for
// calls it never issued, against tools it may not even have, breaks the
// request protocol.
const PipelineToolCallIDPrefix = "ragpipe-"
// IsPipelineToolCallID reports whether a tool call was synthesized by the
// fast-answer pipeline rather than requested by the model.
func IsPipelineToolCallID(id string) bool {
return strings.HasPrefix(id, PipelineToolCallIDPrefix)
}
// BackgroundInjection is one background-work message the engine put in front
// of the model before a step's LLM call. History replays it in place; AckIDs
// are the completion notices it delivered, acknowledged once the assistant
// message carrying the step is persisted.
type BackgroundInjection struct {
Content string `json:"content"`
AckIDs []string `json:"ack_ids,omitempty"`
}
// AgentStep represents one iteration of the ReAct loop
type AgentStep struct {
Iteration int `json:"iteration"` // Iteration number (0-indexed)
Thought string `json:"thought"` // LLM's reasoning/thinking (Think phase)
// Progress is user-facing commentary from a non-terminal round. Thought stays intact for model replay.
Progress string `json:"progress,omitempty"`
ProgressEventID string `json:"progress_event_id,omitempty"`
// UserMessagesBefore records consumed steer rows in delivery order, before
// this model response. Unlike timestamps, this remains unambiguous on replay.
UserMessagesBefore []string `json:"user_messages_before,omitempty"`
// BackgroundInjections are background-work messages delivered before this
// model response, after the step's steered messages, in delivery order.
BackgroundInjections []BackgroundInjection `json:"background_injections,omitempty"`
// BackgroundSeenIDs are finished background items whose results this
// step's tool calls (work_wait, work_cancel) returned to the model.
BackgroundSeenIDs []string `json:"background_seen_ids,omitempty"`
// IntermediateAnswer preserves a plain answer followed by a loop-end steer.
// The canonical final answer is still stored in Message.Content.
IntermediateAnswer bool `json:"intermediate_answer,omitempty"`
// ReasoningContent stores the OpenAI-protocol reasoning_content emitted by the
// model in this round. Persisted on AgentStep so cross-turn replay can put it
// back on the assistant message — required by MiMo / DeepSeek V3.2+ thinking
// mode, ignored by providers that don't recognize the field.
ReasoningContent string `json:"reasoning_content,omitempty"`
// ReasoningSignature / ReasoningMetadata are the provider artifacts that
// must accompany ReasoningContent on replay (Anthropic signatures,
// OpenAI Responses encrypted reasoning items).
ReasoningSignature string `json:"reasoning_signature,omitempty"`
ReasoningMetadata ProviderMetadata `json:"reasoning_metadata,omitempty"`
ToolCalls []ToolCall `json:"tool_calls"` // Tools called in this step (Act phase)
// Approvals is the user decision for tools in this step. It is stored with
// the step so a reloaded transcript can show what was allowed or refused.
Approvals []ToolApprovalRecord `json:"approvals,omitempty"`
Timestamp time.Time `json:"timestamp"` // When this step occurred
// Truncated marks the round the completion-token cap cut off. It rides in
// the agent_steps JSON so a reloaded, shared or re-opened conversation can
// still show that the answer stops mid-sentence by design, rather than
// looking finished. Live streaming carries the same fact on the answer
// event; this is what survives the round trip.
Truncated bool `json:"truncated,omitempty"`
}
// HostApprovalSnapshot is the Lite host card stored with a tool approval.
type HostApprovalSnapshot struct {
Reason string `json:"reason"`
Command string `json:"command,omitempty"`
Cwd string `json:"cwd,omitempty"`
GrantPath string `json:"grant_path,omitempty"`
GrantAccess string `json:"grant_access,omitempty"`
DenialSnippet string `json:"denial_snippet,omitempty"`
FirstAttemptRan bool `json:"first_attempt_ran,omitempty"`
AllowSession bool `json:"allow_session"`
SessionRules []string `json:"session_rules,omitempty"`
}
// ToolApprovalRecord is one human approval attached to an agent step.
type ToolApprovalRecord struct {
PendingID string `json:"pending_id"`
ToolCallID string `json:"tool_call_id,omitempty"`
Kind string `json:"kind,omitempty"`
ServiceName string `json:"service_name,omitempty"`
MCPToolName string `json:"mcp_tool_name,omitempty"`
Description string `json:"description,omitempty"`
ArgsJSON string `json:"args_json,omitempty"`
TimeoutSeconds int `json:"timeout_seconds,omitempty"`
RequestedAt int64 `json:"requested_at,omitempty"`
Host *HostApprovalSnapshot `json:"host,omitempty"`
Resolved bool `json:"resolved,omitempty"`
Approved bool `json:"approved,omitempty"`
Reason string `json:"reason,omitempty"`
TimedOut bool `json:"timed_out,omitempty"`
Canceled bool `json:"canceled,omitempty"`
Scope string `json:"scope,omitempty"`
}
// GetObservations returns observations from all tool calls in this step
// This is a convenience method to maintain backward compatibility
func (s *AgentStep) GetObservations() []string {
observations := make([]string, 0, len(s.ToolCalls))
for _, tc := range s.ToolCalls {
if tc.Result != nil && tc.Result.Output != "" {
observations = append(observations, tc.Result.Output)
}
if tc.Reflection != "" {
observations = append(observations, "Reflection: "+tc.Reflection)
}
}
return observations
}
// AgentState tracks the execution state of an agent across iterations
type AgentState struct {
PendingSteerMessages []string `json:"-"`
PendingBackground []BackgroundInjection `json:"-"`
CurrentRound int `json:"current_round"` // Current round number
RoundSteps []AgentStep `json:"round_steps"` // All steps taken so far in the current round
IsComplete bool `json:"is_complete"` // Whether agent has finished
FinalAnswer string `json:"final_answer"` // The final answer to the query
KnowledgeRefs []*SearchResult `json:"knowledge_refs"` // Collected knowledge references
TurnUsage TokenUsage `json:"turn_usage"` // LLM usage accumulated across this turn
// Suspended is set when the run ended waiting on a user prompt.
// SuspendedStep is the interrupted round: its thought and the calls
// that finished before the blocked one, kept for display.
Suspended *PromptSuspension `json:"-"`
SuspendedStep *AgentStep `json:"-"`
}
// FunctionDefinition represents a function definition for LLM function calling
type FunctionDefinition struct {
Name string `json:"name"`
Description string `json:"description"`
Parameters json.RawMessage `json:"parameters"`
}