Skip to content

Commit a14273e

Browse files
Chisanan232Chisanan232
authored
Merge pull request #255 from ai-agent-assembly/v0.0.1/AAASM-4336/docs/examples_shared_metadata
[AAASM-4336] 📝 (metadata): Generate SDK-version pins across example sub-projects
2 parents fffceba + ad4e3a8 commit a14273e

28 files changed

Lines changed: 1046 additions & 1 deletion

File tree

‎.github/workflows/example-metadata-check.yml‎

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
name: Example Metadata Drift Check
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- "metadata/sdk-versions.yaml"
7+
- "scripts/generate_example_metadata.py"
8+
- "python/**/pyproject.toml"
9+
- "python/**/README.md"
10+
- "node/**/package.json"
11+
- "node/**/README.md"
12+
- "go/**/go.mod"
13+
- "go/**/README.md"
14+
- "scenarios/**/pyproject.toml"
15+
- "scenarios/**/package.json"
16+
- "scenarios/**/README.md"
17+
- ".github/workflows/example-metadata-check.yml"
18+
push:
19+
branches:
20+
- master
21+
22+
concurrency:
23+
group: ${{ github.workflow }}-${{ github.ref }}
24+
cancel-in-progress: true
25+
26+
permissions:
27+
contents: read
28+
29+
jobs:
30+
drift-check:
31+
name: metadata drift
32+
runs-on: ubuntu-latest
33+
steps:
34+
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
35+
36+
- uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
37+
with:
38+
python-version: "3.12"
39+
40+
- name: Regenerate example metadata
41+
run: python scripts/generate_example_metadata.py
42+
43+
- name: Fail if regeneration produced a diff
44+
run: |
45+
if ! git diff --exit-code; then
46+
echo "::error::example metadata is out of sync with metadata/sdk-versions.yaml."
47+
echo "::error::Run 'python scripts/generate_example_metadata.py' locally and commit the result."
48+
exit 1
49+
fi

‎CONTRIBUTING.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Contributing
2+
3+
Thanks for helping improve the Agent Assembly examples. This guide covers the
4+
one repo-wide invariant that every contribution has to preserve: SDK version
5+
metadata across the example sub-projects is generated, not hand-maintained.
6+
7+
## Example SDK metadata is generated
8+
9+
Every example under `python/`, `node/`, `go/`, and `scenarios/` advertises the
10+
Agent Assembly SDK version it pins in two places: its manifest
11+
(`pyproject.toml`, `package.json`, or `go.mod`) and its `README.md`. Keeping
12+
those two in sync by hand across 20+ examples is how drift is born, so this
13+
repo owns the pattern with a single source of truth plus a generator plus a
14+
CI check.
15+
16+
### Source of truth
17+
18+
`metadata/sdk-versions.yaml` at the repo root pins the currently-shipped SDK
19+
version for each of the three language ecosystems along with the install
20+
commands used in the READMEs.
21+
22+
### Regenerating after an SDK bump
23+
24+
When a new Agent Assembly SDK release lands and you want the examples to
25+
advertise it:
26+
27+
1. Edit `metadata/sdk-versions.yaml` — update the `version` field for the
28+
affected language(s). Do not edit any manifest or README by hand.
29+
2. Run the generator from the repo root:
30+
31+
```bash
32+
python scripts/generate_example_metadata.py
33+
```
34+
35+
3. Commit the resulting manifest + README changes together with the SoT
36+
change.
37+
38+
The generator is idempotent: running it twice produces no diff. It uses only
39+
the Python standard library, so no virtualenv or pip install is required.
40+
41+
### Bounded README blocks
42+
43+
Each affected README carries a generated block bounded by:
44+
45+
```markdown
46+
<!-- BEGIN GENERATED: sdk-install -->
47+
...
48+
<!-- END GENERATED: sdk-install -->
49+
```
50+
51+
Never edit content between those markers by hand — it will be overwritten on
52+
the next generator run. Content outside the block (prose about what the
53+
example demonstrates, expected output, troubleshooting) is entirely yours to
54+
edit.
55+
56+
### CI drift check
57+
58+
`.github/workflows/example-metadata-check.yml` runs the generator on every
59+
PR that touches a manifest, README, the SoT, or the generator itself, and
60+
fails the build if the run produces a diff. If that check fails on your PR,
61+
run the generator locally and commit the result.
62+
63+
### What is out of scope for the generator
64+
65+
- **Historical / provenance text** — statements like "this example was
66+
written against 0.0.1-rc.3" are literal and must not be rewritten.
67+
- **Example runtime code** — the generator only touches manifest pins and
68+
the sdk-install README block.
69+
- **New examples** — the generator picks up new sub-projects automatically
70+
based on directory structure (any `python/<name>/pyproject.toml`,
71+
`node/<name>/package.json` pinning `@agent-assembly/sdk`, or
72+
`go/<name>/go.mod` pinning `github.com/ai-agent-assembly/go-sdk` is in
73+
scope). No configuration is needed.

