03给 Agent 装上工具

/*
 * Copyright 2024 CloudWeGo Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package tool

import (
  "context"

  "github.com/cloudwego/eino/schema"
)

// BaseTool provides the metadata that a ChatModel uses to decide whether and
// how to call a tool. Info returns a [schema.ToolInfo] containing the tool
// name, description, and parameter JSON schema.
//
// BaseTool alone is sufficient when passing tool definitions to a ChatModel
// via WithTools — the model only needs the schema to generate tool calls.
// To also execute the tool, implement [InvokableTool] or [StreamableTool].
type BaseTool interface {
  Info(ctx context.Context) (*schema.ToolInfo, error)
}

// InvokableTool is a tool that can be executed by ToolsNode.
//
// InvokableRun receives the model's tool call arguments as a JSON-encoded
// string and returns a plain string result that is sent back to the model as
// a tool message. The framework handles JSON decoding automatically when using
// … 这只是文件开头 40 行，并非完整声明；点击上方「浏览完整文件」

type ToolCallingChatModel interface {
    BaseChatModel
    WithTools(tools []*schema.ToolInfo) (ToolCallingChatModel, error)
}

/*
 * Copyright 2025 CloudWeGo Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package adk

import (
  "bytes"
  "context"
  "encoding/gob"
  "errors"
  "fmt"
  "math"
  "runtime/debug"
  "strings"
  "sync"
  "sync/atomic"

  "github.com/bytedance/sonic"

  "github.com/cloudwego/eino/adk/internal"
  "github.com/cloudwego/eino/components/model"
  "github.com/cloudwego/eino/components/prompt"
  "github.com/cloudwego/eino/components/tool"
  "github.com/cloudwego/eino/compose"
  "github.com/cloudwego/eino/internal/safe"
  "github.com/cloudwego/eino/schema"
)
// … 这只是文件开头 40 行，并非完整声明；点击上方「浏览完整文件」

// TypedChatModelAgentConfig is the generic configuration for ChatModelAgent.
type TypedChatModelAgentConfig[M MessageType] struct {
  // Name of the agent. Better be unique across all agents.
  // Optional. If empty, the agent can still run standalone but cannot be used as
  // a sub-agent tool via NewAgentTool (which requires a non-empty Name).
  Name string
  // Description of the agent's capabilities.
  // Helps other agents determine whether to transfer tasks to this agent.
  // Optional. If empty, the agent can still run standalone but cannot be used as
  // a sub-agent tool via NewAgentTool (which requires a non-empty Description).
  Description string
  // Instruction used as the system prompt for this agent.
  // Optional. If empty, no system prompt will be used.
  // Supports f-string placeholders for session values in default GenModelInput, for example:
  // "You are a helpful assistant. The current time is {Time}. The current user is {User}."
  // These placeholders will be replaced with session values for "Time" and "User".
  Instruction string

  // Model is the chat model used by the agent.
  // If your ChatModelAgent uses any tools, this model must support the model.WithTools
  // call option, as that's how ChatModelAgent configures the model with tool information.
  Model model.BaseModel[M]

  ToolsConfig ToolsConfig

  // GenModelInput transforms instructions and input messages into the model's input format.
  // Optional. Defaults to defaultGenModelInput which combines instruction and messages.
  GenModelInput TypedGenModelInput[M]

  // Exit defines the tool used to terminate the agent process.
  // Optional. If nil, no Exit Action will be generated.
  // You can use the provided 'ExitTool' implementation directly.
  //
  // NOT RECOMMENDED: Agent transfer with full context sharing between agents has not proven
  // to be more effective empirically. Consider using ChatModelAgent with AgentTool
  // or DeepAgent instead for most multi-agent scenarios.
  Exit tool.BaseTool

  // OutputKey stores the agent's response in the session.
  // Optional. When set, stores output via AddSessionValue(ctx, outputKey, msg.Content).
  //
  // NOT RECOMMENDED: Agent transfer with full context sharing between agents has not proven
  // to be more effective empirically. Consider using ChatModelAgent with AgentTool
  // or DeepAgent instead for most multi-agent scenarios.
  OutputKey string

  // MaxIterations defines the upper limit of ChatModel generation cycles.
  // The agent will terminate with an error if this limit is exceeded.
// … 省略 109 行；完整声明 L259–415，点击上方「浏览完整文件」

type ExitTool struct{}

type ToolsConfig struct {
  compose.ToolsNodeConfig

  // ReturnDirectly specifies tools that cause the agent to return immediately when called.
  // The map keys are tool names indicate whether the tool should trigger immediate return.
  ReturnDirectly map[string]bool

  // EmitInternalEvents indicates whether internal events from agentTool should be emitted
  // to the parent agent's AsyncGenerator, allowing real-time streaming of nested agent output
  // to the end-user via Runner.
  //
  // Note that these forwarded events are NOT recorded in the parent agent's runSession.
  // They are only emitted to the end-user and have no effect on the parent agent's state
  // or checkpoint.
  //
  // Action Scoping:
  // Actions emitted by the inner agent are scoped to the agent tool boundary:
  //   - Interrupted: Propagated via CompositeInterrupt to allow proper interrupt/resume
  //   - Exit, TransferToAgent, BreakLoop: Ignored outside the agent tool
  EmitInternalEvents bool
}