# CrowdAlpha AgentLayer Guide

CrowdAlpha is the data funnel for AI agents: an aggregated, value-added,
paywalled funnel for authorized data-consuming agents. It provides
evidence-linked Planetary Model context, context gaps, blockers, and
next-action posture from licensed, paywalled, public, and customer-approved
data. Use the Planetary Model for governed human review and source of truth.
Use AgentLayer for authorized agents, automations, managed fleets, and software
systems. `WorldState` remains a compatibility term in legacy route, schema, and
API names.

## Products

- **Planetary Model**: governed truth layer for domain packages, decision
  reads, evidence bundles, workflow review, context-gap discovery, and
  next-action posture.
- **AgentLayer**: product layer for authorized agents and software systems that
  need records, evidence, updates, decision-input access, and governed discovery
  leads.
- **Domain packages**: sellable coverage areas such as maritime war-risk and
  sanctions, energy infrastructure, logistics, conflict/security, commodities,
  space/aerospace, critical minerals/mining, and other approved domains.
- **Decision inputs**: records shaped for underwriting, routing, compliance,
  exposure, risk, operations, treasury, engineering, and agent workflows.
- **Discovery leads**: evidence-linked prompts for stale assumptions, missing
  evidence, hidden exposure, policy gaps, route or market shifts, operational
  friction, avoidable losses, and missed opportunities. They are not confirmed
  facts unless Planetary Model records support them.

## Recommended Public Context

- `/worldstate`
- `/worldstate/maritime`
- `/worldstate/packages`
- `/worldstate/decision-inputs`
- `/agentlayer`
- `/agentlayer/protocol`
- `/agentlayer/mcp`
- `/agentlayer/openapi`
- `/agentlayer/examples`
- `/agentlayer/trust`
- `/why`
- `/platform`
- `/solutions`
- `/access`
- `/security`

## Authorized Interfaces

Authentication:

- Machine callers use `Authorization: Bearer ca_agent_<public_prefix>_<secret>`.
- Agent keys are provisioned for approved clients and are visible only once.
  CrowdAlpha stores key hashes and public prefixes, not raw API keys.
- Bound agent keys enforce entitlement manifests on context resolution, broad
  entity, transition, evidence, observation, Core1 decision-record, and
  event-stream reads. Filtered responses include redaction metadata; explicitly
  denied entity, stream, or event-type requests fail closed.
- Existing JWT/session auth remains available for human dashboard and admin
  flows.

Agent-to-agent discovery:

- `GET /.well-known/agent-card.json`
- `GET /api/v1/a2a/agent-card`
- `GET /api/v1/a2a/extendedAgentCard`
- `POST /api/v1/a2a/message:send`

The website-hosted `/.well-known/agent-card.json` points supported A2A clients
to `https://api.crowdalpha.ai/api/v1/a2a`; authorized message calls still use
the API domain and require bearer auth.

A2A V1 is a read-first facade over existing `/api/v1` contracts. It supports
synchronous `message:send` for context resolution, world context, state diff,
composite scores, sanctions exposure, state-package decision inputs, by-id
evidence resolution, package readiness, state-package query reports, read-only
package simulation metadata, and Core1 decision records.
It does not run simulations, create branches, persist A2A tasks, stream task
updates, delegate outbound, or mutate the Planetary Model.

Current A2A skills:

- `crowdalpha.resolve_context`
- `crowdalpha.world_query`
- `crowdalpha.world_context`
- `crowdalpha.state_diff`
- `crowdalpha.composite_scores`
- `crowdalpha.sanctions_exposure`
- `crowdalpha.state_package_decision_inputs`
- `crowdalpha.evidence_by_id`
- `crowdalpha.state_packages`
- `crowdalpha.state_package_query`
- `crowdalpha.state_package_simulations`
- `crowdalpha.core1_decision_records`

`crowdalpha.evidence_by_id` resolves one `observation:<id>` evidence ref
through `GET /api/v1/evidence/{evidence_id}` and preserves the AgentLayer
envelope for the returned `EvidenceObservation`.

The package-readiness A2A skill applies the same scoped AgentClient
blocker-detail redaction as `GET /api/v1/state-packages`.
The state-package query A2A skill is read-first over
`POST /api/v1/state-packages/{package_id}/query`; for maritime reports it
preserves `WorldQueryPlan`, evidence refs, blockers, and claim-validated
`answer.report` fields in the AgentLayer envelope.
The general AgentLayer WorldQuery REST route and A2A skill are
`POST /api/v1/world-query` and `crowdalpha.world_query`; they accept arbitrary
governed natural-language questions, require live AI interpretation for
non-blocked answers, run the read-only WorldQuery DB/RAG/tool runtime, and
return evidence refs, blockers, search-alias projection audit, and
no-activation metadata.
The package-simulation A2A skill is read-only over visible branch metadata; it
does not run package simulations or create counterfactual branches.

