agent

type Agent ¶

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

Agent runs LLM-backed workflows via Temporal. It holds agentConfig and client-side state (agentChannel, event worker). Uses AgentWorker for run workflow execution.

func NewAgent(opts ...Option) (*Agent, error)

func (a *Agent) AgentEventWorkflow(ctx workflow.Context) error

func (a *Agent) Close()

func (a *Agent) EventPublishActivity(ctx context.Context, channel string, event *AgentEvent) error

func (a *Agent) OnApproval(ctx context.Context, approvalToken string, status ApprovalStatus) error

func (a *Agent) Run(ctx context.Context, input string, conversationID string) (*AgentResponse, error)

func (a *Agent) RunAsync(ctx context.Context, input string, conversationID string) (resultCh <-chan RunAsyncResult, approvalCh <-chan *ApprovalRequest, err error)

func (a *Agent) RunStream(ctx context.Context, input string, conversationID string) (chan *AgentEvent, error)

type AgentEvent ¶

type AgentEvent struct {
	Type       AgentEventType         `json:"type"`
	AgentName  string                 `json:"agent_name,omitempty"`
	Content    string                 `json:"content,omitempty"`
	ToolCall   *ToolCallEvent         `json:"tool_call,omitempty"`
	Approval   *ApprovalEvent         `json:"approval,omitempty"` // for AgentEventApproval
	Error      error                  `json:"error,omitempty"`
	Metadata   map[string]interface{} `json:"metadata,omitempty"`
	Timestamp  time.Time              `json:"timestamp"`
	WorkflowID string                 `json:"workflow_id,omitempty"` // run workflow ID; for correlation only
}

AgentEvent is published to subscribers when the agent produces output or errors. AgentName identifies which agent in a delegation tree emitted the event (main or sub-agent). RunStream uses it so AgentEventComplete from a sub-agent does not close the root stream. For AgentEventApproval, the requesting agent is also on AgentName (not duplicated on Approval).

type AgentEventType ¶

type AgentEventType string

AgentEventType is the type of agent events

const (
	AgentEventContent       AgentEventType = "content"
	AgentEventContentDelta  AgentEventType = "content_delta" // partial token stream
	AgentEventThinking      AgentEventType = "thinking"
	AgentEventThinkingDelta AgentEventType = "thinking_delta" // Anthropic extended thinking stream
	AgentEventToolCall      AgentEventType = "tool_call"
	AgentEventToolResult    AgentEventType = "tool_result"
	AgentEventApproval      AgentEventType = "approval"
	AgentEventError         AgentEventType = "error"
	AgentEventComplete      AgentEventType = "complete"
)

type AgentEventUpdate ¶

type AgentEventUpdate struct {
	AgentName        string      `json:"agent_name"`
	LocalChannelName string      `json:"local_channel_name,omitempty"`
	Event            *AgentEvent `json:"event"`
}

AgentEventUpdate is the payload for agent-event updates when using one event workflow per agent. AgentName is the name of the agent that emitted the event (main agent or a sub-agent). LocalChannelName is the in-process pub/sub channel name (agent_event_<main-workflow-id>) all nodes in the delegation tree publish to.

type AgentLLMInput ¶

type AgentLLMInput struct {
	ConversationID string               `json:"conversation_id,omitempty"`
	Messages       []interfaces.Message `json:"messages,omitempty"`
	SkipTools      bool                 `json:"skip_tools,omitempty"`
}

AgentLLMInput is the input to AgentLLMActivity. When ConversationID is set, activity fetches messages from store. UserPrompt is passed directly; no message construction in workflow. Messages used only for non-conversation multi-turn.

type AgentLLMResult ¶

type AgentLLMResult struct {
	Content   string            `json:"content"`
	ToolCalls []ToolCallRequest `json:"tool_calls"`
}

AgentLLMResult is the return value of AgentLLMActivity. Workflow uses it to decide: return content or execute tools.

type AgentLLMStreamInput ¶

type AgentLLMStreamInput struct {
	ConversationID   string               `json:"conversation_id,omitempty"`
	Messages         []interfaces.Message `json:"messages,omitempty"`
	EventWorkflowID  string               `json:"event_workflow_id,omitempty"`
	LocalChannelName string               `json:"local_channel_name,omitempty"`
	SkipTools        bool                 `json:"skip_tools,omitempty"`
}

