main: 增强工具调用与消息流程

- 支持 tool.call 和 tool.result 消息类型处理
- 引入 Tool 调度与执行逻辑，支持超时与结果截断
- 增加 ToolRegistry 和 ToolExecutor 管理工具定义与执行
- 更新上下文构建与消息映射逻辑，适配工具闭环处理
- 扩展配置与环境变量，支持 Tool 调用相关选项
- 增强单元测试覆盖工具调用与执行情景
- 更新文档和 OpenAPI，新增工具相关说明与模型定义

tests/Feature/AgentRunTest.php

@@ -257,4 +257,65 @@ class AgentRunTest extends TestCase
                 && ($m->payload['http_status'] ?? null) === 500;
         }));
     }
+
+    public function test_tool_call_triggers_child_run_and_continues_to_final_message(): void
+    {
+        $this->app->bind(AgentProviderInterface::class, function () {
+            return new class implements AgentProviderInterface {
+                public int $calls = 0;
+
+                public function stream(AgentContext $context, array $options = []): \Generator
+                {
+                    if ($this->calls === 0) {
+                        $this->calls++;
+                        yield ProviderEvent::toolDelta([
+                            'tool_calls' => [
+                                [
+                                    'id' => 'call_1',
+                                    'name' => 'get_time',
+                                    'arguments' => '{"format":"c"}',
+                                    'index' => 0,
+                                ],
+                            ],
+                        ]);
+                        yield ProviderEvent::done('tool_calls');
+
+                        return;
+                    }
+
+                    yield ProviderEvent::messageDelta('tool done');
+                    yield ProviderEvent::done('stop');
+                }
+            };
+        });
+
+        $service = app(ChatService::class);
+        $dispatcher = app(RunDispatcher::class);
+
+        $session = $service->createSession('Tool Run');
+        $prompt = $service->appendMessage([
+            'session_id' => $session->session_id,
+            'role' => Message::ROLE_USER,
+            'type' => 'user.prompt',
+            'content' => 'use tool',
+        ]);
+
+        $runId = $dispatcher->dispatchForPrompt($session->session_id, $prompt->message_id);
+
+        (new AgentRunJob($session->session_id, $runId))->handle(
+            app(RunLoop::class),
+            app(OutputSink::class),
+            app(CancelChecker::class)
+        );
+
+        $messages = Message::query()
+            ->where('session_id', $session->session_id)
+            ->orderBy('seq')
+            ->get();
+
+        $this->assertTrue($messages->contains(fn ($m) => $m->type === 'tool.call' && ($m->payload['tool_call_id'] ?? null) === 'call_1'));
+        $this->assertTrue($messages->contains(fn ($m) => $m->type === 'tool.result' && ($m->payload['tool_call_id'] ?? null) === 'call_1'));
+        $this->assertTrue($messages->contains(fn ($m) => $m->type === 'agent.message' && ($m->payload['run_id'] ?? null) === $runId));
+        $this->assertTrue($messages->contains(fn ($m) => $m->type === 'run.status' && ($m->payload['status'] ?? null) === 'DONE'));
+    }
 }

tests/Unit/OpenAiAdapterTest.php

@@ -8,6 +8,7 @@ use App\Services\Agent\OpenAi\ChatCompletionsRequestBuilder;
 use App\Services\Agent\OpenAi\OpenAiEventNormalizer;
 use App\Services\Agent\OpenAi\OpenAiStreamParser;
 use App\Services\Agent\ProviderEventType;
+use App\Services\Tool\ToolRegistry;
 use GuzzleHttp\Psr7\Utils;
 use Tests\TestCase;
 
@@ -19,6 +20,7 @@ class OpenAiAdapterTest extends TestCase
         config()->set('agent.openai.temperature', 0.2);
         config()->set('agent.openai.top_p', 0.9);
         config()->set('agent.openai.include_usage', true);
+        config()->set('agent.tools.tool_choice', 'auto');
 
         $context = new AgentContext('run-1', 'session-1', 'system prompt', [
             [
@@ -26,6 +28,7 @@ class OpenAiAdapterTest extends TestCase
                 'role' => Message::ROLE_USER,
                 'type' => 'user.prompt',
                 'content' => 'hello',
+                'payload' => [],
                 'seq' => 1,
             ],
             [
@@ -33,17 +36,20 @@ class OpenAiAdapterTest extends TestCase
                 'role' => Message::ROLE_AGENT,
                 'type' => 'agent.message',
                 'content' => 'hi',
+                'payload' => [],
                 'seq' => 2,
             ],
         ]);
 
