--- name: agentic-economy description: Pick your entry, search and inspect live Operations, call eligible keyless reads free, and connect only when the selected capability requires it. --- # Agentic Economy — Operation market loop ## 1. Pick your path **AE tools visible in your harness?** Their names begin with `ae_` — registry search, detail, and compare read Operations anonymously and free, so call them directly; invoke/status tools work after one connection. **Not connected yet?** ```sh curl -fsSL https://www.aecon.ai/.well-known/ucp ``` Read `https://www.aecon.ai/llms.txt`, then `https://www.aecon.ai/for-agents`. Install the CLI only for local execution: ```sh npm install --global @agentic-economy/cli export AE_CLI_BASE_URL="https://www.aecon.ai" ae manifest --json ``` If neither entry fits your job, tell your human what you needed. ## Supplier path Owner setup starts at `https://www.aecon.ai/for-providers`, then: ```sh ae connect --supplier --json ae doctor "$AE_BUSINESS_ID" --supplier --json ``` Operation: one job. Preserve identity and revisions; never submit provider keys or count setup tests as earnings. ## 2. Price rule — before any paid call Inspect the Operation, state the total price and the required inputs to your human, and wait for their approval. ## 3. Search by job — anonymous ```sh curl -sS 'https://www.aecon.ai/api/v1/market-operations/search' -H 'content-type: application/json' --data '{"query":"weather forecast","limit":5}' ``` CLI: ```sh ae search "weather forecast" --json ``` HTTP: `POST https://www.aecon.ai/api/v1/market-operations/search`. No account or key. No candidates? If connected: `ae request create ""`, then `ae request status `. This gap is not a task, tender, message, or Operation. ## 4. Inspect one exact Operation — anonymous ```sh curl -sS 'https://www.aecon.ai/api/v1/market-operations/detail' -H 'content-type: application/json' --data '{"operationRef":"operation:v1:…"}' ``` Source-checkout helper: ```sh ae inspect "$AE_OPERATION_REF" --json ``` HTTP detail: `POST https://www.aecon.ai/api/v1/market-operations/detail`. Read the current input schema, terms, price, effects, availability, and evidence before connecting or invoking. Optional anonymous reads: `ae compare` / `ae inspect-plan` mirror `POST https://www.aecon.ai/api/v1/market-operations/compare` and `POST https://www.aecon.ai/api/v1/market-operations/inspect-plan`. `operation.invoke` runs through the authenticated gateway only. Connect once with AE, then invoke; price may be zero, and consequential Operations require explicit authority approval. Public: search, inspect, and eligible free keyless read calls. Connect only when a call reports agent_access_key_required. ## 5. Try the capability; connect only when required ```sh ae call "$AE_OPERATION_REF" --input "$AE_INPUT_JSON" --json ``` Eligible free keyless reads run anonymously through official MCP and return literal output plus an `evidenceHash`. On `agent_access_key_required`, connect once: ```sh ae connect --json ``` Device flow: `POST https://www.aecon.ai/oauth/register` → `POST https://www.aecon.ai/oauth/device_authorization` → approve `https://www.aecon.ai/agent-access/authorize?user_code=...` → `POST https://www.aecon.ai/oauth/token`. Existing `AE_API_KEY` values are validated; nonempty is not proof. The AE key identifies the caller. It never contains or grants a provider credential, endpoint override, payment approval, or silent consequential authority. Use `ae connect --mcp` to write an importable Streamable HTTP MCP connection alongside the origin-bound key. ## 6. Authenticated gateway details HTTP: `POST https://www.aecon.ai/api/v1/operations/call` with `Authorization: Bearer $AE_API_KEY`, `Content-Type: application/json`, and only schema-valid material in the body. Required invoke scope: `market_operations:invoke`. Schema-valid action input example: `{"operationRef":"operation:v1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","input":{},"idempotencyKey":"example-idempotency-key"}`. HTTP POST body example: `{"operationRef":"operation:v1:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","input":{},"idempotencyKey":"example-idempotency-key"}`. The canonical input JSON schema ships in every Operation detail response. The request JSON body field `idempotencyKey` is required. The low-level write API requires `idempotencyKey`; the CLI creates and retains it automatically. The same key with identical material replays the original state; changed material is refused. Never send a provider, URL, method, credential, price, payment recipient, or approval. ## 7. Wait for the recorded result ```sh ae wait "$AE_INVOCATION_REF" --json ``` `ae wait` reads `GET https://www.aecon.ai/api/v1/operations/{invocationRef}` until a result or timeout; it cannot call, retry, or grant authority. `ae status "$AE_INVOCATION_REF" --json` reads once. Outcomes (`result.kind`): `completed | pending | needs_authority | reconciliation_required | refused`. Diagnostics (`found.state`): `gathering_information | awaiting_authority | authorized | leased | in_progress | retryable | reconciliation_required | terminal | cancelled | invalidated`. ## 8. Recover uncertain work ```sh ae recover "$AE_INVOCATION_REF" "$AE_EVIDENCE_JSON" --idempotency-key "$AE_IDEMPOTENCY_KEY" --json ``` Recovery submits bounded evidence through `POST https://www.aecon.ai/api/v1/operations/{invocationRef}/reconcile`. Use the same invocation and original stable key. ## If credit runs short A paid invocation refused with `insufficient_credit` (`retryable: false`) ran nothing; never auto-retry it. Tell your human the balance is short and direct them to add credit at https://www.aecon.ai/owner/credit, then resubmit the same inputs once funded. ## Problem responses and retry rules - Errors are `application/problem+json` with `type`, `title`, `status`, `kind`, `code`, and optional `retryable`. - If `retryable` is true, respect `Retry-After` when present and retry only the same material command identity. - A timeout, `outcome_unknown`, or `reconciliation_required` is not a terminal success and is not permission to create a new invocation; read status, then recover. - Do not retry authentication, validation, authority, or idempotency-conflict problems without changing the invalid input or authority state. ## MCP projection Endpoint: `https://www.aecon.ai/mcp`. Anonymous tools: `ae_registry_search`, `ae_registry_detail`, `ae_registry_operations_search`, `ae_registry_operations_detail`, `ae_registry_operations_compare`, `ae_registry_operations_inspectPlan`. Authenticated tools: `ae_operation_invoke`, `ae_operation_list`, `ae_operation_status`, `ae_operation_cancel`, `ae_operation_reconcile`. Static tool names do not enumerate live Operations. Official MCP SDK lifecycle (protocol `2025-11-25`): connect to `https://www.aecon.ai/mcp` (the client performs initialization); the server is stateless and may omit `Mcp-Session-Id`; call `tools/list` before `tools/call`; close the client transport. ## Business catalog is business-only `registry.search` and `registry.detail` read published businesses; they do not authorize execution. Only an admitted, published Operation is callable. ## Stop rules - Stop when an exact current Operation is unavailable or its terms, required input, price, effects, or evidence are unclear. - Stop on `needs_authority`; only the owner-controlled flow can grant the requested authority. - On `pending`, wait on the recorded invocation or read one status snapshot. On `reconciliation_required`, recover the same invocation before any retry. - Never infer fulfilment, payment, deployment, or a receipt from discovery, a key, a balance, or a request accepted for processing. - Cancel only when the receipt offers cancellation; recover only when it requires reconciliation. ## What counts as proof A job closes only on evidence a response actually returned: anonymous reads carry literal output plus an `evidenceHash`, and invocation results expose usage or evidence fields only when recorded for that result. Without that evidence the job stays unproven — say so rather than claiming success.