DBAdmin/agent.md

# Architektura agenta

Poniżej Mermaid dla architektury **hub-and-spoke** z obrazka — wersja bez `<br/>`, żeby uniknąć błędu `splitLineToFitWidth does not support newlines in the line`.

```mermaid
flowchart LR
    Coordinator["Coordinator - routes and handles errors"]

    Research["Research agent"]
    Writer["Writer agent"]
    Coder["Coder agent"]
    Reviewer["Reviewer agent"]
    Summariser["Summariser agent"]
    Data["Data agent"]
    Planner["Planner agent"]

    Coordinator <--> Research
    Coordinator <--> Writer
    Coordinator <--> Coder
    Coordinator <--> Reviewer
    Coordinator <--> Summariser
    Coordinator <--> Data
    Coordinator <--> Planner

    classDef coordinator fill:#eeeaff,stroke:#8b7bd8,stroke-width:1.5px,color:#3f3a73;
    classDef agent fill:#ddf7f0,stroke:#7bb8a6,stroke-width:1.5px,color:#18584c;

    class Coordinator coordinator;
    class Research,Writer,Coder,Reviewer,Summariser,Data,Planner agent;
```

Wersja z opisem zasad z lewej strony jako osobne węzły:

```mermaid
flowchart LR
    Rules["Hub-and-spoke architecture - one coordinator at the center; subagents talk only to coordinator"]
    Ownership["Coordinator owns routing, context sharing, and error handling"]

    Coordinator["Coordinator - routes and handles errors"]

    Research["Research agent"]
    Writer["Writer agent"]
    Coder["Coder agent"]
    Reviewer["Reviewer agent"]
    Summariser["Summariser agent"]
    Data["Data agent"]
    Planner["Planner agent"]

    Rules --> Coordinator
    Ownership --> Coordinator

    Coordinator <--> Research
    Coordinator <--> Writer
    Coordinator <--> Coder
    Coordinator <--> Reviewer
    Coordinator <--> Summariser
    Coordinator <--> Data
    Coordinator <--> Planner

    classDef coordinator fill:#eeeaff,stroke:#8b7bd8,stroke-width:1.5px,color:#3f3a73;
    classDef agent fill:#ddf7f0,stroke:#7bb8a6,stroke-width:1.5px,color:#18584c;
    classDef note fill:#ffffff,stroke:#cccccc,stroke-width:1px,color:#222222;

    class Coordinator coordinator;
    class Research,Writer,Coder,Reviewer,Summariser,Data,Planner agent;
    class Rules,Ownership note;
```

I wersja najbardziej kompaktowa do dokumentacji:

```mermaid
flowchart TD
    Coordinator["Coordinator"]

    Coordinator --> Research["Research agent"]
    Coordinator --> Writer["Writer agent"]
    Coordinator --> Coder["Coder agent"]
    Coordinator --> Reviewer["Reviewer agent"]
    Coordinator --> Summariser["Summariser agent"]
    Coordinator --> Data["Data agent"]
    Coordinator --> Planner["Planner agent"]

    Research --> Coordinator
    Writer --> Coordinator
    Coder --> Coordinator
    Reviewer --> Coordinator
    Summariser --> Coordinator
    Data --> Coordinator
    Planner --> Coordinator
```


Kluczowa zasada z obrazka: **nie rysujemy połączeń bezpośrednio między subagentami** — wszystko idzie przez `Coordinator`.


```mermaid
flowchart TD
    Decompose["1. Decompose - Break task into subtasks"]
    Assess["2. Assess complexity - Which agents are needed?"]

    Simple["Single agent"]
    Moderate["2-3 agents in sequence"]
    Complex["Agents in parallel"]

    Aggregate["3. Aggregate results - Merge, rank, resolve conflicts"]
    Response["Final response"]

    Decompose --> Assess

    Assess -->|simple| Simple
    Assess -->|moderate| Moderate
    Assess -->|complex| Complex

    Simple --> Aggregate
    Moderate --> Aggregate
    Complex --> Aggregate

    Aggregate --> Response
```

