# southworks/agents architecture

> Architecture diagram of the GitHub repository southworks/agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/southworks/agents
- Repository: https://github.com/southworks/agents

## Overview

This repository is the Microsoft 365 Agents SDK landing point: it links language-specific SDKs, provides samples and coding-assistant plugins, and includes a tool that synchronizes .NET samples from upstream. The tool’s main workflow is plan → prepare migration context → run a constrained Copilot implementation session → validate the patch → publish a pull request. Its shared policy, Git, state, version, and reporting modules support that workflow. The README documents the SDK’s channel support and AI-provider flexibility; the source excerpts chiefly illuminate the sample-sync tool, so other SDK capabilities are represented at their documented directory level.

Main entry points: [`automation/teams-sample-sync/src/cli.ts`](https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/cli.ts) (Sync CLI), [`automation/teams-sample-sync/src/plan.ts`](https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/plan.ts) (Migration planner), [`automation/teams-sample-sync/src/context.ts`](https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/context.ts) (Migration context), [`automation/teams-sample-sync/src/sync-session.ts`](https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/sync-session.ts) (Migration session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_sync["Sample synchronization"]
  node_cli["Sync CLI<br/>[cli.ts]"]
  node_plan["Migration planner<br/>[plan.ts]"]
  node_context["Migration context<br/>[context.ts]"]
  node_session["Migration session<br/>[sync-session.ts]"]
  node_runner["Copilot runner<br/>[agent-runner.ts]"]
  node_tools["Agent tools<br/>[agent-tools.ts]"]
  node_validator["Sample validator<br/>[validate.ts]"]
  node_report["Sync reporting<br/>[report.ts]"]
  node_publisher["PR publisher<br/>[publish-pr.ts]"]
end

subgraph group_sdk["SDK and samples"]
  node_sdk["Language SDKs"]
  node_channels["Agent channels"]
  node_samples["SDK examples"]
end

subgraph group_plugins["Agent plugins"]
  node_plugins["Coding skills"]
end

subgraph group_support["Sync foundations"]
  node_config["Policy configuration<br/>[config.ts]"]
  node_git["Git evidence<br/>[git.ts]"]
  node_guard["Scope guard<br/>[guard.ts]"]
  node_state["Verified state<br/>[state.ts]"]
  node_versions["SDK version resolver<br/>[versions.ts]"]
  node_contracts["Handoff contracts<br/>[types.ts]"]
end

node_operator(("Maintainer"))
node_upstream["Upstream samples"]
node_copilot["GitHub Copilot SDK"]
node_pullrequest["Pull request"]

node_operator -->|"runs sync"| node_cli
node_cli -->|"creates plan"| node_plan
node_plan -->|"resolves version"| node_versions
node_plan -->|"compares trees"| node_git
node_plan -->|"reads state"| node_state
node_cli -.->|"builds context"| node_context
node_context -->|"materializes evidence"| node_git
node_context -->|"reads prior state"| node_state
node_cli -->|"runs migration"| node_session
node_session -.->|"uses session"| node_runner
node_runner -->|"opens SDK session"| node_copilot
node_session -->|"requests validation"| node_tools
node_tools -->|"checks boundaries"| node_guard
node_tools -->|"validates sample"| node_validator
node_validator -->|"checks versions"| node_versions
node_cli -.->|"writes report"| node_report
node_cli -->|"publishes patch"| node_publisher
node_publisher -.->|"opens PR"| node_pullrequest
node_cli -->|"loads policy"| node_config
node_cli -->|"resolves SDK"| node_versions
node_cli -->|"checks changes"| node_git
node_sdk -->|"deploys agents"| node_channels
node_samples -->|"demonstrate usage"| node_sdk
node_plugins -->|"guide development"| node_sdk
node_upstream -.->|"supplies changes"| node_cli

click node_cli "https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/cli.ts"
click node_plan "https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/plan.ts"
click node_context "https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/context.ts"
click node_session "https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/sync-session.ts"
click node_runner "https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/agent-runner.ts"
click node_tools "https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/agent-tools.ts"
click node_validator "https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/validate.ts"
click node_report "https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/report.ts"
click node_publisher "https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/publish-pr.ts"
click node_config "https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/config.ts"
click node_git "https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/git.ts"
click node_guard "https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/guard.ts"
click node_state "https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/state.ts"
click node_versions "https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/versions.ts"
click node_contracts "https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/types.ts"
click node_sdk "https://github.com/southworks/agents/tree/main/samples"
click node_samples "https://github.com/southworks/agents/tree/main/samples"
click node_plugins "https://github.com/southworks/agents/tree/main/agent-plugins"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_plan,node_context,node_session,node_runner,node_tools,node_validator,node_report,node_publisher toneBlue
class node_sdk,node_channels,node_samples toneAmber
class node_plugins,node_pullrequest toneMint
class node_config,node_git,node_guard,node_state,node_versions,node_contracts toneRose
class node_operator,node_upstream,node_copilot toneIndigo
```

## Components

### Sample synchronization

- [Sync CLI](https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/cli.ts): `automation/teams-sample-sync/src/cli.ts`
- [Migration planner](https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/plan.ts): `automation/teams-sample-sync/src/plan.ts`
- [Migration context](https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/context.ts): `automation/teams-sample-sync/src/context.ts`
- [Migration session](https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/sync-session.ts): `automation/teams-sample-sync/src/sync-session.ts`
- [Copilot runner](https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/agent-runner.ts): `automation/teams-sample-sync/src/agent-runner.ts`
- [Agent tools](https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/agent-tools.ts): `automation/teams-sample-sync/src/agent-tools.ts`
- [Sample validator](https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/validate.ts): `automation/teams-sample-sync/src/validate.ts`
- [Sync reporting](https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/report.ts): `automation/teams-sample-sync/src/report.ts`
- [PR publisher](https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/publish-pr.ts): `automation/teams-sample-sync/src/publish-pr.ts`

### SDK and samples

- [Language SDKs](https://github.com/southworks/agents/tree/main/samples): `samples`
- **Agent channels**
- [SDK examples](https://github.com/southworks/agents/tree/main/samples): `samples`

### Agent plugins

- [Coding skills](https://github.com/southworks/agents/tree/main/agent-plugins): `agent-plugins`

### Sync foundations

- [Policy configuration](https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/config.ts): `automation/teams-sample-sync/src/config.ts`
- [Git evidence](https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/git.ts): `automation/teams-sample-sync/src/git.ts`
- [Scope guard](https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/guard.ts): `automation/teams-sample-sync/src/guard.ts`
- [Verified state](https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/state.ts): `automation/teams-sample-sync/src/state.ts`
- [SDK version resolver](https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/versions.ts): `automation/teams-sample-sync/src/versions.ts`
- [Handoff contracts](https://github.com/southworks/agents/blob/main/automation/teams-sample-sync/src/types.ts): `automation/teams-sample-sync/src/types.ts`

### Other components

- **Maintainer**
- **Upstream samples**
- **GitHub Copilot SDK**
- **Pull request**

## Connections

- Maintainer → Sync CLI: runs sync (evidence: `automation/teams-sample-sync/src/cli.ts`)
- Sync CLI → Migration planner: creates plan (evidence: `automation/teams-sample-sync/src/cli.ts`)
- Migration planner → SDK version resolver: resolves version (evidence: `automation/teams-sample-sync/src/plan.ts`)
- Migration planner → Git evidence: compares trees (evidence: `automation/teams-sample-sync/src/plan.ts`)
- Migration planner → Verified state: reads state (evidence: `automation/teams-sample-sync/src/plan.ts`)
- Sync CLI → Migration context: builds context (evidence: `automation/teams-sample-sync/src/cli.ts`)
- Migration context → Git evidence: materializes evidence (evidence: `automation/teams-sample-sync/src/context.ts`)
- Migration context → Verified state: reads prior state (evidence: `automation/teams-sample-sync/src/context.ts`)
- Sync CLI → Migration session: runs migration (evidence: `automation/teams-sample-sync/src/cli.ts`)
- Migration session → Copilot runner: uses session (evidence: `automation/teams-sample-sync/src/sync-session.ts`)
- Copilot runner → GitHub Copilot SDK: opens SDK session (evidence: `automation/teams-sample-sync/src/agent-runner.ts`)
- Migration session → Agent tools: requests validation (evidence: `automation/teams-sample-sync/src/cli.ts`)
- Agent tools → Scope guard: checks boundaries (evidence: `automation/teams-sample-sync/src/agent-tools.ts`)
- Agent tools → Sample validator: validates sample (evidence: `automation/teams-sample-sync/src/agent-tools.ts`)
- Sample validator → SDK version resolver: checks versions (evidence: `automation/teams-sample-sync/src/validate.ts`)
- Sync CLI → Sync reporting: writes report (evidence: `automation/teams-sample-sync/src/cli.ts`)
- Sync CLI → PR publisher: publishes patch (evidence: `automation/teams-sample-sync/src/cli.ts`)
- PR publisher → Pull request: opens PR
- Sync CLI → Policy configuration: loads policy (evidence: `automation/teams-sample-sync/src/cli.ts`)
- Sync CLI → SDK version resolver: resolves SDK (evidence: `automation/teams-sample-sync/src/cli.ts`)
- Sync CLI → Git evidence: checks changes (evidence: `automation/teams-sample-sync/src/cli.ts`)
- Language SDKs → Agent channels: deploys agents (evidence: `README.md`)
- SDK examples → Language SDKs: demonstrate usage (evidence: `README.md`)
- Coding skills → Language SDKs: guide development (evidence: `README.md`)
- Upstream samples → Sync CLI: supplies changes
