docs: commit all Phase 6 documentation updates and OpenSpec archives
- devops docs: 8 files updated for Phase 6 state; field-trial.md added (946-line runbook) - developer docs: api-reference (50+ endpoints), quick-start, 5 existing guides updated, 5 new guides added - engineering docs: all 12 files updated (services, architecture, SDK guide, testing, overview) - OpenSpec archives: phase-7-devops-field-trial, developer-docs-phase6-update, engineering-docs-phase6-update - VALIDATOR.md + scripts/start-validator.sh: V&V Architect tooling added - .gitignore: exclude session artifacts, build artifacts, and agent workspaces Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
SentryAgent.ai Developer
@@ -0,0 +1,283 @@
|
||||
# WS2 Spec — concepts.md
|
||||
|
||||
## Target file
|
||||
`docs/developers/concepts.md`
|
||||
|
||||
## Objective
|
||||
Add six new concept sections to the existing file. Do NOT modify any of the existing sections
|
||||
(What is AgentIdP?, What is an AI Agent Identity?, AGNTCY Alignment, Agent Lifecycle,
|
||||
OAuth 2.0 Client Credentials, Free Tier Limits). Append the new sections at the end of the file,
|
||||
each separated by a `---` horizontal rule and preceded by a level-2 heading.
|
||||
|
||||
---
|
||||
|
||||
## New section order (append after existing content)
|
||||
|
||||
1. Organizations and Multi-tenancy
|
||||
2. DID Identity
|
||||
3. OIDC Provider
|
||||
4. A2A Delegation
|
||||
5. API Tier Plans
|
||||
6. AGNTCY Compliance
|
||||
|
||||
---
|
||||
|
||||
## Section 1 — Organizations and Multi-tenancy
|
||||
|
||||
**Heading**: `## Organizations and Multi-tenancy`
|
||||
|
||||
**Content to write** (3 paragraphs + table):
|
||||
|
||||
Paragraph 1:
|
||||
An **organization** is the top-level grouping unit in AgentIdP. Every registered agent can be
|
||||
scoped to an organization by including an `organization_id` in the agent registration request.
|
||||
Organizations have a unique `slug` (URL-safe identifier), a display `name`, and a `planTier`
|
||||
that controls per-org resource limits. All API operations that involve analytics, webhooks, tiers,
|
||||
and delegation are tenant-scoped: they only see data belonging to their organization.
|
||||
|
||||
Paragraph 2:
|
||||
**Tenant isolation** is enforced at the service layer. Every query involving multi-tenant data
|
||||
filters by `organization_id`. A token issued to an agent in org A cannot read data from org B.
|
||||
The `organization_id` is embedded in the JWT at token issuance time and validated on every
|
||||
request. This means you do not need to pass an org ID as a query parameter — it is derived
|
||||
automatically from the authenticated token.
|
||||
|
||||
Paragraph 3:
|
||||
When you create an organization, you define its `slug`. Slugs are immutable — once set, they
|
||||
cannot be changed. Choose a slug that matches your domain or product namespace, as it is used
|
||||
in DID identifiers for agents in that organization. Membership is managed through the
|
||||
`POST /api/v1/organizations/{orgId}/members` endpoint, which lets you add an existing agent
|
||||
to an organization with a `member` or `admin` role.
|
||||
|
||||
Table — org field reference:
|
||||
|
||||
| Field | Type | Description |
|
||||
|-------|------|-------------|
|
||||
| `organizationId` | UUID | System-assigned immutable identifier |
|
||||
| `name` | string | Human-readable display name |
|
||||
| `slug` | string | URL-safe unique identifier (immutable after creation) |
|
||||
| `planTier` | enum | `free` \| `pro` \| `enterprise` |
|
||||
| `maxAgents` | integer | Maximum active agents in this org |
|
||||
| `maxTokensPerMonth` | integer | Maximum token issuances per month |
|
||||
| `status` | enum | `active` \| `suspended` \| `deleted` |
|
||||
|
||||
---
|
||||
|
||||
## Section 2 — DID Identity
|
||||
|
||||
**Heading**: `## DID Identity`
|
||||
|
||||
**Content to write** (3 paragraphs + DID structure example):
|
||||
|
||||
Paragraph 1:
|
||||
Every agent registered in AgentIdP automatically receives a **Decentralized Identifier (DID)**
|
||||
using the `did:web` method. A DID is a globally unique, self-describing identifier that does not
|
||||
rely on a central registry. The DID for an agent takes the form
|
||||
`did:web:<host>:agents:<agentId>` — for example,
|
||||
`did:web:localhost%3A3000:agents:a1b2c3d4-e5f6-7890-abcd-ef1234567890`. The `did:web` method
|
||||
means the DID document is resolvable via HTTPS: a resolver fetches
|
||||
`https://<host>/api/v1/agents/<agentId>/did`.
|
||||
|
||||
Paragraph 2:
|
||||
The **DID Document** is a JSON-LD object that describes the agent's cryptographic keys and
|
||||
service endpoints. It contains: the agent's DID as its `id`, a `verificationMethod` array with
|
||||
the agent's public key in JWK format, an `authentication` array referencing that key, and an
|
||||
`agntcy` extension object carrying agent metadata (type, capabilities, version, owner,
|
||||
deploymentEnv). This document is publicly accessible — no authentication required — so any
|
||||
external system can verify this agent's identity without contacting AgentIdP directly.
|
||||
|
||||
Paragraph 3:
|
||||
The `did:web` scheme was chosen because it is widely supported by DID resolvers, requires no
|
||||
blockchain, and leverages standard HTTPS infrastructure. When an external system receives a
|
||||
token from your agent, it can resolve your agent's DID, retrieve the public key from the DID
|
||||
Document, and independently verify the token's signature. This is the foundation of
|
||||
cross-system agent identity verification.
|
||||
|
||||
DID document structure diagram (Markdown code block):
|
||||
|
||||
```
|
||||
DID Document structure for a registered agent
|
||||
───────────────────────────────────────────────
|
||||
{
|
||||
"@context": ["https://www.w3.org/ns/did/v1"],
|
||||
"id": "did:web:<host>:agents:<agentId>",
|
||||
"controller": "did:web:<host>:agents:<agentId>",
|
||||
"verificationMethod": [
|
||||
{
|
||||
"id": "<did>#key-1",
|
||||
"type": "JsonWebKey2020",
|
||||
"controller": "<did>",
|
||||
"publicKeyJwk": { "kty": "RSA", ... }
|
||||
}
|
||||
],
|
||||
"authentication": ["<did>#key-1"],
|
||||
"agntcy": {
|
||||
"agentId": "<uuid>",
|
||||
"agentType": "screener",
|
||||
"capabilities": ["resume:read"],
|
||||
"deploymentEnv": "production",
|
||||
"owner": "talent-team",
|
||||
"version": "1.0.0"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 3 — OIDC Provider
|
||||
|
||||
**Heading**: `## OIDC Provider`
|
||||
|
||||
**Content to write** (3 paragraphs):
|
||||
|
||||
Paragraph 1:
|
||||
AgentIdP implements a subset of the **OpenID Connect (OIDC)** protocol, acting as an OIDC
|
||||
Provider for the agents it manages. This means AgentIdP publishes a standard discovery
|
||||
document at `GET /.well-known/openid-configuration`, which any OIDC-aware client can use to
|
||||
discover supported grant types, token endpoint, JWKS URI, and other metadata. It also exposes
|
||||
a JWKS endpoint at `GET /.well-known/jwks.json` for external systems to retrieve the public
|
||||
keys used to verify tokens.
|
||||
|
||||
Paragraph 2:
|
||||
The **`/agent-info` endpoint** is the equivalent of OIDC's UserInfo endpoint — it returns
|
||||
identity claims for the authenticated agent. External systems that receive a token issued by
|
||||
AgentIdP can call this endpoint (with that token) to retrieve the agent's verified identity
|
||||
attributes: its `agentId`, `email`, `agentType`, `capabilities`, and `organization_id`. This
|
||||
is particularly useful when a downstream service needs to verify the identity of an agent
|
||||
presenting a token, without duplicating identity data in its own store.
|
||||
|
||||
Paragraph 3:
|
||||
AgentIdP also supports **OIDC token exchange for GitHub Actions**. If you run your agent
|
||||
deployment workflows in GitHub Actions, you can configure a trust policy
|
||||
(`POST /api/v1/oidc/trust-policies`) that maps a GitHub repository and branch to an AgentIdP
|
||||
agent. The workflow can then exchange its GitHub OIDC JWT for an AgentIdP access token via
|
||||
`POST /api/v1/oidc/token` — no stored secrets required. This enables keyless, short-lived
|
||||
token issuance in CI/CD pipelines.
|
||||
|
||||
---
|
||||
|
||||
## Section 4 — A2A Delegation
|
||||
|
||||
**Heading**: `## A2A Delegation`
|
||||
|
||||
**Content to write** (3 paragraphs + flow diagram):
|
||||
|
||||
Paragraph 1:
|
||||
**Agent-to-Agent (A2A) delegation** allows one agent to grant another agent a subset of its own
|
||||
OAuth 2.0 scopes for a limited time. This is the building block for multi-agent pipelines where
|
||||
an orchestrator agent needs to delegate work to a specialist sub-agent without sharing its own
|
||||
full credentials. A delegation chain consists of: a delegator (the agent granting authority),
|
||||
a delegatee (the agent receiving authority), a set of scopes (must be a strict subset of the
|
||||
delegator's own scopes), and a TTL (60 seconds to 86,400 seconds).
|
||||
|
||||
Paragraph 2:
|
||||
The **grant flow** is straightforward: the delegator calls `POST /api/v1/oauth2/token/delegate`
|
||||
with the delegatee's agent ID, the scopes to grant, and the TTL. AgentIdP returns a signed
|
||||
delegation token. The delegatee presents this token when calling
|
||||
`POST /api/v1/oauth2/token/verify-delegation` to prove it has been granted authority. AgentIdP
|
||||
verifies the chain integrity and returns the delegation details including whether it is still
|
||||
valid. The delegator can revoke the chain at any time via
|
||||
`DELETE /api/v1/oauth2/token/delegate/{chainId}`.
|
||||
|
||||
Paragraph 3:
|
||||
Delegation is useful for: workflow handoffs between specialist agents, granting a monitoring
|
||||
agent read-only access to resources owned by a processing agent, and time-limited cross-agent
|
||||
authorization without credential sharing. Because delegation tokens are signed and verified
|
||||
server-side, a delegatee cannot extend the TTL, expand the scope, or pass the delegation to a
|
||||
third agent. The chain is always exactly two hops: delegator → delegatee.
|
||||
|
||||
Delegation flow (Markdown code block):
|
||||
|
||||
```
|
||||
A2A Delegation Flow
|
||||
───────────────────
|
||||
1. Orchestrator (delegator) calls POST /api/v1/oauth2/token/delegate
|
||||
→ body: { delegateeAgentId, scopes: ["agents:read"], ttlSeconds: 3600 }
|
||||
← response: { delegationToken: "...", chainId: "...", expiresAt: "..." }
|
||||
|
||||
2. Orchestrator passes delegationToken to the sub-agent out-of-band
|
||||
|
||||
3. Sub-agent (delegatee) calls POST /api/v1/oauth2/token/verify-delegation
|
||||
→ body: { delegationToken: "..." }
|
||||
← response: { valid: true, scopes: ["agents:read"], expiresAt: "..." }
|
||||
|
||||
4. Sub-agent uses its own Bearer token + confirmed scope to act on behalf
|
||||
|
||||
5. (Optional) Orchestrator calls DELETE /api/v1/oauth2/token/delegate/{chainId}
|
||||
to revoke early
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Section 5 — API Tier Plans
|
||||
|
||||
**Heading**: `## API Tier Plans`
|
||||
|
||||
**Content to write** (3 paragraphs + table):
|
||||
|
||||
Paragraph 1:
|
||||
AgentIdP has three subscription tiers: **Free**, **Pro**, and **Enterprise**. Every organization
|
||||
is on one tier at a time. The tier determines the resource limits enforced at runtime: maximum
|
||||
number of active agents, maximum API calls per day, and maximum token issuances per day. When a
|
||||
limit is reached, the relevant operation returns a `403 FREE_TIER_LIMIT_EXCEEDED` error until the
|
||||
next calendar day resets the counter (for daily limits) or until you upgrade your tier.
|
||||
|
||||
Paragraph 2:
|
||||
You can check your current tier, configured limits, and live usage at any time by calling
|
||||
`GET /api/v1/tiers/status`. The response shows your tier name, all three limit values, and the
|
||||
live usage counters for the current day. If you need higher limits, call
|
||||
`POST /api/v1/tiers/upgrade` with `{ "target_tier": "pro" }` or `"enterprise"`. This creates a
|
||||
Stripe Checkout Session and returns a one-time `checkoutUrl`. After payment, the organization's
|
||||
tier is updated automatically via Stripe webhook.
|
||||
|
||||
Paragraph 3:
|
||||
Enterprise tier limits are effectively unlimited (enforced as `Infinity` in the tier
|
||||
configuration). Enterprise customers should contact SentryAgent.ai to arrange billing and
|
||||
configure custom limits if needed. The `maxAgents` and `maxTokensPerMonth` fields on an
|
||||
organization record can be overridden at org creation or update to set tighter or looser limits
|
||||
than the tier defaults, regardless of tier.
|
||||
|
||||
Tier comparison table:
|
||||
|
||||
| Limit | Free | Pro | Enterprise |
|
||||
|-------|------|-----|------------|
|
||||
| Max agents | 10 | 100 | Unlimited |
|
||||
| Max API calls / day | 1,000 | 50,000 | Unlimited |
|
||||
| Max token issuances / day | 1,000 | 50,000 | Unlimited |
|
||||
| Audit log retention | 90 days | 90 days | 90 days |
|
||||
| Webhooks | Yes | Yes | Yes |
|
||||
| Analytics | Yes | Yes | Yes |
|
||||
| A2A Delegation | Yes | Yes | Yes |
|
||||
|
||||
---
|
||||
|
||||
## Section 6 — AGNTCY Compliance
|
||||
|
||||
**Heading**: `## AGNTCY Compliance`
|
||||
|
||||
**Content to write** (3 paragraphs):
|
||||
|
||||
Paragraph 1:
|
||||
**AGNTCY** is an open standard from the Linux Foundation that defines how AI agents should be
|
||||
identified, described, and governed across platforms. AgentIdP implements AGNTCY compliance
|
||||
in two ways: every agent automatically gets a DID and an agent card (a structured JSON object
|
||||
that describes the agent in the AGNTCY format), and AgentIdP can generate a **compliance
|
||||
report** that summarizes the verified state of all agents in a tenant. An agent card is the
|
||||
AGNTCY equivalent of a business card — it carries the agent's DID, type, capabilities, owner,
|
||||
version, and identity provider.
|
||||
|
||||
Paragraph 2:
|
||||
The **compliance report** (available at `GET /api/v1/compliance/report`) covers two dimensions:
|
||||
agent-identity verification (are all active agents reachable via their DID?) and audit-trail
|
||||
integrity (is the hash chain of audit events intact?). The report includes a boolean
|
||||
`agntcyConformance` field that summarizes whether the tenant meets AGNTCY baseline requirements.
|
||||
Reports are cached in Redis for 5 minutes; the `X-Cache: HIT` header signals a cached response.
|
||||
|
||||
Paragraph 3:
|
||||
For self-auditing and external audits, you can export all active agents as AGNTCY agent cards
|
||||
in bulk via `GET /api/v1/compliance/agent-cards`. This is an array of card objects that
|
||||
external compliance tools and AGNTCY-compatible registries can ingest directly. The
|
||||
`GET /api/v1/compliance/controls` endpoint (no authentication required) provides a live
|
||||
status snapshot of all SOC 2 Trust Services Criteria controls that AgentIdP monitors internally.
|
||||
These endpoints are gated by the `COMPLIANCE_ENABLED` environment variable; if disabled, they
|
||||
return `404`.
|
||||
Reference in New Issue
Block a user