1. You are a coordinator. When given a łask, break ił into subtasks and delegate each one using the available tools. Do not do the work yourself.

```mermaid
flowchart TD

    A["User Request"]

    B["1. Analyze Request"]
    C["Identify Goal"]
    D["Identify Constraints"]
    E["Identify Required Knowledge"]
    F["Identify Required Actions"]

    G["Break Into Subtasks"]

    H["Research Tasks"]
    I["Data Collection Tasks"]
    J["Analysis Tasks"]
    K["Decision Tasks"]
    L["Execution Tasks"]
    M["Communication Tasks"]

    N["Subtask List"]

    A --> B
    B --> C
    B --> D
    B --> E
    B --> F

    C --> G
    D --> G
    E --> G
    F --> G

    G --> H
    G --> I
    G --> J
    G --> K
    G --> L
    G --> M

    H --> N
    I --> N
    J --> N
    K --> N
    L --> N
    M --> N
```

2. Access complexity 
You are a coordinator. Use your judgment:
- Simple factual questions: use a single agent
- Multi-step tasks: delegate sequentially, passing results forward
- Independent subtasks: delegate in parallel
a. Logika decyzyjna
```mermaid
flowchart TD

    A["Receive Task"]

    B["Analyze Task"]

    C{"Task Complexity?"}

    D["Single Agent"]
    E["Sequential Delegation"]
    F["Parallel Delegation"]

    G["Simple factual question"]

    H["Subtask 1"]
    I["Subtask 2"]
    J["Subtask N"]

    K["Independent Subtask 1"]
    L["Independent Subtask 2"]
    M["Independent Subtask N"]

    N["Aggregate Results"]

    O["Final Response"]

    A --> B
    B --> C

    C -->|Simple| D
    C -->|Multi-step| E
    C -->|Independent subtasks| F

    D --> G
    G --> N

    E --> H
    H --> I
    I --> J
    J --> N

    F --> K
    F --> L
    F --> M

    K --> N
    L --> N
    M --> N

    N --> O
```

Lub też inaczej 

```mermaid
flowchart TD

    A["Task"]

    B{"Use your judgment"}

    C["Single Agent"]
    D["Sequential Agents"]
    E["Parallel Agents"]

    F["Simple factual question"]
    G["Multi-step task"]
    H["Independent subtasks"]

    I["Pass results forward"]
    J["Aggregate outputs"]

    K["Final response"]

    A --> B

    B --> F
    B --> G
    B --> H

    F --> C
    G --> D
    H --> E

    D --> I

    C --> J
    I --> J
    E --> J

    J --> K
```
3. Aggregate results
You have received outputs from multiple agents.
Combine them into a single coherent response.
Resolve any conflicts by preferring the most specific data.
Research output: ${results.research}
Writing output: ${results.writing}
Review feedback: ${results.review}


Dla etapu **"3. Aggregate results"** można opracować prompt bardziej formalnie i operacyjnie:

```text
You are the Aggregator agent.

Your responsibility is to combine outputs from multiple agents into a single coherent response.

Instructions:

1. Review all agent outputs.
2. Identify overlapping information.
3. Remove duplicates and redundancy.
4. Resolve conflicts:
   - Prefer the most specific information.
   - Prefer data supported by evidence.
   - Prefer newer information when timestamps are available.
5. Integrate review feedback into the final result.
6. Preserve important details from every agent.
7. Produce one unified response.
8. Do not mention individual agents unless explicitly requested.
9. Do not perform additional research.
10. Do not introduce new facts not present in the inputs.

Inputs:

Research output:
${results.research}

Writing output:
${results.writing}

Review feedback:
${results.review}

Output:

A single consolidated response incorporating:
- validated research findings,
- improved writing structure,
- accepted review recommendations.
```

Diagram Mermaid dla tego kroku:

```mermaid
flowchart TD

    A["Research Output"]
    B["Writing Output"]
    C["Review Feedback"]

    D["Analyze Inputs"]

    E["Remove Duplicates"]
    F["Resolve Conflicts"]
    G["Apply Review Feedback"]
    H["Merge Information"]

    I["Unified Response"]

    A --> D
    B --> D
    C --> D

    D --> E
    E --> F
    F --> G
    G --> H

    H --> I
```