‎go/README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,19 @@
11
# Go Examples
22

3+
<!-- BEGIN GENERATED: sdk-install -->
4+
<!-- This block is generated by scripts/generate_example_metadata.py. -->
5+
<!-- Edit metadata/sdk-versions.yaml and re-run the generator. -->
6+
| Requirement | Version |
7+
|---|---|
8+
| Agent Assembly Go SDK (`github.com/ai-agent-assembly/go-sdk`) | v0.0.1-rc.3 |
9+
10+
Install:
11+
12+
```bash
13+
go get github.com/ai-agent-assembly/go-sdk@v0.0.1-rc.3
14+
```
15+
<!-- END GENERATED: sdk-install -->
16+
317
Runnable Go examples showing how to integrate Agent Assembly with Go-based AI agent applications.
418

519
## What lives here

‎go/basic-agent/README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,19 @@
11
# basic-agent
22

3+
<!-- BEGIN GENERATED: sdk-install -->
4+
<!-- This block is generated by scripts/generate_example_metadata.py. -->
5+
<!-- Edit metadata/sdk-versions.yaml and re-run the generator. -->
6+
| Requirement | Version |
7+
|---|---|
8+
| Agent Assembly Go SDK (`github.com/ai-agent-assembly/go-sdk`) | v0.0.1-rc.3 |
9+
10+
Install:
11+
12+
```bash
13+
go get github.com/ai-agent-assembly/go-sdk@v0.0.1-rc.3
14+
```
15+
<!-- END GENERATED: sdk-install -->
16+
317
Minimal Go example showing how to initialize the Agent Assembly Go SDK and execute a governed tool call.
418

519
## What this example demonstrates

‎go/cli-runtime-integration/README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,19 @@
11
# cli-runtime-integration
22

3+
<!-- BEGIN GENERATED: sdk-install -->
4+
<!-- This block is generated by scripts/generate_example_metadata.py. -->
5+
<!-- Edit metadata/sdk-versions.yaml and re-run the generator. -->
6+
| Requirement | Version |
7+
|---|---|
8+
| Agent Assembly Go SDK (`github.com/ai-agent-assembly/go-sdk`) | v0.0.1-rc.3 |
9+
10+
Install:
11+
12+
```bash
13+
go get github.com/ai-agent-assembly/go-sdk@v0.0.1-rc.3
14+
```
15+
<!-- END GENERATED: sdk-install -->
16+
317
Go example showing how to integrate the `aasm` CLI runtime sidecar into a Go agent workflow.
418

519
## What this example demonstrates

‎go/langchaingo/README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,19 @@
11
# langchaingo
22