Package-readiness responses include both blocker codes and `blockerDetails`.
Agents should cite those details for feed-rights row refs, Core1 trainability
gates, composite-profile status, coverage keys, and next actions when a package
is blocked from production posture. Scoped AgentClient package-list reads retain
blocker codes and coverage but redact package-wide blocker-detail context unless
the entitlement is unscoped or allow-all.
Package state reads use `StatePackageStateResponse`, including package
identity, entity views, typed transition/evidence/contradiction/causal-path
rows, readiness, simulation presets, count, and provenance. Package discovery
reads use `StatePackageDiscoveryResponse` to return direct-support posture,
governed gaps, evidence, blockers, supported actions, and fail-closed
`INSUFFICIENT_DATA` posture when a customer-facing answer is not yet supported.
For maritime, discovery may include nullable `mvp_context` for the
Shanghai/Yangshan Port Expert lane: 10,000 vessels, 365 days, proof gates,
cargo fail-closed policy, and real-source/replay/AgentLayer blockers.

`GET /api/v1/schemas` advertises `StatePackagesResponse`,
`StatePackageReadiness`, and `StatePackageBlockerDetail`; the filtered OpenAPI
contract tags `GET /api/v1/state-packages` with
`responseSchema=StatePackagesResponse`.
Onboarding, context resolution, world-context, diff, and composite-score stable
contracts also expose `responseSchema` names in capabilities and filtered
OpenAPI.
Entity search, entity state, transitions, evidence, causal paths, generic
decision inputs, and event streams expose conservative response schema names as
well.
Transition rows use the `TransitionEnvelope` schema for entity-state,
relationship-state, and regime-state variants, including uncertainty, evidence
sufficiency, causal-driver, replay/origin, and quarantine fields.
Evidence rows use `EvidenceObservation`, including observation identity,
entity/state-variable linkage, source reliability, adapter metadata,
calibrated output, uncertainty, refs, raw evidence, and timestamps.
Package contradiction rows use `StatePackageContradiction`, including claim or
relationship kind, claim IDs, severity, status, resolution, evidence, and
detection/resolution timestamps.
Package causal-path rows use `StatePackageCausalPath`, including cause/effect
entities, variables, deltas, lag, magnitude, confidence, path metadata, source
transition IDs, and timestamps.
Package simulation rows use `StatePackageSimulation` branch metadata. Treat
them as counterfactual simulation records, not observed Planetary Model state.
Event-stream rows use `EventStreamEvent`, including event identity, cursor,
stream/event type, source, aggregate, partition, payload hash, payload,
provenance, and timestamps.
Causal path rows use `CausalPath`, `CausalPathResult`, and optional
`CausalAttribution` schemas for propagation runs, result edges, deltas,
confidence, path metadata, and observed attribution evidence.
The sanctions-exposure decision input and Core1 read surfaces expose
`SanctionsExposureInputResponse`, `Core1DecisionRecordsResponse`, and
`Core1SanctionsExposureThinSliceResponse`; the Core1 schemas preserve
`candidate_observation_v1` and `mayMutateStateDirectly=false`.

AgentLayer also advertises `agent_error_model_v1` through
`GET /api/v1/capabilities`, `GET /api/v1/schemas`, and filtered OpenAPI.
Stable routes use `AgentErrorResponse` as the default error schema. Current
failures use either `detail.error.{code,message}` for shared auth envelopes or
`detail.{code,message}` for direct AgentLayer guards. Common codes include
`UNAUTHORIZED`, `AGENT_CLIENT_DENIED`, `AGENT_SCOPE_DENIED`,
`AGENT_ENTITLEMENT_DENIED`, `AGENT_WEBHOOK_ENTITLEMENT_REQUIRED`,
`AGENT_EVENT_STREAM_ENTITLEMENT_REQUIRED`,
`AGENT_EVENT_STREAM_ENTITLEMENT_DENIED`, `AGENT_EVIDENCE_NOT_FOUND`,
`AGENT_EVIDENCE_INVALID_ID`, `AGENT_RATE_LIMITED`,
`AGENT_RATE_LIMITER_UNAVAILABLE`, `AGENT_SIMULATION_QUOTA_EXCEEDED`, and
`AGENT_WORLDSTATE_CONTRACT_INVALID`.
Package simulation direct runs that return hidden result refs fail closed with
`AGENT_ENTITLEMENT_DENIED` and the message
`Agent entitlement does not allow this state-package simulation result.` Treat
that response as a denial, not as a usable branch result.
Error bodies must not expose raw bearer tokens, raw AgentLayer keys, webhook
secrets, secret refs, or reusable signatures.

