wip

Author: tymondesigns

config/cortex.php

@@ -326,6 +326,48 @@
         ],
     ],
 
+    /*
+    |--------------------------------------------------------------------------
+    | Agents
+    |--------------------------------------------------------------------------
+    |
+    | Configure agent auto-discovery from your Laravel application.
+    | All agents must extend the AbstractAgent class.
+    |
+    | Agents can be registered in two ways:
+    |
+    | 1. Auto-discovery: Automatically discover agents from the configured path
+    | 2. Manual registration: Use Agent::register() or AgentRegistry::register()
+    |
+    | Example manual registration in service provider:
+    | use Cortex\Facades\Agent;
+    |
+    | public function boot(): void
+    | {
+    |     Agent::register('weather', App\Agents\WeatherAgent::class);
+    |     // Or with an instance:
+    |     Agent::register('custom', new Agent(...));
+    | }
+    |
+    | Usage:
+    | $agent = Cortex::agent('weather-agent');
+    | $result = $agent->invoke([], ['location' => 'New York']);
+    |
+    */
+    'agents' => [
+        /*
+         * Enable automatic discovery of agents from the configured path.
+         */
+        'auto_discover' => env('CORTEX_AGENTS_AUTO_DISCOVER', true),
+
+        /*
+         * The directory path where agents are located.
+         * Defaults to app_path('Agents').
+         * Agents will be discovered from this directory and its subdirectories.
+         */
+        'path' => env('CORTEX_AGENTS_PATH', null),
+    ],
+
     /*
      * Configure the cache settings.
      */

scratchpad.php

@@ -3,8 +3,11 @@
 declare(strict_types=1);
 
 use Cortex\Cortex;
+use Cortex\Agents\Agent;
 use Cortex\Prompts\Prompt;
 use Cortex\JsonSchema\SchemaFactory;
+use Cortex\Tools\Prebuilt\WeatherTool;
+use Cortex\Agents\Prebuilt\WeatherAgent;
 use Cortex\LLM\Data\Messages\UserMessage;
 use Cortex\LLM\Data\Messages\SystemMessage;
 
@@ -81,27 +84,42 @@
         new UserMessage('What is the capital of France?'),
     ]);
 
-// Run an agent with only input parameters
-$agent = Cortex::agent('joke_generator')
-    ->prompt('You are a joke generator. You generate jokes about {topic}.')
-    ->llm('ollama:gpt-oss:20b')
-    ->build();
+$jokeAgent = new Agent(
+    name: 'joke_generator',
+    prompt: 'You are a joke generator. You generate jokes about {topic}.',
+    llm: 'ollama:gpt-oss:20b',
+);
 
