{
  "schemaVersion": "1.0",
  "title": "Run your first AIP action",
  "description": "In this tutorial, you will start one product-neutral AIP daemon on loopback, discover its manifest, invoke the built-in health capability, and inspect the durable action state. You will also view the same capability surface through the MCP ",
  "canonical": "https://getaip.org/docs/getting-started/quickstart",
  "route": "/docs/getting-started/quickstart",
  "source": "docs/getting-started/quickstart.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Start Here",
  "documentType": "Getting started",
  "language": "en",
  "revision": {
    "lastReviewedRevision": "d7cce13d1d555644d04a4d73c66c95b113737635",
    "documentationSourceRevision": "9192fef3695ad294994f2712f6d156241e5e92fb",
    "basis": "frontmatter"
  },
  "downloads": {
    "md": "/docs/download/getting-started/quickstart.md",
    "txt": "/docs/download/getting-started/quickstart.txt",
    "json": "/docs/download/getting-started/quickstart.json",
    "pdf": "/docs/download/getting-started/quickstart.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Run your first AIP action\ndescription: Start a local AIP daemon and inspect one complete native action\nkind: tutorial\naudience: developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"d7cce13d1d555644d04a4d73c66c95b113737635\"\n---\n\n# Run your first AIP action\n\nIn this tutorial, you will start one product-neutral AIP daemon on loopback,\ndiscover its manifest, invoke the built-in health capability, and inspect the\ndurable action state. You will also view the same capability surface through\nthe MCP compatibility profile.\n\nThis path is for developers learning the native request lifecycle. It uses a\nliteral development bearer token and local file-backed state at source revision\n`d7cce13d1d555644d04a4d73c66c95b113737635`. Do not expose this configuration\non a shared network or treat its success as connector-fleet or production\nqualification.\n\n## What you will observe\n\nBy the end of the tutorial, you will have:\n\n- a ready local `getaip-server` process;\n- a manifest containing `cap:aip:server:health`;\n- an `aip.core.v1.action_result` with status `completed`;\n- a durable lifecycle view for action `act_quickstart_health_001`;\n- an AIP manifest projection produced through MCP.\n\nNo external product, connector host, PostgreSQL database, or NATS server is\nrequired for this path.\n\n## Prerequisites\n\nYou need:\n\n- Rust `1.88` or newer;\n- a clean checkout at the source revision above;\n- `curl`;\n- two terminal windows.\n\nRun every command from the repository root. Complete [Install AIP](installation.md)\nfirst if the pinned checkout or Rust toolchain is not ready.\n\n## 1. Start the daemon\n\nIn the first terminal, start `getaip-server` on loopback with an explicit development\nidentity and a dedicated state directory:\n\n```sh\ncargo run --locked -p getaip-server -- \\\n  --bind 127.0.0.1:18080 \\\n  --service-id agent:getaip:server:quickstart \\\n  --native-bearer-token local-development-token \\\n  --native-principal service:quickstart:client \\\n  --storage-dir .getaip-server-quickstart\n```\n\nLeave this process running. The bearer token authenticates native HTTP calls as\n`service:quickstart:client`. The storage directory selects the durable local\nruntime and preserves action, event, receipt, and replay state across process\nrestarts.\n\nExpected result: the command remains running and reports no startup error.\n\n## 2. Check daemon readiness\n\nIn the second terminal, request the unauthenticated readiness endpoint:\n\n```sh\ncurl --fail --silent --show-error http://127.0.0.1:18080/ready\n```\n\nExpected result: HTTP `200` with a JSON body whose `status` is `ready`. At this\nrevision, top-level readiness means the gateway is ready, the runtime worker is\nrunning, every required module is ready, and the NATS listener is running if\nNATS was configured as required. It does not prove that a connector replica or\nexternal product is reachable.\n\n## 3. Discover the manifest\n\nFetch the participant manifest with the same development credential:\n\n```sh\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token local-development-token \\\n  manifest fetch http://127.0.0.1:18080\n```\n\nExpected result: a JSON manifest for `agent:getaip:server:quickstart`. Its capabilities\ninclude `cap:aip:server:health`, and its profiles include the bindings enabled by this\ndaemon. Discover this contract instead of hard-coding assumptions about an\nunfamiliar deployment.\n\n## 4. Invoke the health capability\n\nSubmit a native action with a stable tutorial identifier:\n\n```sh\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token local-development-token \\\n  action call http://127.0.0.1:18080 \\\n  cap:aip:server:health \\\n  --action-id act_quickstart_health_001 \\\n  --input '{}'\n```\n\nExpected result: an AIP envelope with message type\n`aip.core.v1.action_result`. Its `body.action_result` contains\n`\"action_id\": \"act_quickstart_health_001\"`, `\"status\": \"completed\"`, and a\nhealth payload in `output`.\n\nThe explicit action ID makes the next query copyable and gives an interrupted\nclient a stable logical action to resume. For a replay-sensitive mutation, the\ncaller must also preserve its original idempotency and transaction identities;\nthe health capability is a low-risk read and requires no approval.\n\n## 5. Read the durable lifecycle view\n\nQuery the action independently of the original HTTP response:\n\n```sh\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token local-development-token \\\n  action status http://127.0.0.1:18080 \\\n  act_quickstart_health_001 \\\n  --include-result \\\n  --include-receipts\n```\n\nExpected result: the lifecycle view identifies the same action and capability,\nreports a terminal lifecycle state and `result_status` of `completed`, and\nincludes the final result. This read model remains available after the client\nthat submitted the action disconnects.\n\n## 6. Inspect the MCP projection\n\nThe same daemon exposes a Streamable HTTP MCP endpoint backed by the AIP\ngateway. Initialize an MCP client and print its AIP manifest projection:\n\n```sh\ncargo run --locked -p getaip-cli -- \\\n  mcp inspect --url http://127.0.0.1:18080/mcp\n```\n\nExpected result: JSON describing the MCP peer as an AIP manifest. This confirms\nthe MCP mapping implemented by the local daemon; it is not an MCP conformance\nor independent-client qualification result.\n\n## 7. Verify the complete path\n\nRepeat the two read-only checks that prove the daemon is still ready and the\naction remains queryable:\n\n```sh\ncurl --fail --silent --show-error http://127.0.0.1:18080/ready >/dev/null\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token local-development-token \\\n  action status http://127.0.0.1:18080 \\\n  act_quickstart_health_001 \\\n  --include-result >/dev/null\n```\n\nBoth commands must exit with status `0`. You have now completed discovery,\nauthenticated submission, execution, durable lookup, and compatibility-profile\ninspection for one native AIP action.\n\n## Stop and clean up\n\nReturn to the first terminal and stop `getaip-server` with `Control-C`. Keep\n`.getaip-server-quickstart` if you want to restart the daemon and inspect the same action.\nWhen that local history is no longer needed, inspect and remove only this\ntutorial directory:\n\n```sh\ndu -sh .getaip-server-quickstart\nrm -rf -- .getaip-server-quickstart\n```\n\nThis deletion removes the tutorial's local action and replay history. It does\nnot affect Cargo build artifacts or external services.\n\n## What happened internally\n\n`getaip` wrapped the typed health `Action` in an AIP `Envelope` and sent it to\n`/aip/v1/messages` with the bearer credential. The daemon bound the request to\nthe configured principal, validated and executed the built-in handler, stored\nthe lifecycle records, and returned an `ActionResult`. The later status query\nread the stored operational view rather than replaying the action.\n\nThe MCP step initialized a compatibility client and projected the daemon's AIP\nmanifest into MCP concepts. It did not create a second runtime or change the\nnative action semantics.\n\n## Next steps\n\n- [Run the connector fleet quickstart](connector-fleet-quickstart.md)\n- [Understand how AIP works](how-aip-works.md)\n- [Learn capabilities and contracts](../concepts/capabilities.md)\n- [Use native AIP](../guides/use-native-aip.md)\n- [Prepare a production deployment](../guides/production-deployment.md)\n",
    "text": "Run your first AIP action\n\nIn this tutorial, you will start one product-neutral AIP daemon on loopback,\ndiscover its manifest, invoke the built-in health capability, and inspect the\ndurable action state. You will also view the same capability surface through\nthe MCP compatibility profile.\n\nThis path is for developers learning the native request lifecycle. It uses a\nliteral development bearer token and local file-backed state at source revision\nd7cce13d1d555644d04a4d73c66c95b113737635. Do not expose this configuration\non a shared network or treat its success as connector-fleet or production\nqualification.\n\nWhat you will observe\n\nBy the end of the tutorial, you will have:\n• a ready local getaip-server process;\n• a manifest containing cap:aip:server:health;\n• an aip.core.v1.actionresult with status completed;\n• a durable lifecycle view for action actquickstarthealth001;\n• an AIP manifest projection produced through MCP.\n\nNo external product, connector host, PostgreSQL database, or NATS server is\nrequired for this path.\n\nPrerequisites\n\nYou need:\n• Rust 1.88 or newer;\n• a clean checkout at the source revision above;\n• curl;\n• two terminal windows.\n\nRun every command from the repository root. Complete Install AIP (installation.md)\nfirst if the pinned checkout or Rust toolchain is not ready.\n1. Start the daemon\n\nIn the first terminal, start getaip-server on loopback with an explicit development\nidentity and a dedicated state directory:\n\ncargo run --locked -p getaip-server -- \\\n  --bind 127.0.0.1:18080 \\\n  --service-id agent:getaip:server:quickstart \\\n  --native-bearer-token local-development-token \\\n  --native-principal service:quickstart:client \\\n  --storage-dir .getaip-server-quickstart\n\nLeave this process running. The bearer token authenticates native HTTP calls as\nservice:quickstart:client. The storage directory selects the durable local\nruntime and preserves action, event, receipt, and replay state across process\nrestarts.\n\nExpected result: the command remains running and reports no startup error.\n2. Check daemon readiness\n\nIn the second terminal, request the unauthenticated readiness endpoint:\n\ncurl --fail --silent --show-error http://127.0.0.1:18080/ready\n\nExpected result: HTTP 200 with a JSON body whose status is ready. At this\nrevision, top-level readiness means the gateway is ready, the runtime worker is\nrunning, every required module is ready, and the NATS listener is running if\nNATS was configured as required. It does not prove that a connector replica or\nexternal product is reachable.\n3. Discover the manifest\n\nFetch the participant manifest with the same development credential:\n\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token local-development-token \\\n  manifest fetch http://127.0.0.1:18080\n\nExpected result: a JSON manifest for agent:getaip:server:quickstart. Its capabilities\ninclude cap:aip:server:health, and its profiles include the bindings enabled by this\ndaemon. Discover this contract instead of hard-coding assumptions about an\nunfamiliar deployment.\n4. Invoke the health capability\n\nSubmit a native action with a stable tutorial identifier:\n\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token local-development-token \\\n  action call http://127.0.0.1:18080 \\\n  cap:aip:server:health \\\n  --action-id actquickstarthealth001 \\\n  --input '{}'\n\nExpected result: an AIP envelope with message type\naip.core.v1.actionresult. Its body.actionresult contains\n\"actionid\": \"actquickstarthealth001\", \"status\": \"completed\", and a\nhealth payload in output.\n\nThe explicit action ID makes the next query copyable and gives an interrupted\nclient a stable logical action to resume. For a replay-sensitive mutation, the\ncaller must also preserve its original idempotency and transaction identities;\nthe health capability is a low-risk read and requires no approval.\n5. Read the durable lifecycle view\n\nQuery the action independently of the original HTTP response:\n\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token local-development-token \\\n  action status http://127.0.0.1:18080 \\\n  actquickstarthealth001 \\\n  --include-result \\\n  --include-receipts\n\nExpected result: the lifecycle view identifies the same action and capability,\nreports a terminal lifecycle state and resultstatus of completed, and\nincludes the final result. This read model remains available after the client\nthat submitted the action disconnects.\n6. Inspect the MCP projection\n\nThe same daemon exposes a Streamable HTTP MCP endpoint backed by the AIP\ngateway. Initialize an MCP client and print its AIP manifest projection:\n\ncargo run --locked -p getaip-cli -- \\\n  mcp inspect --url http://127.0.0.1:18080/mcp\n\nExpected result: JSON describing the MCP peer as an AIP manifest. This confirms\nthe MCP mapping implemented by the local daemon; it is not an MCP conformance\nor independent-client qualification result.\n7. Verify the complete path\n\nRepeat the two read-only checks that prove the daemon is still ready and the\naction remains queryable:\n\ncurl --fail --silent --show-error http://127.0.0.1:18080/ready >/dev/null\ncargo run --locked -p getaip-cli -- \\\n  --native-bearer-token local-development-token \\\n  action status http://127.0.0.1:18080 \\\n  actquickstarthealth001 \\\n  --include-result >/dev/null\n\nBoth commands must exit with status 0. You have now completed discovery,\nauthenticated submission, execution, durable lookup, and compatibility-profile\ninspection for one native AIP action.\n\nStop and clean up\n\nReturn to the first terminal and stop getaip-server with Control-C. Keep\n.getaip-server-quickstart if you want to restart the daemon and inspect the same action.\nWhen that local history is no longer needed, inspect and remove only this\ntutorial directory:\n\ndu -sh .getaip-server-quickstart\nrm -rf -- .getaip-server-quickstart\n\nThis deletion removes the tutorial's local action and replay history. It does\nnot affect Cargo build artifacts or external services.\n\nWhat happened internally\n\ngetaip wrapped the typed health Action in an AIP Envelope and sent it to\n/aip/v1/messages with the bearer credential. The daemon bound the request to\nthe configured principal, validated and executed the built-in handler, stored\nthe lifecycle records, and returned an ActionResult. The later status query\nread the stored operational view rather than replaying the action.\n\nThe MCP step initialized a compatibility client and projected the daemon's AIP\nmanifest into MCP concepts. It did not create a second runtime or change the\nnative action semantics.\n\nNext steps\n• Run the connector fleet quickstart (connector-fleet-quickstart.md)\n• Understand how AIP works (how-aip-works.md)\n• Learn capabilities and contracts (../concepts/capabilities.md)\n• Use native AIP (../guides/use-native-aip.md)\n• Prepare a production deployment (../guides/production-deployment.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "f514a685d6b04d9c99eb8c91cf8c79376c3d4be92bcf701a788ce2f48c998eb1"
  }
}