main: 增强工具调用与消息流程
- 支持 tool.call 和 tool.result 消息类型处理 - 引入 Tool 调度与执行逻辑，支持超时与结果截断 - 增加 ToolRegistry 和 ToolExecutor 管理工具定义与执行 - 更新上下文构建与消息映射逻辑，适配工具闭环处理 - 扩展配置与环境变量，支持 Tool 调用相关选项 - 增强单元测试覆盖工具调用与执行情景 - 更新文档和 OpenAPI，新增工具相关说明与模型定义
This commit is contained in:
23
app/Services/Tool/Tool.php
Normal file
23
app/Services/Tool/Tool.php
Normal file
@@ -0,0 +1,23 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Tool;
|
||||
|
||||
interface Tool
|
||||
{
|
||||
public function name(): string;
|
||||
|
||||
public function description(): string;
|
||||
|
||||
/**
|
||||
* OpenAI function 参数 JSON Schema。
|
||||
*
|
||||
* @return array<string, mixed>
|
||||
*/
|
||||
public function parameters(): array;
|
||||
|
||||
/**
|
||||
* @param array<string, mixed> $arguments
|
||||
* @return array<string, mixed>|string
|
||||
*/
|
||||
public function execute(array $arguments): array|string;
|
||||
}
|
||||
52
app/Services/Tool/ToolCall.php
Normal file
52
app/Services/Tool/ToolCall.php
Normal file
@@ -0,0 +1,52 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Tool;
|
||||
|
||||
/**
|
||||
* Tool 调用请求 DTO，携带父子 Run 关联信息与参数。
|
||||
*/
|
||||
final class ToolCall
|
||||
{
|
||||
/**
|
||||
* @param array<string, mixed> $arguments
|
||||
*/
|
||||
public function __construct(
|
||||
public string $runId,
|
||||
public string $parentRunId,
|
||||
public string $toolCallId,
|
||||
public string $name,
|
||||
public array $arguments,
|
||||
public string $rawArguments = '',
|
||||
) {
|
||||
}
|
||||
|
||||
/**
|
||||
* @param array<string, mixed> $payload
|
||||
*/
|
||||
public static function fromArray(array $payload): self
|
||||
{
|
||||
return new self(
|
||||
(string) $payload['run_id'],
|
||||
(string) $payload['parent_run_id'],
|
||||
(string) $payload['tool_call_id'],
|
||||
(string) $payload['name'],
|
||||
(array) ($payload['arguments'] ?? []),
|
||||
(string) ($payload['raw_arguments'] ?? '')
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* @return array<string, mixed>
|
||||
*/
|
||||
public function toArray(): array
|
||||
{
|
||||
return [
|
||||
'run_id' => $this->runId,
|
||||
'parent_run_id' => $this->parentRunId,
|
||||
'tool_call_id' => $this->toolCallId,
|
||||
'name' => $this->name,
|
||||
'arguments' => $this->arguments,
|
||||
'raw_arguments' => $this->rawArguments,
|
||||
];
|
||||
}
|
||||
}
|
||||
86
app/Services/Tool/ToolExecutor.php
Normal file
86
app/Services/Tool/ToolExecutor.php
Normal file
@@ -0,0 +1,86 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Tool;
|
||||
|
||||
use Illuminate\Support\Str;
|
||||
|
||||
/**
|
||||
* Tool 执行调度器，负责超时/结果截断等基础防护。
|
||||
*/
|
||||
class ToolExecutor
|
||||
{
|
||||
public function __construct(
|
||||
private readonly ToolRegistry $registry,
|
||||
private ?int $timeoutSeconds = null,
|
||||
private ?int $maxResultBytes = null,
|
||||
) {
|
||||
$this->timeoutSeconds = $this->timeoutSeconds ?? (int) config('agent.tools.timeout_seconds', 15);
|
||||
$this->maxResultBytes = $this->maxResultBytes ?? (int) config('agent.tools.result_max_bytes', 4096);
|
||||
}
|
||||
|
||||
public function execute(ToolCall $call): ToolResult
|
||||
{
|
||||
$tool = $this->registry->get($call->name);
|
||||
|
||||
if (! $tool) {
|
||||
return new ToolResult(
|
||||
$call->runId,
|
||||
$call->parentRunId,
|
||||
$call->toolCallId,
|
||||
$call->name,
|
||||
'FAILED',
|
||||
'',
|
||||
'TOOL_NOT_FOUND'
|
||||
);
|
||||
}
|
||||
|
||||
$started = microtime(true);
|
||||
|
||||
try {
|
||||
$result = $tool->execute($call->arguments);
|
||||
$output = is_string($result) ? $result : json_encode($result, JSON_UNESCAPED_UNICODE);
|
||||
} catch (\Throwable $exception) {
|
||||
return new ToolResult(
|
||||
$call->runId,
|
||||
$call->parentRunId,
|
||||
$call->toolCallId,
|
||||
$call->name,
|
||||
'FAILED',
|
||||
'',
|
||||
Str::limit($exception->getMessage(), 200)
|
||||
);
|
||||
}
|
||||
|
||||
$duration = microtime(true) - $started;
|
||||
$truncated = false;
|
||||
|
||||
if ($this->maxResultBytes > 0 && strlen($output) > $this->maxResultBytes) {
|
||||
$output = substr($output, 0, $this->maxResultBytes);
|
||||
$truncated = true;
|
||||
}
|
||||
|
||||
if ($this->timeoutSeconds > 0 && $duration > $this->timeoutSeconds) {
|
||||
return new ToolResult(
|
||||
$call->runId,
|
||||
$call->parentRunId,
|
||||
$call->toolCallId,
|
||||
$call->name,
|
||||
'TIMEOUT',
|
||||
$output,
|
||||
'TOOL_TIMEOUT',
|
||||
$truncated
|
||||
);
|
||||
}
|
||||
|
||||
return new ToolResult(
|
||||
$call->runId,
|
||||
$call->parentRunId,
|
||||
$call->toolCallId,
|
||||
$call->name,
|
||||
'SUCCESS',
|
||||
$output,
|
||||
null,
|
||||
$truncated
|
||||
);
|
||||
}
|
||||
}
|
||||
64
app/Services/Tool/ToolRegistry.php
Normal file
64
app/Services/Tool/ToolRegistry.php
Normal file
@@ -0,0 +1,64 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Tool;
|
||||
|
||||
use App\Services\Tool\Tools\GetTimeTool;
|
||||
|
||||
/**
|
||||
* Tool 注册表：管理已注册工具与 OpenAI 兼容的声明。
|
||||
*/
|
||||
class ToolRegistry
|
||||
{
|
||||
/**
|
||||
* @var array<string, Tool>
|
||||
*/
|
||||
private array $tools;
|
||||
|
||||
/**
|
||||
* @param array<int, Tool>|null $tools
|
||||
*/
|
||||
public function __construct(?array $tools = null)
|
||||
{
|
||||
$tools = $tools ?? [
|
||||
new GetTimeTool(),
|
||||
];
|
||||
|
||||
$this->tools = [];
|
||||
|
||||
foreach ($tools as $tool) {
|
||||
$this->tools[$tool->name()] = $tool;
|
||||
}
|
||||
}
|
||||
|
||||
public function get(string $name): ?Tool
|
||||
{
|
||||
return $this->tools[$name] ?? null;
|
||||
}
|
||||
|
||||
/**
|
||||
* @return array<int, Tool>
|
||||
*/
|
||||
public function all(): array
|
||||
{
|
||||
return array_values($this->tools);
|
||||
}
|
||||
|
||||
/**
|
||||
* 返回 OpenAI-compatible tools 描述。
|
||||
*
|
||||
* @return array<int, array<string, mixed>>
|
||||
*/
|
||||
public function openAiToolsSpec(): array
|
||||
{
|
||||
return array_map(function (Tool $tool) {
|
||||
return [
|
||||
'type' => 'function',
|
||||
'function' => [
|
||||
'name' => $tool->name(),
|
||||
'description' => $tool->description(),
|
||||
'parameters' => $tool->parameters(),
|
||||
],
|
||||
];
|
||||
}, $this->all());
|
||||
}
|
||||
}
|
||||
40
app/Services/Tool/ToolResult.php
Normal file
40
app/Services/Tool/ToolResult.php
Normal file
@@ -0,0 +1,40 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Tool;
|
||||
|
||||
/**
|
||||
* Tool 执行结果 DTO，记录结果文本与状态。
|
||||
*/
|
||||
final class ToolResult
|
||||
{
|
||||
public function __construct(
|
||||
public string $runId,
|
||||
public string $parentRunId,
|
||||
public string $toolCallId,
|
||||
public string $name,
|
||||
public string $status,
|
||||
public string $output,
|
||||
public ?string $error = null,
|
||||
public bool $truncated = false,
|
||||
) {
|
||||
}
|
||||
|
||||
/**
|
||||
* 便于在测试/日志中以数组格式使用。
|
||||
*
|
||||
* @return array<string, mixed>
|
||||
*/
|
||||
public function toArray(): array
|
||||
{
|
||||
return [
|
||||
'run_id' => $this->runId,
|
||||
'parent_run_id' => $this->parentRunId,
|
||||
'tool_call_id' => $this->toolCallId,
|
||||
'name' => $this->name,
|
||||
'status' => $this->status,
|
||||
'output' => $this->output,
|
||||
'error' => $this->error,
|
||||
'truncated' => $this->truncated,
|
||||
];
|
||||
}
|
||||
}
|
||||
39
app/Services/Tool/ToolRunDispatcher.php
Normal file
39
app/Services/Tool/ToolRunDispatcher.php
Normal file
@@ -0,0 +1,39 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Tool;
|
||||
|
||||
use App\Jobs\ToolRunJob;
|
||||
use App\Services\OutputSink;
|
||||
use Illuminate\Support\Facades\DB;
|
||||
|
||||
/**
|
||||
* 子 Run 调度：为单个 tool_call 创建 Run 并投递队列，幂等。
|
||||
*/
|
||||
class ToolRunDispatcher
|
||||
{
|
||||
public function __construct(private readonly OutputSink $outputSink)
|
||||
{
|
||||
}
|
||||
|
||||
public function dispatch(string $sessionId, ToolCall $toolCall): string
|
||||
{
|
||||
$shouldDispatch = false;
|
||||
|
||||
DB::transaction(function () use ($sessionId, $toolCall, &$shouldDispatch): void {
|
||||
$wasDeduped = null;
|
||||
$this->outputSink->appendRunStatus($sessionId, $toolCall->runId, 'RUNNING', [
|
||||
'parent_run_id' => $toolCall->parentRunId,
|
||||
'tool_call_id' => $toolCall->toolCallId,
|
||||
'dedupe_key' => "run:{$toolCall->runId}:status:RUNNING",
|
||||
], $wasDeduped);
|
||||
|
||||
$shouldDispatch = ! $wasDeduped;
|
||||
});
|
||||
|
||||
if ($shouldDispatch) {
|
||||
ToolRunJob::dispatchSync($sessionId, $toolCall->toArray());
|
||||
}
|
||||
|
||||
return $toolCall->runId;
|
||||
}
|
||||
}
|
||||
51
app/Services/Tool/Tools/GetTimeTool.php
Normal file
51
app/Services/Tool/Tools/GetTimeTool.php
Normal file
@@ -0,0 +1,51 @@
|
||||
<?php
|
||||
|
||||
namespace App\Services\Tool\Tools;
|
||||
|
||||
use App\Services\Tool\Tool;
|
||||
use Illuminate\Support\Carbon;
|
||||
|
||||
class GetTimeTool implements Tool
|
||||
{
|
||||
public function name(): string
|
||||
{
|
||||
return 'get_time';
|
||||
}
|
||||
|
||||
public function description(): string
|
||||
{
|
||||
return '返回服务器当前时间，可指定 PHP 日期格式。';
|
||||
}
|
||||
|
||||
/**
|
||||
* @return array<string, mixed>
|
||||
*/
|
||||
public function parameters(): array
|
||||
{
|
||||
return [
|
||||
'type' => 'object',
|
||||
'properties' => [
|
||||
'format' => [
|
||||
'type' => 'string',
|
||||
'description' => '可选的日期格式，默认为 RFC3339。',
|
||||
],
|
||||
],
|
||||
'required' => [],
|
||||
];
|
||||
}
|
||||
|
||||
/**
|
||||
* @param array<string, mixed> $arguments
|
||||
* @return array<string, mixed>
|
||||
*/
|
||||
public function execute(array $arguments): array
|
||||
{
|
||||
$format = is_string($arguments['format'] ?? null) && $arguments['format'] !== ''
|
||||
? $arguments['format']
|
||||
: Carbon::RFC3339_EXTENDED;
|
||||
|
||||
return [
|
||||
'now' => Carbon::now()->format($format),
|
||||
];
|
||||
}
|
||||
}
|
||||
Reference in New Issue
Block a user