-$result = $agent->invoke(input: [
+$result = $jokeAgent->invoke(input: [
     'topic' => 'programming',
 ]);
 
-// Run a task
-$jokeGenerator = Cortex::task('joke_generator')
-    ->llm('ollama', 'llama3.2')
-    ->user('Tell me a joke about {topic}')
-    ->output(SchemaFactory::object()->properties(
-        SchemaFactory::string('joke'),
-        SchemaFactory::string('punchline'),
-    ));
+$weatherAgent = WeatherAgent::make()->invoke(input: [
+    'location' => 'Paris',
+]);
 
-$result = $jokeGenerator([
-    'topic' => 'programming',
+Cortex::registerAgent('weather_agent', WeatherAgent::class);
+
+Cortex::agent('weather_agent')->invoke(input: [
+    'location' => 'Paris',
+]);
+
+$agent = Cortex::agent()
+    ->withName('weather_agent')
+    ->withPrompt('You are a weather agent. You tell the weather in {location}.')
+    ->withLLM('ollama:gpt-oss:20b')
+    ->withTools([
+        WeatherTool::class,
+    ])
+    ->withOutput(SchemaFactory::object()->properties(
+        SchemaFactory::string('location')->required(),
+        SchemaFactory::string('summary')->required(),
+    ))
+    ->withMaxSteps(3)
+    ->withStrict(true);
+
+$result = $agent->invoke(input: [
+    'location' => 'London',
 ]);
 
 $result = Cortex::embeddings('openai')

src/Agents/AbstractAgent.php

@@ -0,0 +1,115 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Cortex\Agents;
+
+use Cortex\Contracts\ToolKit;
+use Cortex\LLM\Contracts\LLM;
+use Cortex\LLM\Data\ChatResult;
+use Cortex\LLM\Enums\ToolChoice;
+use Cortex\Memory\Contracts\Store;
+use Cortex\LLM\Data\ChatStreamResult;
+use Cortex\Agents\Contracts\AgentBuilder;
+use Cortex\JsonSchema\Types\ObjectSchema;
+use Cortex\LLM\Enums\StructuredOutputMode;
+
+abstract class AbstractAgentBuilder implements AgentBuilder
+{
+    public function llm(): LLM|string|null
+    {
+        return null;
+    }
+
+    /**
+     * @return array<int, \Cortex\LLM\Contracts\Tool|\Closure|class-string<\Cortex\LLM\Contracts\Tool>>
+     */
+    public function tools(): array|ToolKit
+    {
+        return [];
+    }
+
+    public function toolChoice(): ToolChoice|string
+    {
+        return ToolChoice::Auto;
+    }
+
+    public function output(): ObjectSchema|string|null
+    {
+        return null;
+    }
+
+    public function outputMode(): StructuredOutputMode
+    {
+        return StructuredOutputMode::Auto;
+    }
+
+    public function memoryStore(): ?Store
+    {
+        return null;
+    }
+
+    public function maxSteps(): int
+    {
+        return 5;
+    }
+
+    public function strict(): bool
+    {
+        return true;
+    }
+
+    public function initialPromptVariables(): array
+    {
+        return [];
+    }
+
+    public function build(): Agent
+    {
+        return new Agent(
+            name: $this->name(),
+            prompt: $this->prompt(),
+            llm: $this->llm(),
+            tools: $this->tools(),
+            toolChoice: $this->toolChoice(),
+            output: $this->output(),
+            outputMode: $this->outputMode(),
+            memoryStore: $this->memoryStore(),
+            initialPromptVariables: $this->initialPromptVariables(),
+            maxSteps: $this->maxSteps(),
+            strict: $this->strict(),
+        );
+    }
+
+    /**
+     * Convenience method to make an agent instance using the methods defined in this class.
+     */
+    public static function make(array $parameters = []): Agent
+    {
+        $builder = app(static::class, $parameters);
+
+        return $builder->build();
+    }
+
+    /**
+     * Convenience method to invoke the built agent instance..
+     *
+     * @param array<int, \Cortex\LLM\Contracts\Message> $messages
+     * @param array<string, mixed> $input
+     */
+    public function invoke(array $messages = [], array $input = []): ChatResult
+    {
+        return $this->build()->invoke($messages, $input);
+    }
+
+    /**
+     * Convenience method to stream from the built agent instance.
+     *
+     * @param array<int, \Cortex\LLM\Contracts\Message> $messages
+     * @param array<string, mixed> $input
+     */
+    public function stream(array $messages = [], array $input = []): ChatStreamResult
+    {
+        return $this->build()->stream($messages, $input);
+    }
+}

src/Agents/AbstractAgentBuilder.php

@@ -21,6 +21,7 @@
 use Cortex\Exceptions\PipelineException;
 use Cortex\Agents\Stages\HandleToolCalls;
 use Cortex\JsonSchema\Types\ObjectSchema;
+use Cortex\LLM\Enums\StructuredOutputMode;
 use Cortex\LLM\Data\Messages\SystemMessage;
 use Illuminate\Contracts\Support\Arrayable;
 use Cortex\Agents\Stages\AddMessageToMemory;
@@ -53,6 +54,7 @@ public function __construct(
         protected array|ToolKit $tools = [],
         protected ToolChoice|string $toolChoice = ToolChoice::Auto,
         protected ObjectSchema|string|null $output = null,
+        protected StructuredOutputMode $outputMode = StructuredOutputMode::Auto,
         protected ?Store $memoryStore = null,
         protected array $initialPromptVariables = [],
         protected int $maxSteps = 5,
@@ -67,6 +69,7 @@ public function __construct(
             $this->tools,
             $this->toolChoice,
             $this->output,
+            $this->outputMode,
             $this->strict,
         );
         $this->usage = Usage::empty();
@@ -117,7 +120,7 @@ public function invoke(array $messages = [], array $input = []): ChatResult
         $this->memory->setMessages($messages);
 
         /** @var \Cortex\LLM\Data\ChatResult $result */
-        $result = $this->pipeline()->invoke([
+        $result = $this->pipeline()->disableStreaming()->invoke([
             ...$input,
             'messages' => $this->memory->getMessages(),
         ]);
@@ -253,10 +256,11 @@ protected static function buildMemory(ChatPromptTemplate $prompt, ?Store $memory
     protected static function buildLLM(
         ChatPromptTemplate $prompt,
         string $name,
-        ?LLMContract $llm = null,
+        LLMContract|string|null $llm = null,
         array $tools = [],
         ToolChoice|string $toolChoice = ToolChoice::Auto,
         ObjectSchema|string|null $output = null,
+        StructuredOutputMode $outputMode = StructuredOutputMode::Auto,
         bool $strict = true,
     ): LLMContract {
         $llm = $llm !== null
@@ -276,6 +280,7 @@ protected static function buildLLM(
                 output: $output,
                 name: $name,
                 strict: $strict,
+                outputMode: $outputMode,
             );
         }