Documentation / 0.1 draft
From a file to a working contract.
Build a profile, test its behavior, and integrate it into the tools you already use.
MCP, WebMCP, A2A, and Agent Auth
Connect the local MCP tools, generate discovery files, and see which integrations are implemented.
Read the guide Start hereQuick start
Run the ticket service, lose a response, and recover the original result.
Read the guide ReferenceSpecification
Versioned fields, client and service requirements, and the supported OpenAPI binding.
Read the guide IntegrationIntegration guide
Connect an existing API or agent runtime. Keep authorization and recovery boundaries explicit.
Read the guide TestingCompatibility runner
Test a separately implemented client through a small process interface and publish evidence.
Read the guide ProtocolConformance
Understand structural, binding, and behavior checks—and what the tests do not establish.
Read the guide OperationsSecurity and limits
Approved origins, private ledgers, tracking windows, credentials, and unresolved outcomes.
Read the guideQuick start
Requires Node 24 and Python 3.11 or later. This example runs locally and creates synthetic tickets.
git clone https://github.com/sam1siam/agentic.git
cd agentic
npm ci
python -m pip install -r reference/python/requirements.txt
python reference/service/server.py --fault response-lostIn a second terminal, from the same repository:
npm run client -- http://127.0.0.1:4318 pilot-001 "Pilot ticket"
# Repeat the exact command to return the saved receipt.The service commits the ticket and drops its first reply. The client checks the saved request, reads the original ticket, and emits a receipt with outcome: succeeded. Keep the same request ID and input when resuming.
Frequently asked questions
Is this an adopted standard?
No. Agentic is an experimental proposal. The project publishes reference code and is recruiting outside implementers. A stable version needs independent compatibility evidence.
Will agents discover agentic.json automatically?
Only clients that implement this convention can use it. Pass the profile URL explicitly during a pilot. Publishing the file alone does not add support to an agent.
What does a service need?
One JSON POST operation, an authoritative request-status GET, and a resource GET in OpenAPI 3.1, plus atomic request tracking and idempotency scoped to the authenticated principal and action.
How does this relate to other agent files?
llms.txt guides agents to documentation. Discovery manifests describe capabilities and endpoints. Agentic proposes a narrower contract for reconciling an attempted action and verifying its result. See the integration guide for coexistence patterns.
Does the profile make an API safe to call?
No. The agent host still authorizes the action, approves destinations, protects credentials, and isolates ledgers. A publisher’s description is untrusted data.
Does it guarantee exactly-once execution?
No. The service must enforce idempotency. The client avoids automatic repeat writes and uses authoritative status plus evidence. Unresolved cases remain pending or unknown.
What happens when the request window expires?
The client preserves unknown and hands off to its host. It must not assume the action failed or create a fresh request automatically.
Can my team try it without publishing private data?
Yes. Run a local or sandbox pilot. Share redacted results and aggregate counts; do not upload tokens, customer inputs, private receipts, or ledgers.