1package fantasy
2
3import (
4 "cmp"
5 "context"
6 "encoding/json"
7 "errors"
8 "fmt"
9 "maps"
10 "slices"
11 "sync"
12)
13
14// StepResult represents the result of a single step in an agent execution.
15type StepResult struct {
16 Response
17 Messages []Message
18}
19
20// stepExecutionResult encapsulates the result of executing a step with stream processing.
21type stepExecutionResult struct {
22 StepResult StepResult
23 ShouldContinue bool
24}
25
26// StopCondition defines a function that determines when an agent should stop executing.
27type StopCondition = func(steps []StepResult) bool
28
29// StepCountIs returns a stop condition that stops after the specified number of steps.
30func StepCountIs(stepCount int) StopCondition {
31 return func(steps []StepResult) bool {
32 return len(steps) >= stepCount
33 }
34}
35
36// HasToolCall returns a stop condition that stops when the specified tool is called in the last step.
37func HasToolCall(toolName string) StopCondition {
38 return func(steps []StepResult) bool {
39 if len(steps) == 0 {
40 return false
41 }
42 lastStep := steps[len(steps)-1]
43 toolCalls := lastStep.Content.ToolCalls()
44 for _, toolCall := range toolCalls {
45 if toolCall.ToolName == toolName {
46 return true
47 }
48 }
49 return false
50 }
51}
52
53// HasContent returns a stop condition that stops when the specified content type appears in the last step.
54func HasContent(contentType ContentType) StopCondition {
55 return func(steps []StepResult) bool {
56 if len(steps) == 0 {
57 return false
58 }
59 lastStep := steps[len(steps)-1]
60 for _, content := range lastStep.Content {
61 if content.GetType() == contentType {
62 return true
63 }
64 }
65 return false
66 }
67}
68
69// FinishReasonIs returns a stop condition that stops when the specified finish reason occurs.
70func FinishReasonIs(reason FinishReason) StopCondition {
71 return func(steps []StepResult) bool {
72 if len(steps) == 0 {
73 return false
74 }
75 lastStep := steps[len(steps)-1]
76 return lastStep.FinishReason == reason
77 }
78}
79
80// MaxTokensUsed returns a stop condition that stops when total token usage exceeds the specified limit.
81func MaxTokensUsed(maxTokens int64) StopCondition {
82 return func(steps []StepResult) bool {
83 var totalTokens int64
84 for _, step := range steps {
85 totalTokens += step.Usage.TotalTokens
86 }
87 return totalTokens >= maxTokens
88 }
89}
90
91// PrepareStepFunctionOptions contains the options for preparing a step in an agent execution.
92type PrepareStepFunctionOptions struct {
93 Steps []StepResult
94 StepNumber int
95 Model LanguageModel
96 Messages []Message
97}
98
99// PrepareStepResult contains the result of preparing a step in an agent execution.
100type PrepareStepResult struct {
101 Model LanguageModel
102 Messages []Message
103 System *string
104 ToolChoice *ToolChoice
105 ActiveTools []string
106 DisableAllTools bool
107 Tools []AgentTool
108}
109
110// ToolCallRepairOptions contains the options for repairing a tool call.
111type ToolCallRepairOptions struct {
112 OriginalToolCall ToolCallContent
113 ValidationError error
114 AvailableTools []AgentTool
115 SystemPrompt string
116 Messages []Message
117}
118
119type (
120 // PrepareStepFunction defines a function that prepares a step in an agent execution.
121 PrepareStepFunction = func(ctx context.Context, options PrepareStepFunctionOptions) (context.Context, PrepareStepResult, error)
122
123 // OnStepFinishedFunction defines a function that is called when a step finishes.
124 OnStepFinishedFunction = func(step StepResult)
125
126 // RepairToolCallFunction defines a function that repairs a tool call.
127 RepairToolCallFunction = func(ctx context.Context, options ToolCallRepairOptions) (*ToolCallContent, error)
128)
129
130type agentSettings struct {
131 systemPrompt string
132 maxOutputTokens *int64
133 temperature *float64
134 topP *float64
135 topK *int64
136 presencePenalty *float64
137 frequencyPenalty *float64
138 headers map[string]string
139 providerOptions ProviderOptions
140
141 // TODO: add support for provider tools
142 tools []AgentTool
143 maxRetries *int
144
145 model LanguageModel
146
147 stopWhen []StopCondition
148 prepareStep PrepareStepFunction
149 repairToolCall RepairToolCallFunction
150 onRetry OnRetryCallback
151}
152
153// AgentCall represents a call to an agent.
154type AgentCall struct {
155 Prompt string `json:"prompt"`
156 Files []FilePart `json:"files"`
157 Messages []Message `json:"messages"`
158 MaxOutputTokens *int64
159 Temperature *float64 `json:"temperature"`
160 TopP *float64 `json:"top_p"`
161 TopK *int64 `json:"top_k"`
162 PresencePenalty *float64 `json:"presence_penalty"`
163 FrequencyPenalty *float64 `json:"frequency_penalty"`
164 ActiveTools []string `json:"active_tools"`
165 ProviderOptions ProviderOptions
166 OnRetry OnRetryCallback
167 MaxRetries *int
168
169 StopWhen []StopCondition
170 PrepareStep PrepareStepFunction
171 RepairToolCall RepairToolCallFunction
172}
173
174// Agent-level callbacks.
175type (
176 // OnAgentStartFunc is called when agent starts.
177 OnAgentStartFunc func()
178
179 // OnAgentFinishFunc is called when agent finishes.
180 OnAgentFinishFunc func(result *AgentResult) error
181
182 // OnStepStartFunc is called when a step starts.
183 OnStepStartFunc func(stepNumber int) error
184
185 // OnStepFinishFunc is called when a step finishes.
186 OnStepFinishFunc func(stepResult StepResult) error
187
188 // OnFinishFunc is called when entire agent completes.
189 OnFinishFunc func(result *AgentResult)
190
191 // OnErrorFunc is called when an error occurs.
192 OnErrorFunc func(error)
193)
194
195// Stream part callbacks - called for each corresponding stream part type.
196type (
197 // OnChunkFunc is called for each stream part (catch-all).
198 OnChunkFunc func(StreamPart) error
199
200 // OnWarningsFunc is called for warnings.
201 OnWarningsFunc func(warnings []CallWarning) error
202
203 // OnTextStartFunc is called when text starts.
204 OnTextStartFunc func(id string) error
205
206 // OnTextDeltaFunc is called for text deltas.
207 OnTextDeltaFunc func(id, text string) error
208
209 // OnTextEndFunc is called when text ends.
210 OnTextEndFunc func(id string) error
211
212 // OnReasoningStartFunc is called when reasoning starts.
213 OnReasoningStartFunc func(id string, reasoning ReasoningContent) error
214
215 // OnReasoningDeltaFunc is called for reasoning deltas.
216 OnReasoningDeltaFunc func(id, text string) error
217
218 // OnReasoningEndFunc is called when reasoning ends.
219 OnReasoningEndFunc func(id string, reasoning ReasoningContent) error
220
221 // OnToolInputStartFunc is called when tool input starts.
222 OnToolInputStartFunc func(id, toolName string) error
223
224 // OnToolInputDeltaFunc is called for tool input deltas.
225 OnToolInputDeltaFunc func(id, delta string) error
226
227 // OnToolInputEndFunc is called when tool input ends.
228 OnToolInputEndFunc func(id string) error
229
230 // OnToolCallFunc is called when tool call is complete.
231 OnToolCallFunc func(toolCall ToolCallContent) error
232
233 // OnToolResultFunc is called when tool execution completes.
234 OnToolResultFunc func(result ToolResultContent) error
235
236 // OnSourceFunc is called for source references.
237 OnSourceFunc func(source SourceContent) error
238
239 // OnStreamFinishFunc is called when stream finishes.
240 OnStreamFinishFunc func(usage Usage, finishReason FinishReason, providerMetadata ProviderMetadata) error
241)
242
243// AgentStreamCall represents a streaming call to an agent.
244type AgentStreamCall struct {
245 Prompt string `json:"prompt"`
246 Files []FilePart `json:"files"`
247 Messages []Message `json:"messages"`
248 MaxOutputTokens *int64
249 Temperature *float64 `json:"temperature"`
250 TopP *float64 `json:"top_p"`
251 TopK *int64 `json:"top_k"`
252 PresencePenalty *float64 `json:"presence_penalty"`
253 FrequencyPenalty *float64 `json:"frequency_penalty"`
254 ActiveTools []string `json:"active_tools"`
255 Headers map[string]string
256 ProviderOptions ProviderOptions
257 OnRetry OnRetryCallback
258 MaxRetries *int
259
260 StopWhen []StopCondition
261 PrepareStep PrepareStepFunction
262 RepairToolCall RepairToolCallFunction
263
264 // Agent-level callbacks
265 OnAgentStart OnAgentStartFunc // Called when agent starts
266 OnAgentFinish OnAgentFinishFunc // Called when agent finishes
267 OnStepStart OnStepStartFunc // Called when a step starts
268 OnStepFinish OnStepFinishFunc // Called when a step finishes
269 OnFinish OnFinishFunc // Called when entire agent completes
270 OnError OnErrorFunc // Called when an error occurs
271
272 // Stream part callbacks - called for each corresponding stream part type
273 OnChunk OnChunkFunc // Called for each stream part (catch-all)
274 OnWarnings OnWarningsFunc // Called for warnings
275 OnTextStart OnTextStartFunc // Called when text starts
276 OnTextDelta OnTextDeltaFunc // Called for text deltas
277 OnTextEnd OnTextEndFunc // Called when text ends
278 OnReasoningStart OnReasoningStartFunc // Called when reasoning starts
279 OnReasoningDelta OnReasoningDeltaFunc // Called for reasoning deltas
280 OnReasoningEnd OnReasoningEndFunc // Called when reasoning ends
281 OnToolInputStart OnToolInputStartFunc // Called when tool input starts
282 OnToolInputDelta OnToolInputDeltaFunc // Called for tool input deltas
283 OnToolInputEnd OnToolInputEndFunc // Called when tool input ends
284 OnToolCall OnToolCallFunc // Called when tool call is complete
285 OnToolResult OnToolResultFunc // Called when tool execution completes
286 OnSource OnSourceFunc // Called for source references
287 OnStreamFinish OnStreamFinishFunc // Called when stream finishes
288}
289
290// AgentResult represents the result of an agent execution.
291type AgentResult struct {
292 Steps []StepResult
293 // Final response
294 Response Response
295 TotalUsage Usage
296}
297
298// Agent represents an AI agent that can generate responses and stream responses.
299type Agent interface {
300 Generate(context.Context, AgentCall) (*AgentResult, error)
301 Stream(context.Context, AgentStreamCall) (*AgentResult, error)
302}
303
304// AgentOption defines a function that configures agent settings.
305type AgentOption = func(*agentSettings)
306
307type agent struct {
308 settings agentSettings
309}
310
311// NewAgent creates a new agent with the given language model and options.
312func NewAgent(model LanguageModel, opts ...AgentOption) Agent {
313 settings := agentSettings{
314 model: model,
315 }
316 for _, o := range opts {
317 o(&settings)
318 }
319 return &agent{
320 settings: settings,
321 }
322}
323
324func (a *agent) prepareCall(call AgentCall) AgentCall {
325 call.MaxOutputTokens = cmp.Or(call.MaxOutputTokens, a.settings.maxOutputTokens)
326 call.Temperature = cmp.Or(call.Temperature, a.settings.temperature)
327 call.TopP = cmp.Or(call.TopP, a.settings.topP)
328 call.TopK = cmp.Or(call.TopK, a.settings.topK)
329 call.PresencePenalty = cmp.Or(call.PresencePenalty, a.settings.presencePenalty)
330 call.FrequencyPenalty = cmp.Or(call.FrequencyPenalty, a.settings.frequencyPenalty)
331 call.MaxRetries = cmp.Or(call.MaxRetries, a.settings.maxRetries)
332
333 if len(call.StopWhen) == 0 && len(a.settings.stopWhen) > 0 {
334 call.StopWhen = a.settings.stopWhen
335 }
336 if call.PrepareStep == nil && a.settings.prepareStep != nil {
337 call.PrepareStep = a.settings.prepareStep
338 }
339 if call.RepairToolCall == nil && a.settings.repairToolCall != nil {
340 call.RepairToolCall = a.settings.repairToolCall
341 }
342 if call.OnRetry == nil && a.settings.onRetry != nil {
343 call.OnRetry = a.settings.onRetry
344 }
345
346 providerOptions := ProviderOptions{}
347 if a.settings.providerOptions != nil {
348 maps.Copy(providerOptions, a.settings.providerOptions)
349 }
350 if call.ProviderOptions != nil {
351 maps.Copy(providerOptions, call.ProviderOptions)
352 }
353 call.ProviderOptions = providerOptions
354
355 headers := map[string]string{}
356
357 if a.settings.headers != nil {
358 maps.Copy(headers, a.settings.headers)
359 }
360
361 return call
362}
363
364// Generate implements Agent.
365func (a *agent) Generate(ctx context.Context, opts AgentCall) (*AgentResult, error) {
366 opts = a.prepareCall(opts)
367 initialPrompt, err := a.createPrompt(a.settings.systemPrompt, opts.Prompt, opts.Messages, opts.Files...)
368 if err != nil {
369 return nil, err
370 }
371 var responseMessages []Message
372 var steps []StepResult
373
374 for {
375 stepInputMessages := append(initialPrompt, responseMessages...)
376 stepModel := a.settings.model
377 stepSystemPrompt := a.settings.systemPrompt
378 stepActiveTools := opts.ActiveTools
379 stepToolChoice := ToolChoiceAuto
380 disableAllTools := false
381 stepTools := a.settings.tools
382 if opts.PrepareStep != nil {
383 updatedCtx, prepared, err := opts.PrepareStep(ctx, PrepareStepFunctionOptions{
384 Model: stepModel,
385 Steps: steps,
386 StepNumber: len(steps),
387 Messages: stepInputMessages,
388 })
389 if err != nil {
390 return nil, err
391 }
392
393 ctx = updatedCtx
394
395 // Apply prepared step modifications
396 if prepared.Messages != nil {
397 stepInputMessages = prepared.Messages
398 }
399 if prepared.Model != nil {
400 stepModel = prepared.Model
401 }
402 if prepared.System != nil {
403 stepSystemPrompt = *prepared.System
404 }
405 if prepared.ToolChoice != nil {
406 stepToolChoice = *prepared.ToolChoice
407 }
408 if len(prepared.ActiveTools) > 0 {
409 stepActiveTools = prepared.ActiveTools
410 }
411 disableAllTools = prepared.DisableAllTools
412 if prepared.Tools != nil {
413 stepTools = prepared.Tools
414 }
415 }
416
417 // Recreate prompt with potentially modified system prompt
418 if stepSystemPrompt != a.settings.systemPrompt {
419 stepPrompt, err := a.createPrompt(stepSystemPrompt, opts.Prompt, opts.Messages, opts.Files...)
420 if err != nil {
421 return nil, err
422 }
423 // Replace system message part, keep the rest
424 if len(stepInputMessages) > 0 && len(stepPrompt) > 0 {
425 stepInputMessages[0] = stepPrompt[0] // Replace system message
426 }
427 }
428
429 preparedTools := a.prepareTools(stepTools, stepActiveTools, disableAllTools)
430
431 retryOptions := DefaultRetryOptions()
432 if opts.MaxRetries != nil {
433 retryOptions.MaxRetries = *opts.MaxRetries
434 }
435 retryOptions.OnRetry = opts.OnRetry
436 retry := RetryWithExponentialBackoffRespectingRetryHeaders[*Response](retryOptions)
437
438 result, err := retry(ctx, func() (*Response, error) {
439 return stepModel.Generate(ctx, Call{
440 Prompt: stepInputMessages,
441 MaxOutputTokens: opts.MaxOutputTokens,
442 Temperature: opts.Temperature,
443 TopP: opts.TopP,
444 TopK: opts.TopK,
445 PresencePenalty: opts.PresencePenalty,
446 FrequencyPenalty: opts.FrequencyPenalty,
447 Tools: preparedTools,
448 ToolChoice: &stepToolChoice,
449 ProviderOptions: opts.ProviderOptions,
450 })
451 })
452 if err != nil {
453 return nil, err
454 }
455
456 var stepToolCalls []ToolCallContent
457 for _, content := range result.Content {
458 if content.GetType() == ContentTypeToolCall {
459 toolCall, ok := AsContentType[ToolCallContent](content)
460 if !ok {
461 continue
462 }
463
464 // Validate and potentially repair the tool call
465 validatedToolCall := a.validateAndRepairToolCall(ctx, toolCall, stepTools, stepSystemPrompt, stepInputMessages, a.settings.repairToolCall)
466 stepToolCalls = append(stepToolCalls, validatedToolCall)
467 }
468 }
469
470 toolResults, err := a.executeTools(ctx, stepTools, stepToolCalls, nil)
471
472 // Build step content with validated tool calls and tool results
473 stepContent := []Content{}
474 toolCallIndex := 0
475 for _, content := range result.Content {
476 if content.GetType() == ContentTypeToolCall {
477 // Replace with validated tool call
478 if toolCallIndex < len(stepToolCalls) {
479 stepContent = append(stepContent, stepToolCalls[toolCallIndex])
480 toolCallIndex++
481 }
482 } else {
483 // Keep other content as-is
484 stepContent = append(stepContent, content)
485 }
486 }
487 // Add tool results
488 for _, result := range toolResults {
489 stepContent = append(stepContent, result)
490 }
491 currentStepMessages := toResponseMessages(stepContent)
492 responseMessages = append(responseMessages, currentStepMessages...)
493
494 stepResult := StepResult{
495 Response: Response{
496 Content: stepContent,
497 FinishReason: result.FinishReason,
498 Usage: result.Usage,
499 Warnings: result.Warnings,
500 ProviderMetadata: result.ProviderMetadata,
501 },
502 Messages: currentStepMessages,
503 }
504 steps = append(steps, stepResult)
505 shouldStop := isStopConditionMet(opts.StopWhen, steps)
506
507 if shouldStop || err != nil || len(stepToolCalls) == 0 || result.FinishReason != FinishReasonToolCalls {
508 break
509 }
510 }
511
512 totalUsage := Usage{}
513
514 for _, step := range steps {
515 usage := step.Usage
516 totalUsage.InputTokens += usage.InputTokens
517 totalUsage.OutputTokens += usage.OutputTokens
518 totalUsage.ReasoningTokens += usage.ReasoningTokens
519 totalUsage.CacheCreationTokens += usage.CacheCreationTokens
520 totalUsage.CacheReadTokens += usage.CacheReadTokens
521 totalUsage.TotalTokens += usage.TotalTokens
522 }
523
524 agentResult := &AgentResult{
525 Steps: steps,
526 Response: steps[len(steps)-1].Response,
527 TotalUsage: totalUsage,
528 }
529 return agentResult, nil
530}
531
532func isStopConditionMet(conditions []StopCondition, steps []StepResult) bool {
533 if len(conditions) == 0 {
534 return false
535 }
536
537 for _, condition := range conditions {
538 if condition(steps) {
539 return true
540 }
541 }
542 return false
543}
544
545func toResponseMessages(content []Content) []Message {
546 var assistantParts []MessagePart
547 var toolParts []MessagePart
548
549 for _, c := range content {
550 switch c.GetType() {
551 case ContentTypeText:
552 text, ok := AsContentType[TextContent](c)
553 if !ok {
554 continue
555 }
556 assistantParts = append(assistantParts, TextPart{
557 Text: text.Text,
558 ProviderOptions: ProviderOptions(text.ProviderMetadata),
559 })
560 case ContentTypeReasoning:
561 reasoning, ok := AsContentType[ReasoningContent](c)
562 if !ok {
563 continue
564 }
565 assistantParts = append(assistantParts, ReasoningPart{
566 Text: reasoning.Text,
567 ProviderOptions: ProviderOptions(reasoning.ProviderMetadata),
568 })
569 case ContentTypeToolCall:
570 toolCall, ok := AsContentType[ToolCallContent](c)
571 if !ok {
572 continue
573 }
574 assistantParts = append(assistantParts, ToolCallPart{
575 ToolCallID: toolCall.ToolCallID,
576 ToolName: toolCall.ToolName,
577 Input: toolCall.Input,
578 ProviderExecuted: toolCall.ProviderExecuted,
579 ProviderOptions: ProviderOptions(toolCall.ProviderMetadata),
580 })
581 case ContentTypeFile:
582 file, ok := AsContentType[FileContent](c)
583 if !ok {
584 continue
585 }
586 assistantParts = append(assistantParts, FilePart{
587 Data: file.Data,
588 MediaType: file.MediaType,
589 ProviderOptions: ProviderOptions(file.ProviderMetadata),
590 })
591 case ContentTypeSource:
592 // Sources are metadata about references used to generate the response.
593 // They don't need to be included in the conversation messages.
594 continue
595 case ContentTypeToolResult:
596 result, ok := AsContentType[ToolResultContent](c)
597 if !ok {
598 continue
599 }
600 toolParts = append(toolParts, ToolResultPart{
601 ToolCallID: result.ToolCallID,
602 Output: result.Result,
603 ProviderOptions: ProviderOptions(result.ProviderMetadata),
604 })
605 }
606 }
607
608 var messages []Message
609 if len(assistantParts) > 0 {
610 messages = append(messages, Message{
611 Role: MessageRoleAssistant,
612 Content: assistantParts,
613 })
614 }
615 if len(toolParts) > 0 {
616 messages = append(messages, Message{
617 Role: MessageRoleTool,
618 Content: toolParts,
619 })
620 }
621 return messages
622}
623
624func (a *agent) executeTools(ctx context.Context, allTools []AgentTool, toolCalls []ToolCallContent, toolResultCallback func(result ToolResultContent) error) ([]ToolResultContent, error) {
625 if len(toolCalls) == 0 {
626 return nil, nil
627 }
628
629 // Create a map for quick tool lookup
630 toolMap := make(map[string]AgentTool)
631 for _, tool := range allTools {
632 toolMap[tool.Info().Name] = tool
633 }
634
635 // Execute all tool calls sequentially in order
636 results := make([]ToolResultContent, 0, len(toolCalls))
637
638 for _, toolCall := range toolCalls {
639 // Skip invalid tool calls - create error result
640 if toolCall.Invalid {
641 result := ToolResultContent{
642 ToolCallID: toolCall.ToolCallID,
643 ToolName: toolCall.ToolName,
644 Result: ToolResultOutputContentError{
645 Error: toolCall.ValidationError,
646 },
647 ProviderExecuted: false,
648 }
649 results = append(results, result)
650 if toolResultCallback != nil {
651 if err := toolResultCallback(result); err != nil {
652 return nil, err
653 }
654 }
655 continue
656 }
657
658 tool, exists := toolMap[toolCall.ToolName]
659 if !exists {
660 result := ToolResultContent{
661 ToolCallID: toolCall.ToolCallID,
662 ToolName: toolCall.ToolName,
663 Result: ToolResultOutputContentError{
664 Error: errors.New("Error: Tool not found: " + toolCall.ToolName),
665 },
666 ProviderExecuted: false,
667 }
668 results = append(results, result)
669 if toolResultCallback != nil {
670 if err := toolResultCallback(result); err != nil {
671 return nil, err
672 }
673 }
674 continue
675 }
676
677 // Execute the tool
678 toolResult, err := tool.Run(ctx, ToolCall{
679 ID: toolCall.ToolCallID,
680 Name: toolCall.ToolName,
681 Input: toolCall.Input,
682 })
683 if err != nil {
684 result := ToolResultContent{
685 ToolCallID: toolCall.ToolCallID,
686 ToolName: toolCall.ToolName,
687 Result: ToolResultOutputContentError{
688 Error: err,
689 },
690 ClientMetadata: toolResult.Metadata,
691 ProviderExecuted: false,
692 }
693 if toolResultCallback != nil {
694 if cbErr := toolResultCallback(result); cbErr != nil {
695 return nil, cbErr
696 }
697 }
698 return nil, err
699 }
700
701 var result ToolResultContent
702 if toolResult.IsError {
703 result = ToolResultContent{
704 ToolCallID: toolCall.ToolCallID,
705 ToolName: toolCall.ToolName,
706 Result: ToolResultOutputContentError{
707 Error: errors.New(toolResult.Content),
708 },
709 ClientMetadata: toolResult.Metadata,
710 ProviderExecuted: false,
711 }
712 } else {
713 result = ToolResultContent{
714 ToolCallID: toolCall.ToolCallID,
715 ToolName: toolCall.ToolName,
716 Result: ToolResultOutputContentText{
717 Text: toolResult.Content,
718 },
719 ClientMetadata: toolResult.Metadata,
720 ProviderExecuted: false,
721 }
722 }
723 results = append(results, result)
724 if toolResultCallback != nil {
725 if err := toolResultCallback(result); err != nil {
726 return nil, err
727 }
728 }
729 }
730
731 return results, nil
732}
733
734// executeSingleTool executes a single tool and returns its result and a critical error flag.
735func (a *agent) executeSingleTool(ctx context.Context, toolMap map[string]AgentTool, toolCall ToolCallContent, toolResultCallback func(result ToolResultContent) error) (ToolResultContent, bool) {
736 result := ToolResultContent{
737 ToolCallID: toolCall.ToolCallID,
738 ToolName: toolCall.ToolName,
739 ProviderExecuted: false,
740 }
741
742 // Skip invalid tool calls - create error result (not critical)
743 if toolCall.Invalid {
744 result.Result = ToolResultOutputContentError{
745 Error: toolCall.ValidationError,
746 }
747 if toolResultCallback != nil {
748 _ = toolResultCallback(result)
749 }
750 return result, false
751 }
752
753 tool, exists := toolMap[toolCall.ToolName]
754 if !exists {
755 result.Result = ToolResultOutputContentError{
756 Error: errors.New("Error: Tool not found: " + toolCall.ToolName),
757 }
758 if toolResultCallback != nil {
759 _ = toolResultCallback(result)
760 }
761 return result, false
762 }
763
764 // Execute the tool
765 toolResult, err := tool.Run(ctx, ToolCall{
766 ID: toolCall.ToolCallID,
767 Name: toolCall.ToolName,
768 Input: toolCall.Input,
769 })
770 if err != nil {
771 result.Result = ToolResultOutputContentError{
772 Error: err,
773 }
774 result.ClientMetadata = toolResult.Metadata
775 if toolResultCallback != nil {
776 _ = toolResultCallback(result)
777 }
778 // This is a critical error - tool.Run() failed
779 return result, true
780 }
781
782 result.ClientMetadata = toolResult.Metadata
783 if toolResult.IsError {
784 result.Result = ToolResultOutputContentError{
785 Error: errors.New(toolResult.Content),
786 }
787 } else {
788 result.Result = ToolResultOutputContentText{
789 Text: toolResult.Content,
790 }
791 }
792 if toolResultCallback != nil {
793 _ = toolResultCallback(result)
794 }
795 // Not a critical error - tool ran successfully (even if it reported an error state)
796 return result, false
797}
798
799// Stream implements Agent.
800func (a *agent) Stream(ctx context.Context, opts AgentStreamCall) (*AgentResult, error) {
801 // Convert AgentStreamCall to AgentCall for preparation
802 call := AgentCall{
803 Prompt: opts.Prompt,
804 Files: opts.Files,
805 Messages: opts.Messages,
806 MaxOutputTokens: opts.MaxOutputTokens,
807 Temperature: opts.Temperature,
808 TopP: opts.TopP,
809 TopK: opts.TopK,
810 PresencePenalty: opts.PresencePenalty,
811 FrequencyPenalty: opts.FrequencyPenalty,
812 ActiveTools: opts.ActiveTools,
813 ProviderOptions: opts.ProviderOptions,
814 MaxRetries: opts.MaxRetries,
815 OnRetry: opts.OnRetry,
816 StopWhen: opts.StopWhen,
817 PrepareStep: opts.PrepareStep,
818 RepairToolCall: opts.RepairToolCall,
819 }
820
821 call = a.prepareCall(call)
822
823 initialPrompt, err := a.createPrompt(a.settings.systemPrompt, call.Prompt, call.Messages, call.Files...)
824 if err != nil {
825 return nil, err
826 }
827
828 var responseMessages []Message
829 var steps []StepResult
830 var totalUsage Usage
831
832 // Start agent stream
833 if opts.OnAgentStart != nil {
834 opts.OnAgentStart()
835 }
836
837 for stepNumber := 0; ; stepNumber++ {
838 stepInputMessages := append(initialPrompt, responseMessages...)
839 stepModel := a.settings.model
840 stepSystemPrompt := a.settings.systemPrompt
841 stepActiveTools := call.ActiveTools
842 stepToolChoice := ToolChoiceAuto
843 disableAllTools := false
844 stepTools := a.settings.tools
845 // Apply step preparation if provided
846 if call.PrepareStep != nil {
847 updatedCtx, prepared, err := call.PrepareStep(ctx, PrepareStepFunctionOptions{
848 Model: stepModel,
849 Steps: steps,
850 StepNumber: stepNumber,
851 Messages: stepInputMessages,
852 })
853 if err != nil {
854 return nil, err
855 }
856
857 ctx = updatedCtx
858
859 if prepared.Messages != nil {
860 stepInputMessages = prepared.Messages
861 }
862 if prepared.Model != nil {
863 stepModel = prepared.Model
864 }
865 if prepared.System != nil {
866 stepSystemPrompt = *prepared.System
867 }
868 if prepared.ToolChoice != nil {
869 stepToolChoice = *prepared.ToolChoice
870 }
871 if len(prepared.ActiveTools) > 0 {
872 stepActiveTools = prepared.ActiveTools
873 }
874 disableAllTools = prepared.DisableAllTools
875 if prepared.Tools != nil {
876 stepTools = prepared.Tools
877 }
878 }
879
880 // Recreate prompt with potentially modified system prompt
881 if stepSystemPrompt != a.settings.systemPrompt {
882 stepPrompt, err := a.createPrompt(stepSystemPrompt, call.Prompt, call.Messages, call.Files...)
883 if err != nil {
884 return nil, err
885 }
886 if len(stepInputMessages) > 0 && len(stepPrompt) > 0 {
887 stepInputMessages[0] = stepPrompt[0]
888 }
889 }
890
891 preparedTools := a.prepareTools(stepTools, stepActiveTools, disableAllTools)
892
893 // Start step stream
894 if opts.OnStepStart != nil {
895 _ = opts.OnStepStart(stepNumber)
896 }
897
898 // Create streaming call
899 streamCall := Call{
900 Prompt: stepInputMessages,
901 MaxOutputTokens: call.MaxOutputTokens,
902 Temperature: call.Temperature,
903 TopP: call.TopP,
904 TopK: call.TopK,
905 PresencePenalty: call.PresencePenalty,
906 FrequencyPenalty: call.FrequencyPenalty,
907 Tools: preparedTools,
908 ToolChoice: &stepToolChoice,
909 ProviderOptions: call.ProviderOptions,
910 }
911
912 // Execute step with retry logic wrapping both stream creation and processing
913 retryOptions := DefaultRetryOptions()
914 if call.MaxRetries != nil {
915 retryOptions.MaxRetries = *call.MaxRetries
916 }
917 retryOptions.OnRetry = call.OnRetry
918 retry := RetryWithExponentialBackoffRespectingRetryHeaders[stepExecutionResult](retryOptions)
919
920 result, err := retry(ctx, func() (stepExecutionResult, error) {
921 // Create the stream
922 stream, err := stepModel.Stream(ctx, streamCall)
923 if err != nil {
924 return stepExecutionResult{}, err
925 }
926
927 // Process the stream
928 result, err := a.processStepStream(ctx, stream, opts, steps, stepTools)
929 if err != nil {
930 return stepExecutionResult{}, err
931 }
932
933 return result, nil
934 })
935 if err != nil {
936 if opts.OnError != nil {
937 opts.OnError(err)
938 }
939 return nil, err
940 }
941
942 steps = append(steps, result.StepResult)
943 totalUsage = addUsage(totalUsage, result.StepResult.Usage)
944
945 // Call step finished callback
946 if opts.OnStepFinish != nil {
947 _ = opts.OnStepFinish(result.StepResult)
948 }
949
950 // Add step messages to response messages
951 stepMessages := toResponseMessages(result.StepResult.Content)
952 responseMessages = append(responseMessages, stepMessages...)
953
954 // Check stop conditions
955 shouldStop := isStopConditionMet(call.StopWhen, steps)
956 if shouldStop || !result.ShouldContinue {
957 break
958 }
959 }
960
961 // Finish agent stream
962 agentResult := &AgentResult{
963 Steps: steps,
964 Response: steps[len(steps)-1].Response,
965 TotalUsage: totalUsage,
966 }
967
968 if opts.OnFinish != nil {
969 opts.OnFinish(agentResult)
970 }
971
972 if opts.OnAgentFinish != nil {
973 _ = opts.OnAgentFinish(agentResult)
974 }
975
976 return agentResult, nil
977}
978
979func (a *agent) prepareTools(tools []AgentTool, activeTools []string, disableAllTools bool) []Tool {
980 preparedTools := make([]Tool, 0, len(tools))
981
982 // If explicitly disabling all tools, return no tools
983 if disableAllTools {
984 return preparedTools
985 }
986
987 for _, tool := range tools {
988 // If activeTools has items, only include tools in the list
989 // If activeTools is empty, include all tools
990 if len(activeTools) > 0 && !slices.Contains(activeTools, tool.Info().Name) {
991 continue
992 }
993 info := tool.Info()
994 preparedTools = append(preparedTools, FunctionTool{
995 Name: info.Name,
996 Description: info.Description,
997 InputSchema: map[string]any{
998 "type": "object",
999 "properties": info.Parameters,
1000 "required": info.Required,
1001 },
1002 ProviderOptions: tool.ProviderOptions(),
1003 })
1004 }
1005 return preparedTools
1006}
1007
1008// validateAndRepairToolCall validates a tool call and attempts repair if validation fails.
1009func (a *agent) validateAndRepairToolCall(ctx context.Context, toolCall ToolCallContent, availableTools []AgentTool, systemPrompt string, messages []Message, repairFunc RepairToolCallFunction) ToolCallContent {
1010 if err := a.validateToolCall(toolCall, availableTools); err == nil {
1011 return toolCall
1012 } else { //nolint: revive
1013 if repairFunc != nil {
1014 repairOptions := ToolCallRepairOptions{
1015 OriginalToolCall: toolCall,
1016 ValidationError: err,
1017 AvailableTools: availableTools,
1018 SystemPrompt: systemPrompt,
1019 Messages: messages,
1020 }
1021
1022 if repairedToolCall, repairErr := repairFunc(ctx, repairOptions); repairErr == nil && repairedToolCall != nil {
1023 if validateErr := a.validateToolCall(*repairedToolCall, availableTools); validateErr == nil {
1024 return *repairedToolCall
1025 }
1026 }
1027 }
1028
1029 invalidToolCall := toolCall
1030 invalidToolCall.Invalid = true
1031 invalidToolCall.ValidationError = err
1032 return invalidToolCall
1033 }
1034}
1035
1036// validateToolCall validates a tool call against available tools and their schemas.
1037func (a *agent) validateToolCall(toolCall ToolCallContent, availableTools []AgentTool) error {
1038 var tool AgentTool
1039 for _, t := range availableTools {
1040 if t.Info().Name == toolCall.ToolName {
1041 tool = t
1042 break
1043 }
1044 }
1045
1046 if tool == nil {
1047 return fmt.Errorf("tool not found: %s", toolCall.ToolName)
1048 }
1049
1050 // Validate JSON parsing
1051 var input map[string]any
1052 if err := json.Unmarshal([]byte(toolCall.Input), &input); err != nil {
1053 return fmt.Errorf("invalid JSON input: %w", err)
1054 }
1055
1056 // Basic schema validation (check required fields)
1057 // TODO: more robust schema validation using JSON Schema or similar
1058 toolInfo := tool.Info()
1059 for _, required := range toolInfo.Required {
1060 if _, exists := input[required]; !exists {
1061 return fmt.Errorf("missing required parameter: %s", required)
1062 }
1063 }
1064 return nil
1065}
1066
1067func (a *agent) createPrompt(system, prompt string, messages []Message, files ...FilePart) (Prompt, error) {
1068 if prompt == "" {
1069 return nil, &Error{Title: "invalid argument", Message: "prompt can't be empty"}
1070 }
1071
1072 var preparedPrompt Prompt
1073
1074 if system != "" {
1075 preparedPrompt = append(preparedPrompt, NewSystemMessage(system))
1076 }
1077 preparedPrompt = append(preparedPrompt, messages...)
1078 preparedPrompt = append(preparedPrompt, NewUserMessage(prompt, files...))
1079 return preparedPrompt, nil
1080}
1081
1082// WithSystemPrompt sets the system prompt for the agent.
1083func WithSystemPrompt(prompt string) AgentOption {
1084 return func(s *agentSettings) {
1085 s.systemPrompt = prompt
1086 }
1087}
1088
1089// WithMaxOutputTokens sets the maximum output tokens for the agent.
1090func WithMaxOutputTokens(tokens int64) AgentOption {
1091 return func(s *agentSettings) {
1092 s.maxOutputTokens = &tokens
1093 }
1094}
1095
1096// WithTemperature sets the temperature for the agent.
1097func WithTemperature(temp float64) AgentOption {
1098 return func(s *agentSettings) {
1099 s.temperature = &temp
1100 }
1101}
1102
1103// WithTopP sets the top-p value for the agent.
1104func WithTopP(topP float64) AgentOption {
1105 return func(s *agentSettings) {
1106 s.topP = &topP
1107 }
1108}
1109
1110// WithTopK sets the top-k value for the agent.
1111func WithTopK(topK int64) AgentOption {
1112 return func(s *agentSettings) {
1113 s.topK = &topK
1114 }
1115}
1116
1117// WithPresencePenalty sets the presence penalty for the agent.
1118func WithPresencePenalty(penalty float64) AgentOption {
1119 return func(s *agentSettings) {
1120 s.presencePenalty = &penalty
1121 }
1122}
1123
1124// WithFrequencyPenalty sets the frequency penalty for the agent.
1125func WithFrequencyPenalty(penalty float64) AgentOption {
1126 return func(s *agentSettings) {
1127 s.frequencyPenalty = &penalty
1128 }
1129}
1130
1131// WithTools sets the tools for the agent.
1132func WithTools(tools ...AgentTool) AgentOption {
1133 return func(s *agentSettings) {
1134 s.tools = append(s.tools, tools...)
1135 }
1136}
1137
1138// WithStopConditions sets the stop conditions for the agent.
1139func WithStopConditions(conditions ...StopCondition) AgentOption {
1140 return func(s *agentSettings) {
1141 s.stopWhen = append(s.stopWhen, conditions...)
1142 }
1143}
1144
1145// WithPrepareStep sets the prepare step function for the agent.
1146func WithPrepareStep(fn PrepareStepFunction) AgentOption {
1147 return func(s *agentSettings) {
1148 s.prepareStep = fn
1149 }
1150}
1151
1152// WithRepairToolCall sets the repair tool call function for the agent.
1153func WithRepairToolCall(fn RepairToolCallFunction) AgentOption {
1154 return func(s *agentSettings) {
1155 s.repairToolCall = fn
1156 }
1157}
1158
1159// WithMaxRetries sets the maximum number of retries for the agent.
1160func WithMaxRetries(maxRetries int) AgentOption {
1161 return func(s *agentSettings) {
1162 s.maxRetries = &maxRetries
1163 }
1164}
1165
1166// WithOnRetry sets the retry callback for the agent.
1167func WithOnRetry(callback OnRetryCallback) AgentOption {
1168 return func(s *agentSettings) {
1169 s.onRetry = callback
1170 }
1171}
1172
1173// processStepStream processes a single step's stream and returns the step result.
1174func (a *agent) processStepStream(ctx context.Context, stream StreamResponse, opts AgentStreamCall, _ []StepResult, stepTools []AgentTool) (stepExecutionResult, error) {
1175 var stepContent []Content
1176 var stepToolCalls []ToolCallContent
1177 var stepUsage Usage
1178 stepFinishReason := FinishReasonUnknown
1179 var stepWarnings []CallWarning
1180 var stepProviderMetadata ProviderMetadata
1181
1182 activeToolCalls := make(map[string]*ToolCallContent)
1183 activeTextContent := make(map[string]string)
1184 type reasoningContent struct {
1185 content string
1186 options ProviderMetadata
1187 }
1188 activeReasoningContent := make(map[string]reasoningContent)
1189
1190 // Set up concurrent tool execution
1191 type toolExecutionRequest struct {
1192 toolCall ToolCallContent
1193 parallel bool
1194 }
1195 toolChan := make(chan toolExecutionRequest, 10)
1196 var toolExecutionWg sync.WaitGroup
1197 var toolStateMu sync.Mutex
1198 toolResults := make([]ToolResultContent, 0)
1199 var toolExecutionErr error
1200
1201 // Create a map for quick tool lookup
1202 toolMap := make(map[string]AgentTool)
1203 for _, tool := range stepTools {
1204 toolMap[tool.Info().Name] = tool
1205 }
1206
1207 // Semaphores for controlling parallelism
1208 parallelSem := make(chan struct{}, 5)
1209 var sequentialMu sync.Mutex
1210
1211 // Single coordinator goroutine that dispatches tools
1212 toolExecutionWg.Go(func() {
1213 for req := range toolChan {
1214 if req.parallel {
1215 parallelSem <- struct{}{}
1216 toolExecutionWg.Go(func() {
1217 defer func() { <-parallelSem }()
1218 result, isCriticalError := a.executeSingleTool(ctx, toolMap, req.toolCall, opts.OnToolResult)
1219 toolStateMu.Lock()
1220 toolResults = append(toolResults, result)
1221 if isCriticalError && toolExecutionErr == nil {
1222 if errorResult, ok := result.Result.(ToolResultOutputContentError); ok && errorResult.Error != nil {
1223 toolExecutionErr = errorResult.Error
1224 }
1225 }
1226 toolStateMu.Unlock()
1227 })
1228 } else {
1229 sequentialMu.Lock()
1230 result, isCriticalError := a.executeSingleTool(ctx, toolMap, req.toolCall, opts.OnToolResult)
1231 toolStateMu.Lock()
1232 toolResults = append(toolResults, result)
1233 if isCriticalError && toolExecutionErr == nil {
1234 if errorResult, ok := result.Result.(ToolResultOutputContentError); ok && errorResult.Error != nil {
1235 toolExecutionErr = errorResult.Error
1236 }
1237 }
1238 toolStateMu.Unlock()
1239 sequentialMu.Unlock()
1240 }
1241 }
1242 })
1243
1244 // Process stream parts
1245 for part := range stream {
1246 // Forward all parts to chunk callback
1247 if opts.OnChunk != nil {
1248 err := opts.OnChunk(part)
1249 if err != nil {
1250 return stepExecutionResult{}, err
1251 }
1252 }
1253
1254 switch part.Type {
1255 case StreamPartTypeWarnings:
1256 stepWarnings = part.Warnings
1257 if opts.OnWarnings != nil {
1258 err := opts.OnWarnings(part.Warnings)
1259 if err != nil {
1260 return stepExecutionResult{}, err
1261 }
1262 }
1263
1264 case StreamPartTypeTextStart:
1265 activeTextContent[part.ID] = ""
1266 if opts.OnTextStart != nil {
1267 err := opts.OnTextStart(part.ID)
1268 if err != nil {
1269 return stepExecutionResult{}, err
1270 }
1271 }
1272
1273 case StreamPartTypeTextDelta:
1274 if _, exists := activeTextContent[part.ID]; exists {
1275 activeTextContent[part.ID] += part.Delta
1276 }
1277 if opts.OnTextDelta != nil {
1278 err := opts.OnTextDelta(part.ID, part.Delta)
1279 if err != nil {
1280 return stepExecutionResult{}, err
1281 }
1282 }
1283
1284 case StreamPartTypeTextEnd:
1285 if text, exists := activeTextContent[part.ID]; exists {
1286 stepContent = append(stepContent, TextContent{
1287 Text: text,
1288 ProviderMetadata: part.ProviderMetadata,
1289 })
1290 delete(activeTextContent, part.ID)
1291 }
1292 if opts.OnTextEnd != nil {
1293 err := opts.OnTextEnd(part.ID)
1294 if err != nil {
1295 return stepExecutionResult{}, err
1296 }
1297 }
1298
1299 case StreamPartTypeReasoningStart:
1300 activeReasoningContent[part.ID] = reasoningContent{content: part.Delta, options: part.ProviderMetadata}
1301 if opts.OnReasoningStart != nil {
1302 content := ReasoningContent{
1303 Text: part.Delta,
1304 ProviderMetadata: part.ProviderMetadata,
1305 }
1306 err := opts.OnReasoningStart(part.ID, content)
1307 if err != nil {
1308 return stepExecutionResult{}, err
1309 }
1310 }
1311
1312 case StreamPartTypeReasoningDelta:
1313 if active, exists := activeReasoningContent[part.ID]; exists {
1314 active.content += part.Delta
1315 active.options = part.ProviderMetadata
1316 activeReasoningContent[part.ID] = active
1317 }
1318 if opts.OnReasoningDelta != nil {
1319 err := opts.OnReasoningDelta(part.ID, part.Delta)
1320 if err != nil {
1321 return stepExecutionResult{}, err
1322 }
1323 }
1324
1325 case StreamPartTypeReasoningEnd:
1326 if active, exists := activeReasoningContent[part.ID]; exists {
1327 if part.ProviderMetadata != nil {
1328 active.options = part.ProviderMetadata
1329 }
1330 content := ReasoningContent{
1331 Text: active.content,
1332 ProviderMetadata: active.options,
1333 }
1334 stepContent = append(stepContent, content)
1335 if opts.OnReasoningEnd != nil {
1336 err := opts.OnReasoningEnd(part.ID, content)
1337 if err != nil {
1338 return stepExecutionResult{}, err
1339 }
1340 }
1341 delete(activeReasoningContent, part.ID)
1342 }
1343
1344 case StreamPartTypeToolInputStart:
1345 activeToolCalls[part.ID] = &ToolCallContent{
1346 ToolCallID: part.ID,
1347 ToolName: part.ToolCallName,
1348 Input: "",
1349 ProviderExecuted: part.ProviderExecuted,
1350 }
1351 if opts.OnToolInputStart != nil {
1352 err := opts.OnToolInputStart(part.ID, part.ToolCallName)
1353 if err != nil {
1354 return stepExecutionResult{}, err
1355 }
1356 }
1357
1358 case StreamPartTypeToolInputDelta:
1359 if toolCall, exists := activeToolCalls[part.ID]; exists {
1360 toolCall.Input += part.Delta
1361 }
1362 if opts.OnToolInputDelta != nil {
1363 err := opts.OnToolInputDelta(part.ID, part.Delta)
1364 if err != nil {
1365 return stepExecutionResult{}, err
1366 }
1367 }
1368
1369 case StreamPartTypeToolInputEnd:
1370 if opts.OnToolInputEnd != nil {
1371 err := opts.OnToolInputEnd(part.ID)
1372 if err != nil {
1373 return stepExecutionResult{}, err
1374 }
1375 }
1376
1377 case StreamPartTypeToolCall:
1378 toolCall := ToolCallContent{
1379 ToolCallID: part.ID,
1380 ToolName: part.ToolCallName,
1381 Input: part.ToolCallInput,
1382 ProviderExecuted: part.ProviderExecuted,
1383 ProviderMetadata: part.ProviderMetadata,
1384 }
1385
1386 // Validate and potentially repair the tool call
1387 validatedToolCall := a.validateAndRepairToolCall(ctx, toolCall, stepTools, a.settings.systemPrompt, nil, opts.RepairToolCall)
1388 stepToolCalls = append(stepToolCalls, validatedToolCall)
1389 stepContent = append(stepContent, validatedToolCall)
1390
1391 if opts.OnToolCall != nil {
1392 err := opts.OnToolCall(validatedToolCall)
1393 if err != nil {
1394 return stepExecutionResult{}, err
1395 }
1396 }
1397
1398 // Determine if tool can run in parallel
1399 isParallel := false
1400 if tool, exists := toolMap[validatedToolCall.ToolName]; exists {
1401 isParallel = tool.Info().Parallel
1402 }
1403
1404 // Send tool call to execution channel
1405 toolChan <- toolExecutionRequest{toolCall: validatedToolCall, parallel: isParallel}
1406
1407 // Clean up active tool call
1408 delete(activeToolCalls, part.ID)
1409
1410 case StreamPartTypeSource:
1411 sourceContent := SourceContent{
1412 SourceType: part.SourceType,
1413 ID: part.ID,
1414 URL: part.URL,
1415 Title: part.Title,
1416 ProviderMetadata: part.ProviderMetadata,
1417 }
1418 stepContent = append(stepContent, sourceContent)
1419 if opts.OnSource != nil {
1420 err := opts.OnSource(sourceContent)
1421 if err != nil {
1422 return stepExecutionResult{}, err
1423 }
1424 }
1425
1426 case StreamPartTypeFinish:
1427 stepUsage = part.Usage
1428 stepFinishReason = part.FinishReason
1429 stepProviderMetadata = part.ProviderMetadata
1430 if opts.OnStreamFinish != nil {
1431 err := opts.OnStreamFinish(part.Usage, part.FinishReason, part.ProviderMetadata)
1432 if err != nil {
1433 return stepExecutionResult{}, err
1434 }
1435 }
1436
1437 case StreamPartTypeError:
1438 return stepExecutionResult{}, part.Error
1439 }
1440 }
1441
1442 // Close the tool execution channel and wait for all executions to complete
1443 close(toolChan)
1444 toolExecutionWg.Wait()
1445
1446 // Check for tool execution errors
1447 if toolExecutionErr != nil {
1448 return stepExecutionResult{}, toolExecutionErr
1449 }
1450
1451 // Add tool results to content if any
1452 if len(toolResults) > 0 {
1453 for _, result := range toolResults {
1454 stepContent = append(stepContent, result)
1455 }
1456 }
1457
1458 stepResult := StepResult{
1459 Response: Response{
1460 Content: stepContent,
1461 FinishReason: stepFinishReason,
1462 Usage: stepUsage,
1463 Warnings: stepWarnings,
1464 ProviderMetadata: stepProviderMetadata,
1465 },
1466 Messages: toResponseMessages(stepContent),
1467 }
1468
1469 // Determine if we should continue (has tool calls and not stopped)
1470 shouldContinue := len(stepToolCalls) > 0 && stepFinishReason == FinishReasonToolCalls
1471
1472 return stepExecutionResult{
1473 StepResult: stepResult,
1474 ShouldContinue: shouldContinue,
1475 }, nil
1476}
1477
1478func addUsage(a, b Usage) Usage {
1479 return Usage{
1480 InputTokens: a.InputTokens + b.InputTokens,
1481 OutputTokens: a.OutputTokens + b.OutputTokens,
1482 TotalTokens: a.TotalTokens + b.TotalTokens,
1483 ReasoningTokens: a.ReasoningTokens + b.ReasoningTokens,
1484 CacheCreationTokens: a.CacheCreationTokens + b.CacheCreationTokens,
1485 CacheReadTokens: a.CacheReadTokens + b.CacheReadTokens,
1486 }
1487}
1488
1489// WithHeaders sets the headers for the agent.
1490func WithHeaders(headers map[string]string) AgentOption {
1491 return func(s *agentSettings) {
1492 s.headers = headers
1493 }
1494}
1495
1496// WithProviderOptions sets the provider options for the agent.
1497func WithProviderOptions(providerOptions ProviderOptions) AgentOption {
1498 return func(s *agentSettings) {
1499 s.providerOptions = providerOptions
1500 }
1501}