Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 3 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Applying this example

Instructions for a coding agent adding A2A Net account linking to an existing web
Instructions for a coding agent adding Agenta account linking to an existing web
app. Read `README.md` first for the flow.

## 1. Add the endpoint
Expand Down Expand Up @@ -41,7 +41,7 @@ and the page share a path and the URL is easy to say out loud.
Wire its props to the app's own auth: `loading` and `isAuthenticated` from
whatever hook the app already uses, and `signIn(returnTo)` to whatever starts the
sign-in flow. Read `token` and `platform` from the query string with the app's own
router — A2A Net sends both, so nothing has to decode a token in the browser.
router — Agenta sends both, so nothing has to decode a token in the browser.

Then restyle it. It renders bare `<main>`, `<h1>` and `<button>` so the states are
readable; use the app's own layout, logo and components. What must survive the
Expand All @@ -57,7 +57,7 @@ holds a bearer token), add the header to the `fetch` in `connect`.

## 4. Set the Customer Sign-In URL

On the agent's Publish page at <https://app.a2anet.com>, in the last step of Slack
On the agent's Publish page at <https://app.buildagenta.com>, in the last step of Slack
or Teams setup, set `https://app.example.com/connect`. It must be https.
Until it is set, the agent runs as its owner rather than as your customers.

Expand Down
16 changes: 8 additions & 8 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# A2A Net Connect Example
# Agenta Connect Example

This is an example implementation of the `/connect` endpoint, which allows
you to authenticate Slack, Teams, and Copilot users with your product.
Expand All @@ -9,18 +9,18 @@ makes it run as each of your customers instead.
## The flow

1. An unlinked user messages the agent — or runs its command, clicks one of its
buttons, or reacts to point it at something. A2A Net posts a **Connect** button
buttons, or reacts to point it at something. Agenta posts a **Connect** button
2. The button opens your Customer Sign-In URL with a ten-minute, single-use token
as `?token=`, and the app they came from as `?platform=`
3. Your page signs the visitor in the way your product already does
4. Your backend asks `POST /api/v1/customer-links/preview` who the token names,
and your page shows it next to who they are signed in as
5. Your backend `POST`s the token and your own identifier for that user to
`POST /api/v1/customer-links`, with your A2A Net API key
6. A2A Net stores the link. It is durable — only the token was short-lived — and
`POST /api/v1/customer-links`, with your Agenta API key
6. Agenta stores the link. It is durable — only the token was short-lived — and
the user's next message runs as that customer

A2A Net never sees the customer's credentials.
Agenta never sees the customer's credentials.

## Files

Expand All @@ -36,8 +36,8 @@ credential:

| Variable | What it is |
| ---------------- | ------------------------------------------------------------------- |
| `A2ANET_API_KEY` | A standard user API key, minted at <https://app.a2anet.com/api-keys> |
| `A2ANET_API_URL` | `https://app.a2anet.com/api/v1` |
| `A2ANET_API_KEY` | A standard user API key, minted at <https://app.buildagenta.com/api-keys> |
| `A2ANET_API_URL` | `https://app.buildagenta.com/api/v1` |

## Your Customer Sign-In URL

Expand All @@ -54,7 +54,7 @@ https://app.example.com/connect
| --------------------- | -------------------------------------- | ---------------------------- |
| `400 invalid_request` | Expired, tampered with, or not a token | Ask the agent for a new link |
| `409 link_token_used` | The link was already redeemed | Ask for a new one if needed |
| `502` | A2A Net could not be reached | Try again |
| `502` | Agenta could not be reached | Try again |

## Two things to keep

Expand Down
10 changes: 5 additions & 5 deletions package.json
Original file line number Diff line number Diff line change
Expand Up @@ -12,21 +12,21 @@
"test:coverage": "bun test --coverage"
},
"keywords": [
"a2anet",
"agenta",
"agents",
"slack",
"teams"
],
"author": "A2A Net <hello@a2anet.com>",
"author": "Agenta <hello@buildagenta.com>",
"license": "Apache-2.0",
"repository": {
"type": "git",
"url": "https://github.com/a2anet/a2anet-connect-example.git"
"url": "https://github.com/buildagenta/connect-example.git"
},
"bugs": {
"url": "https://github.com/a2anet/a2anet-connect-example/issues"
"url": "https://github.com/buildagenta/connect-example/issues"
},
"homepage": "https://github.com/a2anet/a2anet-connect-example#readme",
"homepage": "https://github.com/buildagenta/connect-example#readme",
"devDependencies": {
"@biomejs/biome": "^1.9.0",
"@types/bun": "latest",
Expand Down
6 changes: 3 additions & 3 deletions src/connect-page.tsx
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// SPDX-FileCopyrightText: 2026-present A2A Net <hello@a2anet.com>
// SPDX-FileCopyrightText: 2026-present Agenta <hello@buildagenta.com>
//
// SPDX-License-Identifier: Apache-2.0

Expand Down Expand Up @@ -69,12 +69,12 @@ export function statusContent(status: ConnectStatus, platform: string): StatusCo
}