3+
<!-- BEGIN GENERATED: sdk-install -->
4+
<!-- This block is generated by scripts/generate_example_metadata.py. -->
5+
<!-- Edit metadata/sdk-versions.yaml and re-run the generator. -->
6+
| Requirement | Version |
7+
|---|---|
8+
| Agent Assembly Go SDK (`github.com/ai-agent-assembly/go-sdk`) | v0.0.1-rc.3 |
9+
10+
Install:
11+
12+
```bash
13+
go get github.com/ai-agent-assembly/go-sdk@v0.0.1-rc.3
14+
```
15+
<!-- END GENERATED: sdk-install -->
16+
317
Go example showing how to govern a [LangChainGo](https://github.com/tmc/langchaingo)
418
agent's tool calls with Agent Assembly.
519

‎go/tool-policy/README.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,19 @@
11
# tool-policy
22

3+
<!-- BEGIN GENERATED: sdk-install -->
4+
<!-- This block is generated by scripts/generate_example_metadata.py. -->
5+
<!-- Edit metadata/sdk-versions.yaml and re-run the generator. -->
6+
| Requirement | Version |
7+
|---|---|
8+
| Agent Assembly Go SDK (`github.com/ai-agent-assembly/go-sdk`) | v0.0.1-rc.3 |
9+
10+
Install:
11+
12+
```bash
13+
go get github.com/ai-agent-assembly/go-sdk@v0.0.1-rc.3
14+
```
15+
<!-- END GENERATED: sdk-install -->
16+
317
Go example showing explicit allow and deny behavior using Agent Assembly policy governance.
418

519
## What this example demonstrates

‎metadata/sdk-versions.yaml‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Shared SDK version pins consumed by scripts/generate_example_metadata.py.
2+
#
3+
# This file is the single source of truth for the Agent Assembly SDK versions
4+
# advertised across every example sub-project in this repo (python/*, node/*,
5+
# go/*, and scenarios/*).
6+
#
7+
# Bump policy:
8+
# - Edit this file only on a new SDK release. Update the `version` fields to
9+
# the newly released SDK versions.
10+
# - Then run `python scripts/generate_example_metadata.py` from the repo root.
11+
# The generator rewrites every affected manifest (pyproject.toml,
12+
# package.json, go.mod) and every bounded README block.
13+
# - CI enforces drift (see `.github/workflows/example-metadata-check.yml`):
14+
# any hand-edit of a pin or an SDK version literal in a bounded README block
15+
# will fail the drift check.
16+
#
17+
# Values here MUST match what is currently pinned in the manifests — this file
18+
# does not perform version bumps; it captures the current release pins.
19+
20+
python:
21+
package: "agent-assembly"
22+
version: "0.0.1rc3"
23+
install_pip: "pip install agent-assembly=={{version}}"
24+
install_uv: "uv add agent-assembly=={{version}}"
25+
26+
node:
27+
package: "@agent-assembly/sdk"
28+
version: "0.0.1-rc.3"
29+
install_pnpm: "pnpm add @agent-assembly/sdk@{{version}}"
30+
install_npm: "npm install @agent-assembly/sdk@{{version}}"
31+
install_yarn: "yarn add @agent-assembly/sdk@{{version}}"
32+
33+
go:
34+
module: "github.com/ai-agent-assembly/go-sdk"
35+
version: "v0.0.1-rc.3"
36+
install: "go get github.com/ai-agent-assembly/go-sdk@{{version}}"

‎node/custom-tool-policy/README.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,23 @@
11
# custom-tool-policy
22

3+
<!-- BEGIN GENERATED: sdk-install -->
4+
<!-- This block is generated by scripts/generate_example_metadata.py. -->
5+
<!-- Edit metadata/sdk-versions.yaml and re-run the generator. -->
6+
| Requirement | Version |
7+
|---|---|
8+
| Agent Assembly Node.js SDK (`@agent-assembly/sdk`) | 0.0.1-rc.3 |
9+
10+
Install:
11+
12+
```bash
13+
pnpm add @agent-assembly/sdk@0.0.1-rc.3
14+
# or
15+
npm install @agent-assembly/sdk@0.0.1-rc.3
16+
# or
17+
yarn add @agent-assembly/sdk@0.0.1-rc.3
18+
```
19+
<!-- END GENERATED: sdk-install -->
20+
321
A minimal TypeScript example showing how to use Agent Assembly governance directly — no agent framework required.
422

523
## What this example demonstrates

‎node/langchain-js-basic-agent/README.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,23 @@
11
# langchain-js-basic-agent
22

3+
<!-- BEGIN GENERATED: sdk-install -->
4+
<!-- This block is generated by scripts/generate_example_metadata.py. -->
5+
<!-- Edit metadata/sdk-versions.yaml and re-run the generator. -->
6+
| Requirement | Version |
7+
|---|---|
8+
| Agent Assembly Node.js SDK (`@agent-assembly/sdk`) | 0.0.1-rc.3 |
9+
10+
Install:
11+
12+
```bash
13+
pnpm add @agent-assembly/sdk@0.0.1-rc.3
14+
# or
15+
npm install @agent-assembly/sdk@0.0.1-rc.3
16+
# or
17+
yarn add @agent-assembly/sdk@0.0.1-rc.3
18+
```
19+
<!-- END GENERATED: sdk-install -->
20+
321
A LangChain.js-style agent example showing how to integrate the Agent Assembly Node.js SDK for tool governance.
422

523
## What this example demonstrates

0 commit comments

Comments
 (0)