agent

type Agent struct {
	Identity `yaml:",inline" json:",inline"`
	Source   *Source `yaml:"source,omitempty" json:"source,omitempty"` // Source of the agent

	llm.ModelSelection `yaml:",inline" json:",inline"`

	Temperature float64        `yaml:"temperature,omitempty" json:"temperature,omitempty"` // Temperature
	Description string         `yaml:"description,omitempty" json:"description,omitempty"` // Description of the agent
	Prompt      *prompt.Prompt `yaml:"prompt,omitempty" json:"prompt,omitempty"`           // Prompt template
	Knowledge   []*Knowledge   `yaml:"knowledge,omitempty" json:"knowledge,omitempty"`

	// AutoSummarize controls whether the conversation is automatically
	// summarized/compacted after a turn (when supported by the runtime).
	AutoSummarize *bool `yaml:"autoSummarize,omitempty" json:"autoSummarize,omitempty"`

	// UI defaults: whether to show execution details and tool feed in chat
	ShowExecutionDetails *bool `yaml:"showExecutionDetails,omitempty" json:"showExecutionDetails,omitempty"`
	ShowToolFeed         *bool `yaml:"showToolFeed,omitempty" json:"showToolFeed,omitempty"`

	SystemPrompt    *prompt.Prompt `yaml:"systemPrompt,omitempty" json:"systemPrompt,omitempty"`
	SystemKnowledge []*Knowledge   `yaml:"systemKnowledge,omitempty" json:"systemKnowledge,omitempty"`
	Tool            []*llm.Tool    `yaml:"tool,omitempty" json:"tool,omitempty"`

	// ParallelToolCalls requests providers that support it to execute
	// multiple tool calls in parallel within a single reasoning step.
	// Honored only when the selected model implements the feature.
	ParallelToolCalls bool `yaml:"parallelToolCalls,omitempty" json:"parallelToolCalls,omitempty"`

	// ToolCallExposure defines how tool calls are exposed to the LLM
	ToolCallExposure ToolCallExposure `yaml:"toolCallExposure,omitempty" json:"toolCallExposure,omitempty"`

	// Persona defines the default conversational persona the agent uses when
	// sending messages. When nil the role defaults to "assistant".
	Persona *prompt.Persona `yaml:"persona,omitempty" json:"persona,omitempty"`

	// ToolExport controls automatic exposure of this agent as a virtual tool
	ToolExport *ToolExport `yaml:"toolExport,omitempty" json:"toolExport,omitempty"`

	// Attachment groups binary-attachment behavior
	Attachment *Attachment `yaml:"attachment,omitempty" json:"attachment,omitempty"`

	// Chains defines post-turn follow-ups executed after a turn finishes.
	Chains []*Chain `yaml:"chains,omitempty" json:"chains,omitempty"`

	// MCPResources controls optional inclusion of MCP-accessible resources
	// as binary attachments in the core LLM generate call. When enabled, the
	// agent service will lazily index the specified locations with Embedius,
	// select the top-N most relevant resources for the current query, and
	// include them as attachments in the request.
	MCPResources *MCPResources `yaml:"mcpResources,omitempty" json:"mcpResources,omitempty"`
}

type Attachment struct {
	// LimitBytes caps cumulative attachments size per conversation for this agent.
	// When zero, a provider default may apply or no cap if provider has none.
	LimitBytes int64 `yaml:"limitBytes,omitempty" json:"limitBytes,omitempty"`

	// Mode controls delivery: "ref" or "inline"
	Mode string `yaml:"mode,omitempty" json:"mode,omitempty"`

	// TTLSec sets TTL for attachments in seconds.
	TTLSec int64 `yaml:"ttlSec,omitempty" json:"ttlSec,omitempty"`

	// ToolCallConversionThreshold sets default threshold (bytes) to convert
	// tool call results into PDF attachments (provider-dependent).
	ToolCallConversionThreshold int64 `yaml:"toolCallConversionThreshold,omitempty" json:"toolCallConversionThreshold,omitempty"`
}