AgentLLMStreamInput is the input to AgentLLMStreamActivity.

type AgentResponse ¶

type AgentResponse struct {
	Content   string         `json:"content"`
	AgentName string         `json:"agent_name"`
	Model     string         `json:"model"`
	Metadata  map[string]any `json:"metadata"`
}

AgentResponse is the return value of AgentRun.Get / AgentWorkflow.

type AgentTool ¶

type AgentTool interface {
	interfaces.Tool
	// SubAgent returns the sub-agent this tool delegates to.
	SubAgent() *Agent
}

AgentTool marks a tool that represents sub-agent delegation (child AgentWorkflow), not normal Tool.Execute.

AgentWorkflow chooses delegation vs AgentToolExecuteActivity using SubAgentRoutes keyed by tool name, not by asserting AgentTool in workflow code. AgentTool is still used elsewhere (e.g. toolApprovalMetadata walks toolsList() and asserts AgentTool to set delegation fields on approval events).

type AgentToolApprovalInput ¶

type AgentToolApprovalInput struct {
	ToolName         string         `json:"tool_name"`
	Args             map[string]any `json:"args"`
	ToolCallID       string         `json:"tool_call_id"`
	EventWorkflowID  string         `json:"event_workflow_id"`
	LocalChannelName string         `json:"local_channel_name,omitempty"`
}

type AgentToolExecuteInput ¶

type AgentToolExecuteInput struct {
	ToolName       string               `json:"tool_name"`
	Args           map[string]any       `json:"args"`
	ConversationID string               `json:"conversation_id,omitempty"`
	Messages       []interfaces.Message `json:"messages,omitempty"`
	ToolCallID     string               `json:"tool_call_id,omitempty"`
}

AgentToolExecuteInput is the input to AgentToolExecuteActivity.

type AgentWorker ¶

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

AgentWorker runs the Temporal worker for an agent. It owns run worker creation and registration of workflows and activities from agent_workflow.go.

func NewAgentWorker(opts ...Option) (*AgentWorker, error)

func NewAgentWorkerDefault() *AgentWorker

func (aw *AgentWorker) AddConversationMessagesActivity(ctx context.Context, conversationID string, messages []interfaces.Message) error

func (aw *AgentWorker) AgentLLMActivity(ctx context.Context, input AgentLLMInput) (*AgentLLMResult, error)

func (aw *AgentWorker) AgentLLMStreamActivity(ctx context.Context, input AgentLLMStreamInput) (*AgentLLMResult, error)

func (aw *AgentWorker) AgentToolApprovalActivity(ctx context.Context, input AgentToolApprovalInput) (ApprovalStatus, error)

func (aw *AgentWorker) AgentToolExecuteActivity(ctx context.Context, input AgentToolExecuteInput) (string, error)

func (aw *AgentWorker) AgentWorkflow(ctx workflow.Context, input AgentWorkflowInput) (*AgentResponse, error)

func (aw *AgentWorker) Close()

func (aw *AgentWorker) SendAgentEventUpdateActivity(ctx context.Context, eventWorkflowID string, upd *AgentEventUpdate) error

func (aw *AgentWorker) Start() error

type AgentWorkflowInput ¶

type AgentWorkflowInput struct {
	UserPrompt       string                   `json:"user_prompt,omitempty"`
	EventWorkflowID  string                   `json:"event_workflow_id,omitempty"`
	LocalChannelName string                   `json:"local_channel_name,omitempty"`
	StreamingEnabled bool                     `json:"streaming_enabled,omitempty"`
	ConversationID   string                   `json:"conversation_id,omitempty"`
	EventTypes       []AgentEventType         `json:"event_types,omitempty"`
	SubAgentDepth    int                      `json:"sub_agent_depth,omitempty"`
	SubAgentRoutes   map[string]SubAgentRoute `json:"sub_agent_routes,omitempty"`
}

