ModelScope AgentID Integration

Add AgentID as a machine-caller authentication path while keeping application authorization and existing user authentication explicit.

Non-negotiable identity boundary

AgentID proves that the caller controls the private key bound to the verified AgentID for the requested audience. It does not prove that the model, prompt, code, process, memory, or personality is unchanged.

Treat a verified agent_id like a service-account subject. Never treat token verification alone as authorization for a business action.

Required references

For every implementation, read:

• protocol.md for the current ModelScope issuer, claims, SDKs, endpoints, and token behavior.
• security-boundaries.md for secret handling, guarantees, and failure policy.

Then read only what the task needs:

• application-integration.md for FastAPI, Express, identity mapping, and 401/403 boundaries.
• agent-onboarding.md for Connected App registration, Agent provisioning, and onboarding modes.

Re-check the linked official documentation before changing endpoints, dependencies, claims, or SDK APIs. AgentID is evolving.

Workflow

1. Inspect before changing

Identify:

• application framework and runtime version;
• existing OAuth, session, API-key, or service-account middleware;
• protected routes and current authorization policy;
• environment-variable and dependency conventions;
• test commands and relevant dirty files.

Do not overwrite unrelated user changes. Do not replace existing auth unless the user explicitly asks for migration.

2. Select onboarding policy

Use one explicit mode:

• optional — default; existing auth remains the default and AgentID is added.
• preferred — compatible Agent clients are directed to AgentID while legacy auth remains available.
• disabled — do not advertise or accept AgentID.

Do not infer policy from the request hostname. Publish it explicitly if the application has a discovery manifest.

3. Establish the trust boundary

The application operator must register a ModelScope Agent Identity Connected App and provide its client_id. That value is the exact JWT audience.

The application runtime receives only a short-lived AgentID JWT. It must never receive:

• the Agent private key;
• the user's ModelScope Access Token;
• the signature material used to mint a token.

4. Scaffold outside the target first

Generate a clean reference integration in a temporary directory:

python3 <skill-dir>/scripts/scaffold_integration.py \
  --framework fastapi \
  --output /tmp/agentid-reference \
  --with-manifest \
  --with-bootstrap

Supported framework values are fastapi and express. Use --onboarding-mode optional unless requirements say otherwise. Use --token-transport bearer unless an existing gateway requires a dedicated header.

Inspect generated files before adapting them to the application. Do not copy a complete example over existing middleware.

5. Integrate a narrow verifier

Create one local boundary that:

1. extracts the configured token transport;
2. validates issuer and signature;
3. requires the exact Connected App audience;
4. validates expiry and required subject;
5. exposes a small verified identity object;
6. returns a generic 401 on authentication failure.

Use verified.agent_id or its framework equivalent as the caller subject. Never trust an agent_id in the request body.

6. Keep authorization local

After authentication, separately decide whether this agent_id may perform the requested action. Unknown identities must follow one explicit policy:

• reject;
• invite for review;
• bootstrap an idempotent local mapping.

Use 401 for failed authentication and 403 for an authenticated Agent that lacks permission.

7. Add Agent-side onboarding only when needed

Agent provisioning is a setup-time operation requiring explicit user consent and a ModelScope Access Token. Runtime token acquisition needs only the local Agent identity and private key.

Reuse a single unambiguous local identity. If multiple identities exist, require selection. Never guess or silently clone one private key across different Agent roles.

8. Test and audit

Test at minimum:

• valid token;
• wrong audience;
• invalid issuer or signature;
• expired token;
• missing or malformed subject;
• unknown Agent policy;
• idempotent bootstrap when enabled;
• legacy auth coexistence in optional mode;
• no AgentID exposure in disabled mode.

Run:

python3 <skill-dir>/scripts/verify_integration.py <project-dir>

Do not declare completion while the audit reports errors.

Completion report

Report:

• files created or changed;
• required environment variables and dependencies;
• Connected App registration steps still requiring the operator;
• tests and audit commands executed;
• whether a real ModelScope token round trip was run;
• what the integration proves and what it does not prove.

Never print a JWT, private key, ModelScope Access Token, or request signature.