-        $payload = (new ChatCompletionsRequestBuilder())->build($context);
+        $payload = (new ChatCompletionsRequestBuilder(new ToolRegistry()))->build($context);
 
         $this->assertSame('test-model', $payload['model']);
         $this->assertTrue($payload['stream']);
         $this->assertSame(0.2, $payload['temperature']);
         $this->assertSame(0.9, $payload['top_p']);
         $this->assertSame(['include_usage' => true], $payload['stream_options']);
+        $this->assertNotEmpty($payload['tools']);
+        $this->assertSame('auto', $payload['tool_choice']);
         $this->assertSame([
             ['role' => 'system', 'content' => 'system prompt'],
             ['role' => 'user', 'content' => 'hello'],
@@ -51,6 +57,55 @@ class OpenAiAdapterTest extends TestCase
         ], $payload['messages']);
     }
 
+    public function test_request_builder_maps_tool_messages(): void
+    {
+        $context = new AgentContext('run-1', 'session-1', 'system prompt', [
+            [
+                'message_id' => 'm1',
+                'role' => Message::ROLE_USER,
+                'type' => 'user.prompt',
+                'content' => 'call tool',
+                'payload' => [],
+                'seq' => 1,
+            ],
+            [
+                'message_id' => 'm2',
+                'role' => Message::ROLE_AGENT,
+                'type' => 'tool.call',
+                'content' => null,
+                'payload' => [
+                    'tool_call_id' => 'call_1',
+                    'name' => 'get_time',
+                    'arguments' => ['format' => 'c'],
+                ],
+                'seq' => 2,
+            ],
+            [
+                'message_id' => 'm3',
+                'role' => Message::ROLE_TOOL,
+                'type' => 'tool.result',
+                'content' => '2024-01-01',
+                'payload' => [
+                    'tool_call_id' => 'call_1',
+                    'name' => 'get_time',
+                    'output' => '2024-01-01',
+                ],
+                'seq' => 3,
+            ],
+        ]);
+
+        $payload = (new ChatCompletionsRequestBuilder(new ToolRegistry()))->build($context);
+
+        $assistantMessage = collect($payload['messages'])->first(fn ($message) => isset($message['tool_calls']));
+        $toolResultMessage = collect($payload['messages'])->first(fn ($message) => ($message['role'] ?? '') === 'tool');
+
+        $this->assertNotNull($assistantMessage);
+        $this->assertSame('assistant', $assistantMessage['role']);
+        $this->assertSame('get_time', $assistantMessage['tool_calls'][0]['function']['name']);
+        $this->assertNotNull($toolResultMessage);
+        $this->assertSame('call_1', $toolResultMessage['tool_call_id']);
+    }
+
     public function test_event_normalizer_maps_delta_and_done(): void
     {
         $normalizer = new OpenAiEventNormalizer();
@@ -103,6 +158,37 @@ class OpenAiAdapterTest extends TestCase
         $this->assertSame(ProviderEventType::Done, $events[0]->type);
     }
 
+    public function test_event_normalizer_handles_tool_delta(): void
+    {
+        $normalizer = new OpenAiEventNormalizer();
+
+        $toolDelta = json_encode([
+            'choices' => [
+                [
+                    'delta' => [
+                        'tool_calls' => [
+                            [
+                                'id' => 'call_1',
+                                'index' => 0,
+                                'function' => [
+                                    'name' => 'get_time',
+                                    'arguments' => '{"format":"Y-m-d"}',
+                                ],
+                            ],
+                        ],
+                    ],
+                    'finish_reason' => null,
+                ],
+            ],
+        ]);
+
+        $events = $normalizer->normalize($toolDelta);
+        $this->assertCount(1, $events);
+        $this->assertSame(ProviderEventType::ToolDelta, $events[0]->type);
+        $this->assertSame('call_1', $events[0]->payload['tool_calls'][0]['id']);
+        $this->assertSame('get_time', $events[0]->payload['tool_calls'][0]['name']);
+    }
+
     public function test_stream_parser_splits_sse_events(): void
     {
         $stream = Utils::streamFor("data: {\"id\":1}\n\ndata: [DONE]\n\n");