Jeżeli budujesz system typu **Coordinator → Research → Writing → Review → Aggregate**, to Aggregator jest ostatnim agentem przed zwróceniem odpowiedzi do użytkownika.


# Architekura 

Da się, ale ten obraz jest bardzo szczegółowy. Zamiast przepisywać wszystkie opisy agentów 1:1, proponuję najpierw odtworzyć **strukturę organizacyjną**, a potem ewentualnie rozbudować o opisy.

Na obrazku widzę 4 domeny:

* Engineering (Architect → Frontend, Backend, Security, QA, Release, Implementation)
* Marketing (Mouse → Content, Video Director, Scriptwriter, Designer, Video Editor, Asset Producer)
* Growth (Analyst → Funnels, Pricing, Retention, Analytics, Partnerships)
* Research (Oracle → Signals, Synthesis, Competitive, Customer Research, Product Research)

Mermaid:

```mermaid  
flowchart LR

    CTO["Engineering Architect"]
    CMO["Marketing Mouse"]
    CGO["Growth Analyst"]
    CRO["Research Oracle"]

    CTO --> Frontend["Frontend"]
    CTO --> Backend["Backend"]
    CTO --> Security["Security"]
    CTO --> QA["QA"]
    CTO --> Release["Release"]
    CTO --> Implementation["Implementation"]

    CMO --> Content["Content"]
    CMO --> VideoDirector["Video Director"]
    CMO --> Scriptwriter["Scriptwriter"]
    CMO --> Designer["Designer"]
    CMO --> VideoEditor["Video Editor"]
    CMO --> AssetProducer["Asset Producer"]

    CGO --> Funnels["Funnels"]
    CGO --> Pricing["Pricing"]
    CGO --> Retention["Retention"]
    CGO --> Analytics["Analytics"]
    CGO --> Partnerships["Partnerships"]

    CRO --> Signals["Signals"]
    CRO --> Synthesis["Synthesis"]
    CRO --> Competitive["Competitive"]
    CRO --> Customer["Customer Research"]
    CRO --> Product["Product Research"]

    classDef lead fill:#222244,color:white,stroke:#aaa;
    classDef eng fill:#1f4e79,color:white;
    classDef mkt fill:#8c5e00,color:white;
    classDef growth fill:#5b3a8c,color:white;
    classDef research fill:#8c2f39,color:white;

    class CTO lead;
    class CMO lead;
    class CGO lead;
    class CRO lead;

    class Frontend,Backend,Security,QA,Release,Implementation eng;
    class Content,VideoDirector,Scriptwriter,Designer,VideoEditor,AssetProducer mkt;
    class Funnels,Pricing,Retention,Analytics,Partnerships growth;
    class Signals,Synthesis,Competitive,Customer,Product research;
```

Jeżeli to ma być do Twojego systemu agentowego (Coordinator → subagenci), to lepiej byłoby narysować to jako **hierarchię agentów z ownerami**, np.:

```mermaid
flowchart TB

    Coordinator

    Coordinator --> Engineering
    Coordinator --> Marketing
    Coordinator --> Growth
    Coordinator --> Research

    Engineering --> Frontend
    Engineering --> Backend
    Engineering --> Security
    Engineering --> QA
    Engineering --> Release
    Engineering --> Implementation

    Marketing --> Content
    Marketing --> Scriptwriter
    Marketing --> Designer
    Marketing --> VideoDirector
    Marketing --> VideoEditor
    Marketing --> AssetProducer

    Growth --> Funnels
    Growth --> Pricing
    Growth --> Retention
    Growth --> Analytics
    Growth --> Partnerships

    Research --> Signals
    Research --> Synthesis
    Research --> Competitive
    Research --> CustomerResearch
    Research --> ProductResearch
```


To już wygląda jak prawdziwy **multi-agent architecture diagram**, który można później połączyć z Twoim wcześniejszym diagramem **Coordinator / Planner / Research / Review / Aggregate**.