/**
* Names the chat account a link would bind to, as specifically as A2A Net can.
* Names the chat account a link would bind to, as specifically as Agenta can.
*
* Show this next to who the visitor is signed in as. Someone who was sent a
* link they did not ask for is reading the only line on the page that can tell
* them so.
* @param description What your server got back from A2A Net, if anything.
* @param description What your server got back from Agenta, if anything.
* @returns A phrase such as "Slack (@alice in Acme Corp)".
*/
export function identityLabel(description: LinkDescription | undefined): string {
Expand Down
12 changes: 6 additions & 6 deletions src/connect.ts
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
// SPDX-FileCopyrightText: 2026-present A2A Net <hello@a2anet.com>
// SPDX-FileCopyrightText: 2026-present Agenta <hello@buildagenta.com>
//
// SPDX-License-Identifier: Apache-2.0

/**
* `POST /connect` — the endpoint that turns a Slack or Teams user into one
* of your customers.
*
* The link token arrives in the browser, from the Connect button A2A Net posted
* The link token arrives in the browser, from the Connect button Agenta posted
* to an unlinked user. It names that platform user and nothing else; who they are
* in *your* product is a question only you can answer, which is why this exchange
* happens on your server, against your session, with your API key.
Expand All @@ -24,7 +24,7 @@ export type ConnectResult = { connected: true } | { connected: false; reason: Co
/**
* Who a link token names, for the page to show before anyone clicks Connect.
*
* Absent names are normal: a platform only tells A2A Net what it will, and Teams
* Absent names are normal: a platform only tells Agenta what it will, and Teams
* will not name a tenant at all.
*/
export interface LinkDescription {
Expand Down Expand Up @@ -52,7 +52,7 @@ const env = (name: string): string => {
};

/**
* Redeems a link token against A2A Net, binding it to one of your customers.
* Redeems a link token against Agenta, binding it to one of your customers.
* @param linkToken The `?token=` the Connect button carried into the browser.
* @param customerId Your own identifier for the signed-in user.
* @param values Per-customer variables and secrets for this customer's runs.
Expand Down Expand Up @@ -87,7 +87,7 @@ export async function redeemLinkToken(
}

/**
* Asks A2A Net who a link token names, without redeeming it.
* Asks Agenta who a link token names, without redeeming it.
*
* Show what this returns. A link token is a bearer credential: whoever holds the
* URL can click Connect, so an attacker only has to get their own Connect link
Expand Down Expand Up @@ -134,7 +134,7 @@ const STATUS_BY_REASON: Record<ConnectFailure, number> = {
const MESSAGE_BY_REASON: Record<ConnectFailure, string> = {
invalid: "This connection link is invalid or has expired",
used: "This connection link has already been used",
unreachable: "A2A Net could not be reached",
unreachable: "Agenta could not be reached",
};

const json = (body: unknown, status: number): Response =>
Expand Down
18 changes: 9 additions & 9 deletions tests/connect.test.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// SPDX-FileCopyrightText: 2026-present A2A Net <hello@a2anet.com>
// SPDX-FileCopyrightText: 2026-present Agenta <hello@buildagenta.com>
//
// SPDX-License-Identifier: Apache-2.0

Expand Down Expand Up @@ -37,7 +37,7 @@ const post = (body: unknown): Request =>
});

beforeEach(() => {
process.env.A2ANET_API_URL = "https://app.a2anet.com/api/v1";
process.env.A2ANET_API_URL = "https://app.buildagenta.com/api/v1";
process.env.A2ANET_API_KEY = "a2anet_test";
});

Expand Down Expand Up @@ -67,7 +67,7 @@ describe("redeemLinkToken", () => {
});
});

test("reports A2A Net being unreachable", async () => {
test("reports Agenta being unreachable", async () => {
globalThis.fetch = (async () => {
throw new Error("network");
}) as unknown as typeof fetch;
Expand Down Expand Up @@ -97,7 +97,7 @@ describe("redeemLinkToken", () => {
describe("handleConnectRequest", () => {
const authenticated = async (): Promise<string> => "customer-1";

test("refuses an unauthenticated caller before reaching A2A Net", async () => {
test("refuses an unauthenticated caller before reaching Agenta", async () => {
respondWith(200);
const handler = handleConnectRequest(async () => null);
expect((await handler(post({ token: "token" }))).status).toBe(401);
Expand All @@ -117,7 +117,7 @@ describe("handleConnectRequest", () => {
expect(await response.json()).toEqual({ connected: true });
});

test("passes A2A Net's refusal through as its own status", async () => {
test("passes Agenta's refusal through as its own status", async () => {
respondWith(409);
const handler = handleConnectRequest(authenticated);
expect((await handler(post({ token: "token" }))).status).toBe(409);
Expand Down Expand Up @@ -145,12 +145,12 @@ describe("previewLinkToken", () => {
});
});

test.each([400, 404, 500])("has nothing to show when A2A Net answers %i", async (status) => {
test.each([400, 404, 500])("has nothing to show when Agenta answers %i", async (status) => {
respondWith(status);
expect(await previewLinkToken("token")).toBeNull();
});

test("has nothing to show when A2A Net is unreachable", async () => {
test("has nothing to show when Agenta is unreachable", async () => {
globalThis.fetch = (async () => {
throw new Error("network");
}) as unknown as typeof fetch;
Expand All @@ -161,7 +161,7 @@ describe("previewLinkToken", () => {
describe("handlePreviewRequest", () => {
const authenticated = async (): Promise<string> => "customer-1";

test("refuses an unauthenticated caller before reaching A2A Net", async () => {
test("refuses an unauthenticated caller before reaching Agenta", async () => {
respondWith(200, DESCRIPTION);
const handler = handlePreviewRequest(async () => null);
expect((await handler(post({ token: "token" }))).status).toBe(401);
Expand All @@ -186,7 +186,7 @@ describe("handlePreviewRequest", () => {
});
});

test("reports a token A2A Net will not preview as invalid", async () => {
test("reports a token Agenta will not preview as invalid", async () => {
respondWith(400);
const handler = handlePreviewRequest(authenticated);
expect((await handler(post({ token: "token" }))).status).toBe(400);
Expand Down
Loading