# Neuron Suunnittelija / suorittaja

Tässä esimerkissä orkestrointiin käytetään kohdetta Queuety ja varsinaiseen agentin suoritukseen kohdetta Neuron.

Toimintamalli on yksinkertainen. Queuety-suunnittelijavaihe määrittää tehtävät, `start_agents()` muuttaa ne itsenäisiksi ylimmän tason työnkuluiksi, kukin alatason työnkulku suorittaa Neuron-agentin ja `wait_for_agents()` kokoaa tulokset takaisin ylätyönkulkuun.

## Miksi tämä jako toimii hyvin

Neuron osaa vaihtaa palveluntarjoajaa vähäisin koodimuutoksin ja kapseloida erikoistuneen agentin kehotteen, työkalut ja muistin. Queuety sopii hyvin kestäviin for-each- ja valmistumistiloihin, uudelleenyrityksiin, jatkamiseen sekä suorituksen tarkasteluun tai ihmisen tekemään tarkistukseen.

## Vaihe 1: luo agentti Neuron, jonka palveluntarjoajaa voi vaihtaa

```php
namespace App\Neuron;

use NeuronAI\Agent\Agent;
use NeuronAI\Providers\AIProviderInterface;
use NeuronAI\Providers\Anthropic\Anthropic;
use NeuronAI\Providers\Gemini\Gemini;
use NeuronAI\Providers\OpenAI\Responses\OpenAIResponses;
use NeuronAI\SystemPrompt;

final class ResearchAgent extends Agent
{
    public function __construct(
        private readonly string $providerName = 'openai',
    ) {}

    protected function provider(): AIProviderInterface
    {
        return match ($this->providerName) {
            'anthropic' => new Anthropic(
                key: $_ENV['ANTHROPIC_API_KEY'],
                model: $_ENV['ANTHROPIC_MODEL'],
            ),
            'gemini' => new Gemini(
                key: $_ENV['GEMINI_API_KEY'],
                model: $_ENV['GEMINI_MODEL'],
            ),
            default => new OpenAIResponses(
                key: $_ENV['OPENAI_API_KEY'],
                model: $_ENV['OPENAI_MODEL'],
            ),
        };
    }

    public function instructions(): string
    {
        return (string) new SystemPrompt(
            background: [
                'You are a research agent.',
                'Return concise, source-aware summaries for the assigned topic.',
            ],
        );
    }
}
```

Hyödyllistä tässä on se, että työnkulku voi valita palveluntarjoajan suorituksen aikana välittämällä kohteen `provider` työnkulun tilassa.

## Vaihe 2: suorita agentti Neuron vaiheen Queuety sisällä

```php
namespace App\Workflow\Steps;

use App\Neuron\ResearchAgent;
use NeuronAI\Chat\Messages\UserMessage;
use Queuety\Step;

final class ResearchTopicStep implements Step
{
    public function handle(array $state): array
    {
        $agent = new ResearchAgent(
            providerName: $state['provider'] ?? 'openai',
        );

        $message = $agent->chat(
            new UserMessage(sprintf(
                "Research the topic '%s' for brief %d. Return a compact bullet summary.",
                $state['topic'],
                $state['brief_id'],
            ))
        )->getMessage();

        return [
            'summary' => $message->getContent(),
        ];
    }

    public function config(): array
    {
        return [];
    }
}
```

Tämä on keskeinen integraatiokohta: Neuron hoitaa LLM-kutsun, mutta Queuety hallitsee edelleen vaiherajaa ja tallennettua työnkulun tilaa.

## Vaihe 3: anna suunnittelijan käynnistää agenttien suoritukset

```php
use Queuety\Enums\WaitMode;
use Queuety\Queuety;

$agent_workflow = Queuety::workflow('research_agent_run')
    ->then(ResearchTopicStep::class);

Queuety::workflow('brief_research')
    ->version('brief-research.v1')
    ->then(PlanResearchTasksStep::class) // writes $state['agent_tasks']
    ->start_agents('agent_tasks', $agent_workflow)
    ->wait_for_agents(mode: WaitMode::All, result_key: 'agent_results')
    ->then(SynthesizeBriefStep::class)
    ->dispatch([
        'brief_id' => 42,
        'provider' => 'anthropic',
    ]);
```

Jos `PlanResearchTasksStep` palauttaa:

```php
[
    'agent_tasks' => [
        ['topic' => 'pricing'],
        ['topic' => 'customer reviews'],
        ['topic' => 'recent launches'],
    ],
]
```

Queuety luo kullekin tehtävälle ylimmän tason työnkulun, odottaa niiden kaikkien valmistumista ja välittää sitten valmiin alatason työnkulun tilan kohteen `$state['agent_results']` alla.

## Miksi kohdetta Neuron ei vain kutsuta silmukassa?

Se onnistuu, mutta menetät orkestroinnin edut:

Yksittäisiä agenttisuorituksia ei voisi enää tarkastella erikseen, osittainen kaatuminen todennäköisesti käynnistäisi koko erän uudelleen, eikä myöhemmille vaiheille olisi selkeää valmistumiskohtaa.

Tämä toimintamalli pitää agenttikoodin yksinkertaisena ja jättää kestävän orkestroinnin kohteen Queuety hallittavaksi.

Jos suunnittelija kuuluu pitkäikäisempään agentti-istuntoon, käytä tätä työnkulkumallia suorituskerroksessa ja anna [tilakoneen](https://queuety.inline0.dev/fi/docs/state-machines) hallita ulompaa elinkaarta.

## Aiheeseen liittyvät dokumentit

- [Asynkroniset siirrot](https://queuety.inline0.dev/fi/docs/workflows/async-handoffs)
- [Agenttien orkestrointi](https://queuety.inline0.dev/fi/docs/workflows/agent-orchestration)
- [Tilakoneet](https://queuety.inline0.dev/fi/docs/state-machines)