Rensei docs
Agent Cards

Agent Cards

4-scope model, YAML authoring, extends, and versioning.

Agent Cards are the unit of agent identity on Rensei: a versioned, YAML-authored document that declares what an agent is, what it can do, and what it requires - before a single session runs.

What is an Agent Card

An Agent Card stores the full behavioural specification for one agent in the agent_cards table. The card's card JSONB column holds the rich content (system prompt, responsibilities, output contract, partials, tools, runtime preferences, auth requirements). A set of first-class columns (name, description, workType, scope, version, capabilities, runtimes, trust, auth) are hoisted from that content at write time so the workflow editor's agent picker and the runtime resolver can query them without re-parsing the full document.

Every Agent Card resolves to a stable agent:// URI at the scope it was authored:

ScopeURI pattern
systemagent://system/<name>
orgagent://org/<orgId>/<name>
projectagent://project/<projectId>/<name>
workflowagent://workflow/<workflowId>/<name>

When a version is greater than 1, the URI gains a @<version> suffix (e.g. agent://org/acme/my-agent@3).

The 4-scope model

Rensei resolves Agent Cards using a most-specific-wins cascade: workflow → project → org → system.

Prop

Type

The system scope is operator-only. End-user POST /api/agent-cards rejects scope="system" with 403. Use /api/admin/agents to publish system-scope cards.

Authoring a card via the UI

Navigate to Factory → Agent Cards in your project, then click New card. The editor guides you through the card schema fields and previews the resolved agent:// URI. Cards authored this way default to project scope.

To promote a card to org scope, an org-admin can use the Promote to org action in the card detail view, or submit POST /api/agent-cards with scope="org".

YAML authoring reference

Cards are stored as a JSONB blob with the following top-level structure:

# agent-card.yaml - used for CLI push or import via /api/agent-cards
name: my-dev-agent
description: Implements Linear issues assigned to the agent
workType: development
scope: project   # workflow | project | org  (system = operator-only)

card:
  systemPrompt: |
    You are a senior software engineer working on this codebase.
    Follow the project conventions documented in AGENTS.md.

  responsibilities:
    - Read the Linear issue and any linked PRs
    - Write the code change in a new branch
    - Open a PR and self-review before requesting human review

  outputContract:
    successSignal: pr_opened
    failureSignal: blocked

  partials:
    - id: code-intel           # system partial - auto-resolves
    - id: code-style@2         # pin to version 2
    - id: partial://org/acme/security-checklist   # fully-qualified URI

  runtimes:
    - provider: claude          # Anthropic Claude
      model: claude-opus-4-5
      contextWindow: 200000

  auth:
    - kind: credential
      provider: github
      required: true

  capabilities:
    memory: true
    architecture: true
    code-intel: true

  trust:
    tier: org   # system | org | project | workflow

  tools:
    allow:
      - bash
      - read
      - write
      - edit

  guardrails:
    - id: no-secrets-in-output

  observability:
    evalConfig:
      enabled: true
      graderId: structural-zod

Key fields

Prop

Type

Versioning

Agent Cards use monotonic integer versioning. Every write that changes card, name, description, workType, capabilities, runtimes, auth, or trust increments the version counter. Existing sessions are pinned to the version they started with via agent_session_pins - an in-flight session is never disrupted by an author publishing a new version.

The runtime resolver follows this logic:

  1. Look up the card by (orgId, name) for the caller's scope cascade.
  2. If the session has a pin in agent_session_pins, resolve to that exact version (requires supportsVersionPinning: true on the backing Agent Registry Provider).
  3. Otherwise resolve to the highest published version.

When a provider does NOT support version pinning, the runtime silently falls back to latest and emits an agent.pin-ignored observability event.

REST API

List cards visible to a caller

# Autocomplete shape (default - used by the workflow editor's agent picker)
GET /api/agent-cards?scope=all&projectId=<id>

# Full shape (rich AgentPicker in the editor)
GET /api/agent-cards?format=full&scope=all&projectId=<id>&q=my-dev

# Scope options: all | system | org | project
# limit: 1-200, default 50

Response (format=full):

{
  "cards": [
    {
      "id": "crd_01abc",
      "name": "my-dev-agent",
      "description": "Implements Linear issues",
      "scope": "project",
      "scopeOwnerId": "proj_xyz",
      "version": 3,
      "workType": "development",
      "agentRef": "agent://project/proj_xyz/my-dev-agent@3",
      "hasSystemPrompt": true,
      "requiresAuthConfig": true,
      "authSummary": "credential",
      "capabilities": { "memory": true, "architecture": true },
      "trust": { "tier": "project" },
      "runtimes": [{ "provider": "claude", "model": "claude-opus-4-5" }]
    }
  ]
}

Create a card

POST /api/agent-cards
Content-Type: application/json
Authorization: Bearer rsk_live_...

{
  "scope": "project",
  "projectId": "proj_xyz",
  "name": "my-dev-agent",
  "description": "Implements Linear issues",
  "workType": "development",
  "card": {
    "systemPrompt": "You are ...",
    "partials": [{ "id": "code-intel" }],
    "runtimes": [{ "provider": "claude", "model": "claude-opus-4-5" }]
  }
}

Returns 201 { card: AgentCardListItem } - the full picker shape ready for optimistic render.

Update a card

PUT /api/agent-cards/<id>

Updates the card JSONB and auto-increments version.

Operator routes (admin)

GET  /api/admin/agents           # list all agents across all orgs
GET  /api/admin/agents/<id>
POST /api/admin/agents           # create system-scope card
PUT  /api/admin/agents/<id>
POST /api/admin/agents/<id>/publish   # promote draft → published
POST /api/admin/agents/materialize-preview   # preview ARP reconcile result

Agent Card Partials

Handlebars partials, auto-attach, and version pinning.

On this page

What is an Agent CardThe 4-scope modelAuthoring a card via the UIYAML authoring referenceKey fieldsVersioningREST APIList cards visible to a callerCreate a cardUpdate a cardOperator routes (admin)Related pages