type Chain struct {
	On           string      `yaml:"on,omitempty" json:"on,omitempty"`                     // succeeded|failed|canceled|*
	Target       ChainTarget `yaml:"target" json:"target"`                                 // required: agent to invoke
	Conversation string      `yaml:"conversation,omitempty" json:"conversation,omitempty"` // reuse|link (default link)
	When         *WhenSpec   `yaml:"when,omitempty" json:"when,omitempty"`                 // optional condition

	Query *prompt.Prompt `yaml:"query,omitempty" json:"query,omitempty"` // templated query/payload

	Publish *ChainPublish `yaml:"publish,omitempty" json:"publish,omitempty"` // optional publish settings
	OnError string        `yaml:"onError,omitempty" json:"onError,omitempty"` // ignore|message|propagate
	Limits  *ChainLimits  `yaml:"limits,omitempty" json:"limits,omitempty"`   // guard-rails
}

type ChainLimits struct {
	MaxDepth int `yaml:"maxDepth,omitempty" json:"maxDepth,omitempty"`
}

type ChainPublish struct {
	Role   string `yaml:"role,omitempty" json:"role,omitempty"`     // assistant|user|system|tool|none
	Name   string `yaml:"name,omitempty" json:"name,omitempty"`     // attribution handle
	Type   string `yaml:"type,omitempty" json:"type,omitempty"`     // text|control
	Parent string `yaml:"parent,omitempty" json:"parent,omitempty"` // same_turn|last_user|none
}

type ChainTarget struct {
	AgentID string `yaml:"agentId" json:"agentId"`
}

type Finder interface {
	Find(ctx context.Context, id string) (*Agent, error)
}

type Identity struct {
	ID   string `yaml:"id,omitempty" json:"id,omitempty"`
	Name string `yaml:"name,omitempty" json:"name,omitempty"`
	Icon string `yaml:"icon,omitempty" json:"icon,omitempty"`
}

type Knowledge struct {
	Description   string          `yaml:"description,omitempty" json:"description,omitempty"`
	Match         *option.Options `json:"match,omitempty"` // Optional matching options
	URL           string          `yaml:"url,omitempty" json:"url,omitempty"`
	InclusionMode string          `yaml:"inclusionMode,omitempty" json:"inclusionMode,omitempty"` // Inclusion mode for the knowledge base
	MaxFiles      int             `yaml:"maxFiles,omitempty" json:"maxFiles,omitempty"`           // Max matched assets per knowledge (default 5)
}

type Loader interface {
	// Add stores an in-memory representation of an Agent so it becomes
	// available for subsequent queries.
	Add(name string, agent *Agent)

	//Load retrieves an Agent by its name. If the Agent does not exist, it
	Load(ctx context.Context, name string) (*Agent, error)
}

type MCPResources struct {
	Enabled   bool            `yaml:"enabled,omitempty" json:"enabled,omitempty"`
	Locations []string        `yaml:"locations,omitempty" json:"locations,omitempty"`
	MaxFiles  int             `yaml:"maxFiles,omitempty" json:"maxFiles,omitempty"`
	TrimPath  string          `yaml:"trimPath,omitempty" json:"trimPath,omitempty"`
	Match     *option.Options `yaml:"match,omitempty" json:"match,omitempty"`
}

type Source struct {
	URL string `yaml:"url,omitempty" json:"url,omitempty"`
}

type ToolCallExposure string

type ToolExport struct {
	Expose  bool     `yaml:"expose,omitempty" json:"expose,omitempty"`   // opt-in flag
	Service string   `yaml:"service,omitempty" json:"service,omitempty"` // MCP service name (default "agentExec")
	Method  string   `yaml:"method,omitempty" json:"method,omitempty"`   // Method name (default agent.id)
	Domains []string `yaml:"domains,omitempty" json:"domains,omitempty"` // Allowed parent domains
}

type WhenExpect struct {
	Kind    string `yaml:"kind,omitempty" json:"kind,omitempty"`
	Pattern string `yaml:"pattern,omitempty" json:"pattern,omitempty"`
	Path    string `yaml:"path,omitempty" json:"path,omitempty"`
}

type WhenSpec struct {
	Expr   string         `yaml:"expr,omitempty" json:"expr,omitempty"`
	Query  *prompt.Prompt `yaml:"query,omitempty" json:"query,omitempty"`
	Model  string         `yaml:"model,omitempty" json:"model,omitempty"`
	Expect *WhenExpect    `yaml:"expect,omitempty" json:"expect,omitempty"`
}