`GET /api/v1/state-packages/decision-inputs` is a stable `decision.read` route
for package-native decision inputs and accepts `decisionInputId` for filtered
reads. MCP exposes it as `world_get_state_package_decision_inputs`, and the
TypeScript/Python Agent SDKs expose matching helpers. The MCP tool preserves
the REST AgentLayer envelope, route-derived `sourceRefs`, uncertainty, and
`packageProvenance` lineage.

Agent discovery tasks:

- Ask what changed, what is missing, and which weak assumption may be costly.
- Scan only licensed, public, and customer-approved context available to the
  caller.
- Return evidence, blockers, uncertainty, entitlement posture, and next-action
  posture.
- Treat stale assumptions, missing evidence, hidden exposure, operational
  friction, avoidable losses, and missed opportunities as discovery leads until
  governed records support a stronger answer.

- `GET /api/v1/capabilities`
- `GET /api/v1/schemas`
- `GET /api/v1/openapi.json`
- `GET /api/v1/onboarding`
- `GET /api/v1/coverage`
- `GET /api/v1/health`
- `GET /api/v1/entities`
- `POST /api/v1/context/resolve`
- `POST /api/v1/world-query`
- `GET /api/v1/world-context`
- `GET /api/v1/diff`
- `GET /api/v1/composite-scores`
- `GET /api/v1/state/entities/{entity_id}`
- `GET /api/v1/transitions`
- `GET /api/v1/evidence`
- `GET /api/v1/evidence/{evidence_id}`
- `GET /api/v1/observations`
- `GET /api/v1/causal-paths`
- `GET /api/v1/decision-inputs`
- `GET /api/v1/state-packages/decision-inputs`
- `GET /api/v1/decision-inputs/sanctions-exposure`
- `GET /api/v1/core1/decision-records`
- `GET /api/v1/core1/thin-slice/sanctions-exposure`
- `GET /api/v1/core1/feed-catalog`
- `GET /api/v1/state-packages`
- `GET /api/v1/state-packages/audit`
- `GET /api/v1/state-packages/{package_id}/state`
- `GET /api/v1/state-packages/{package_id}/discovery`
- `POST /api/v1/state-packages/{package_id}/query`
- `GET /api/v1/state-packages/{package_id}/transitions`
- `GET /api/v1/state-packages/{package_id}/evidence`
- `GET /api/v1/state-packages/{package_id}/contradictions`
- `GET /api/v1/state-packages/{package_id}/causal-paths`
- `GET /api/v1/state-packages/{package_id}/simulations`
- `POST /api/v1/state-packages/{package_id}/simulations`
- `GET /api/v1/state-packages/{package_id}/integrity`
- `GET /api/v1/event-streams`
- `GET /api/v1/webhook-endpoints`
- `GET /api/v1/webhook-deliveries`
- `GET /api/v1/simulations`
- `POST /api/v1/simulations`
- `POST /api/v1/simulations/compare`

Approved-access onboarding:

- `GET /api/v1/onboarding` returns the approved AgentClient/API-key path,
  token environment variables, first calls, SDK availability, explicit disabled
  OAuth-client policy, and explicit blockers for self-serve sandbox access.
- The TypeScript and Python Agent SDKs expose this first call as
  `client.onboarding()`.
- Approved-access sample clients live at
  `packages/agent-sdk/examples/approved-access-first-call.ts` and
  `sdks/python/examples/approved_access_first_call.py`. They require
  `CROWDALPHA_API_TOKEN`, read onboarding policy first, fail closed on
  unexpected self-serve OAuth/sandbox availability, and preserve structured
  AgentLayer error codes.
- The onboarding contract is read-only. It does not mint keys, create
  entitlements, create public OAuth clients, exchange OAuth tokens, issue
  sandbox keys, or bypass approved access review.

Interface files:

- `/agents.md`
- `/.well-known/crowdalpha-agent.json`
- `/.well-known/agent-card.json`
- `/.well-known/mcp.json`
- `/.well-known/openapi.json`
- `/llms.txt`
- `/llms-full.txt`

## Rules For Agents

- Treat public pages as product context, not production data.
- Use authorized AgentLayer responses for agent and software workflows.
- Treat CrowdAlpha as approved-access agent-market infrastructure, not
  ungoverned human retail or consumer self-serve access.
- Preserve confidence, uncertainty, evidence references, `interfaceProvenance`,
  provenance, and entitlements when summarizing or citing CrowdAlpha.
- Preserve `entitlements.mode`, scopes, client metadata, redaction, blockers,
  and `asOf` in downstream agent traces.
- Do not invent facts outside returned records and evidence.
- Treat scenarios and hypothetical analysis as separate from observed records.
- Treat discovery leads as leads until Planetary Model evidence, freshness,
  rights, and entitlement checks support the answer.