AgentWorkflowInput is the input to AgentWorkflow. EventWorkflowID is set when streaming or approval is used. StreamingEnabled enables partial content streaming (from WithStream). ConversationID is set when conversation is used; workflow fetches messages and writes assistant/tool via activities. SubAgentDepth is 0 for a top-level user run; each child workflow increments it (runtime cap vs maxSubAgentDepth). SubAgentRoutes maps sub-agent tool name -> route; built from WithSubAgents when the run starts. LocalChannelName is the in-process pub/sub channel name used for in-memory event fan-in across the delegation tree. Set once at the top level (agent_event_<main-workflow-id>) and propagated unchanged to all sub-agents. Contrast with EventWorkflowID which is used for out-of-process (remote) routing. EventTypes is set by the SDK; a single "*" element means emit all event kinds (used for RunStream).

type ApprovalEvent ¶

type ApprovalEvent struct {
	ToolCallID    string         `json:"tool_call_id,omitempty"`
	ToolName      string         `json:"tool_name"`
	Args          map[string]any `json:"args,omitempty"`
	ApprovalToken string         `json:"approval_token,omitempty"`
	// Kind is tool vs sub-agent delegation; use for UI copy.
	Kind ToolApprovalKind `json:"kind,omitempty"`
	// DelegateToName is set when Kind is delegation: display name of the target sub-agent.
	DelegateToName string `json:"delegate_to_name,omitempty"`
}

ApprovalEvent is the payload for AgentEventApproval (RunStream). The agent that requested approval is on AgentEvent.AgentName, not repeated here. Use with Agent.OnApproval when the user approves or rejects; see streaming examples.

type ApprovalHandler ¶

type ApprovalHandler func(ctx context.Context, req *ApprovalRequest)

ApprovalHandler is called when a tool needs approval (Run with WithApprovalHandler). req.Respond is always set: call req.Respond(ApprovalStatusApproved) or Rejected when ready. The handler may return immediately after starting async work. Multiple invocations may run concurrently when tools are invoked in parallel.

type ApprovalRequest ¶

type ApprovalRequest struct {
	ToolName string         `json:"tool_name"`
	Args     map[string]any `json:"args"`
	Respond  ApprovalSender `json:"-"`
	// Kind matches ApprovalEvent: distinguish normal tools from sub-agent delegation.
	Kind ToolApprovalKind `json:"kind,omitempty"`
	// AgentName is the agent running the workflow that requested approval.
	AgentName string `json:"agent_name,omitempty"`
	// DelegateToName is set for delegation: human-friendly target specialist name.
	DelegateToName string `json:"delegate_to_name,omitempty"`
}

ApprovalRequest describes a pending tool approval for Run and RunAsync. Respond is always set; call it once with ApprovalStatusApproved or ApprovalStatusRejected. For RunStream approvals, use OnApproval with the approval event payload instead.

type ApprovalSender ¶

type ApprovalSender func(status ApprovalStatus) error

ApprovalSender sends an approval result. Call once per request. Safe for concurrent use— multiple approvals may be pending when tools run in parallel.

type ApprovalStatus ¶

type ApprovalStatus string

const (
	ApprovalStatusNone     ApprovalStatus = "NONE"
	ApprovalStatusPending  ApprovalStatus = "PENDING"
	ApprovalStatusApproved ApprovalStatus = "APPROVED"
	ApprovalStatusRejected ApprovalStatus = "REJECTED"
)

type LLMSampling ¶

type LLMSampling struct {
	Temperature *float64 // 0-2 OpenAI, 0-1 Anthropic
	MaxTokens   int      // 0 = provider default
	TopP        *float64 // 0-1; OpenAI only
	TopK        *int     // Anthropic only
}

LLMSampling holds per-agent LLM sampling overrides. nil/0 = provider default. One LLM client can serve multiple agents with different sampling.

type Option ¶

type Option func(*agentConfig)

Option configures an agent. See agentConfig for which options apply to Agent vs AgentWorker.

func DisableWorker() Option

func WithApprovalHandler(fn ApprovalHandler) Option

func WithApprovalTimeout(d time.Duration) Option

func WithConversation(conv interfaces.Conversation) Option

func WithConversationSize(size int) Option

func WithDescription(desc string) Option

func WithEnableRemoteWorkers(enable bool) Option

func WithInstanceId(id string) Option

func WithLLMClient(client interfaces.LLMClient) Option

func WithLLMSampling(s *LLMSampling) Option

func WithLogLevel(level string) Option

func WithLogger(l log.Logger) Option

func WithMaxIterations(n int) Option

func WithMaxSubAgentDepth(depth int) Option

func WithName(name string) Option

func WithResponseFormat(rf *interfaces.ResponseFormat) Option

func WithStream(enable bool) Option

func WithSubAgents(subAgents ...*Agent) Option

func WithSystemPrompt(prompt string) Option

func WithTaskQueue(queue string) Option

func WithTemporalClient(tc client.Client) Option

func WithTemporalConfig(cfg *TemporalConfig) Option

func WithTimeout(d time.Duration) Option

func WithToolApprovalPolicy(policy interfaces.AgentToolApprovalPolicy) Option

func WithToolRegistry(reg interfaces.ToolRegistry) Option

func WithTools(tools ...interfaces.Tool) Option

type RequireAllToolApprovalPolicy ¶

type RequireAllToolApprovalPolicy struct{}

RequireAllToolApprovalPolicy requires approval for every tool. Default when no policy is set.

func (RequireAllToolApprovalPolicy) RequiresApproval(interfaces.Tool) bool

type RunAsyncResult ¶

type RunAsyncResult struct {
	Response *AgentResponse
	Err      error
}

RunAsyncResult is the single outcome from RunAsync. After the channel closes, Err is non-nil on failure; otherwise Response is non-nil.

type SubAgentRoute ¶

type SubAgentRoute struct {
	TaskQueue   string                   `json:"task_queue"`
	ChildRoutes map[string]SubAgentRoute `json:"child_routes,omitempty"`
}

SubAgentRoute tells the workflow how to delegate to a sub-agent: child AgentWorkflow on TaskQueue, with nested routes for that sub-agent's own sub-agents (frozen at parent run start).

type TemporalConfig ¶

type TemporalConfig struct {
	Host      string
	Port      int
	Namespace string
	TaskQueue string // Required. Full task queue name. Unique per agent.
}

TemporalConfig holds Temporal connection settings (Host, Port, Namespace) and the task queue name.

TaskQueue is required and must be unique per agent. Use different TaskQueues when running multiple agents in the same process (e.g. "my-agent-math", "my-agent-creative"). For multiple instances of the same agent (e.g. scaled pods), use WithInstanceId() so each instance gets a unique queue derived as {TaskQueue}-{InstanceId}.

When using DisableWorker, the agent and NewAgentWorker must use the same TaskQueue (and same InstanceId if set) so they pair correctly.

type ToolApprovalKind ¶

type ToolApprovalKind string

ToolApprovalKind classifies what the user is approving (same event type for RunStream).

const (
	// ToolApprovalKindTool is a normal tool execution (default when Kind is empty for older payloads).
	ToolApprovalKindTool ToolApprovalKind = "tool"
	// ToolApprovalKindDelegation is approval to run a registered sub-agent (delegate).
	ToolApprovalKindDelegation ToolApprovalKind = "delegation"
)

type ToolCallEvent ¶

type ToolCallEvent struct {
	ToolCallID string         `json:"tool_call_id,omitempty"`
	ToolName   string         `json:"tool_name"`
	Args       map[string]any `json:"args,omitempty"`
	Result     any            `json:"result,omitempty"`
	Status     ToolCallStatus `json:"status"`
}

type ToolCallRequest ¶

type ToolCallRequest struct {
	ToolCallID    string         `json:"tool_call_id"` // from LLM; used to match tool results
	ToolName      string         `json:"tool_name"`
	Args          map[string]any `json:"args"`
	NeedsApproval bool           `json:"needs_approval"`
}

ToolCallRequest is a tool invocation with approval flag. NeedsApproval is set by AgentLLMActivity.

type ToolCallStatus ¶

type ToolCallStatus string

const (
	ToolCallStatusPending   ToolCallStatus = "pending"
	ToolCallStatusRunning   ToolCallStatus = "running"
	ToolCallStatusCompleted ToolCallStatus = "completed"
	ToolCallStatusFailed    ToolCallStatus = "failed"
)