{
  "schemaVersion": "1.0",
  "title": "Examples and reference deployments",
  "description": "Use this page to choose the smallest source artifact that matches your goal. The repository contains short Rust examples, local smoke topologies, scenario harnesses, and qualification environments. These artifact classes answer different qu",
  "canonical": "https://getaip.org/docs/guides/examples-and-reference-deployments",
  "route": "/docs/guides/examples-and-reference-deployments",
  "source": "docs/guides/examples-and-reference-deployments.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Build with AIP",
  "documentType": "Guide",
  "language": "en",
  "downloads": {
    "md": "/docs/download/guides/examples-and-reference-deployments.md",
    "txt": "/docs/download/guides/examples-and-reference-deployments.txt",
    "json": "/docs/download/guides/examples-and-reference-deployments.json",
    "pdf": "/docs/download/guides/examples-and-reference-deployments.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Examples and reference deployments\ndescription: Choose a source example or reference topology and understand the exact evidence boundary of each artifact\nkind: index\naudience: developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"97be86e9efedf07ecf1783b03800f683f107fb04\"\n---\n\n# Examples and reference deployments\n\nUse this page to choose the smallest source artifact that matches your goal.\nThe repository contains short Rust examples, local smoke topologies, scenario\nharnesses, and qualification environments. These artifact classes answer\ndifferent questions and provide different levels of evidence.\n\nStart with a task guide when you want a supported end-to-end learning path.\nUse an example when you need one focused code pattern. Use a reference topology\nwhen you need to inspect component boundaries before designing a deployment.\n\nThe inventory targets source revision\n`97be86e9efedf07ecf1783b03800f683f107fb04`. This authoring pass inspected the\nsource without building an example, starting Docker, contacting a product, or\nasserting that a retained evidence run exists.\n\n## Choose the smallest useful artifact\n\n| Goal | Start here | Evidence provided by the artifact itself |\n|---|---|---|\n| Learn one complete local AIP request | Getting-started quickstart | A documented, source-backed procedure |\n| Understand one Rust mapping or framing type | Registered Rust example | Executable source for one bounded concept |\n| Connect an MCP or A2A client | Compatibility-profile guide | A source-backed client procedure and verification boundary |\n| Learn connector-fleet routing | Connector-fleet quickstart | A bounded tutorial using the deterministic fleet topology |\n| Inspect multi-service composition | Reference topology below | Deployment structure, not production qualification |\n| Evaluate a connector artifact | Its qualification harness and retained evidence | Evidence only after the exact harness and artifacts complete successfully |\n\nDo not begin with the largest Compose file merely because it contains more\ncomponents. Larger fixtures introduce credentials, external checkouts, images,\nstate, cleanup, and evidence assumptions that a focused example avoids.\n\n## Run a registered Rust example\n\nThe `aip` facade crate registers ten examples. Every registered example\ncurrently declares the legacy `full` feature aggregate as a Cargo requirement.\nRun one from the repository root with this pattern:\n\n```sh\ncargo run --locked -p aip --example minimal-agent --features full\n```\n\nReplace `minimal-agent` with another registered name from the table. The\n`full` aggregate enables more optional code than most examples use. Treat it as\na repository compatibility boundary, not as dependency guidance for a new\napplication.\n\n| Example | What the source demonstrates | What it does not do |\n|---|---|---|\n| `minimal-agent` | In-process gateway, test manifest, local handler, and one action result | Start `aipd`, authenticate a transport, or persist state |\n| `sse-streaming` | Encode one in-memory transport event as SSE | Open an HTTP listener or test reconnect behavior |\n| `nats-native` | Build a native NATS subject and envelope headers | Connect to a NATS server or send a request |\n| `mcp-bridge` | Map a local manifest to MCP tools and a tool call back to an action | Start an MCP server or invoke a provider |\n| `mcp-client-bridge` | Discover an MCP peer through an in-memory client transport | Contact a network peer or prove client interoperability |\n| `mcp-server-aipd` | Print canonical endpoint names and an MCP initialize request | Start `aipd` or establish an authenticated session |\n| `mcp-stdio-server` | Encode one newline-delimited MCP request frame | Spawn a child server or manage a session |\n| `mcp-streamable-http` | Encode and decode one MCP SSE event | Perform Streamable HTTP initialization or replay |\n| `mcp-sampling-elicitation` | Construct sampling, elicitation, and response DTOs | Install model, human-input, or completion providers |\n| `chatwoot-dify-crewai` | Compose local mapping types for Chatwoot, Dify, and CrewAI | Call any of the three products or establish a durable workflow |\n\nThe output of `mcp-server-aipd` includes an illustrative daemon command from\nthe example source. It is not the current deployment recipe. Use the MCP guide\nfor a runnable loopback endpoint and for the separate production\nintrospection controls.\n\nMost examples print JSON or framing text to standard output. Validate the\nspecific field that matters to your adaptation rather than treating process\nexit alone as behavioral evidence.\n\n## Choose a source topology\n\nThe multi-service directories have narrower purposes than their names may\nsuggest:\n\n| Source path | Intended question | Important boundary |\n|---|---|---|\n| `examples/hermes-agent-aip` | Can the Hermes Agent connector discover and smoke-check two local Hermes gateways? | Builds an adjacent external checkout, uses a hard-coded smoke credential, and is not a production topology |\n| `examples/cal-diy-qualification` | Can one pinned Cal.diy artifact satisfy the isolated qualification procedure? | Requires the exact upstream checkout, local images, Docker, generated secrets, retained run evidence, and the legacy bundled daemon |\n| `examples/restaurant-booking` | How do Cal.diy, Hermes Agent, a coordinator, MCP, approval, and durable state compose in one scenario? | Uses the legacy bundled daemon and local identity fixtures despite the deployment-oriented Compose name |\n| `deploy/connector-fleet` | How do admission, registry, control plane, edge, product-neutral daemons, remote hosts, mTLS, and qualification fit together? | It is a deterministic qualification topology with fixture-specific trust, endpoints, images, and evidence paths |\n| `examples/aipd-docker` | How does the older bundled local E2E assemble its dependencies? | Contains non-public qualification fixtures and is excluded from the public adoption path |\n\nNone of these directories is a drop-in production deployment. A source path\ncan be useful as architecture evidence while remaining unsuitable as an\noperational template.\n\n## Compare public connector example coverage\n\nThe six maintained connectors do not have symmetric example coverage at the\nreviewed revision:\n\n| Connector | Focused or scenario example | Deterministic fleet product profile | Current interpretation |\n|---|---|:---:|---|\n| Cal.diy | Isolated qualification and restaurant-booking scenario | Yes | Strongest dedicated local harness coverage; evidence still belongs to an exact completed run |\n| Hermes Agent | Two-node smoke topology and restaurant-booking scenario | Yes | Covers smoke and scenario composition; neither proves a general production deployment |\n| Chatwoot | Local three-product mapping example | Yes | Mapping plus fixture-backed fleet execution, not a live external-product claim |\n| Dify | Local three-product mapping example | Yes | Mapping plus fixture-backed fleet execution, not a live external-product claim |\n| CrewAI | Local three-product mapping example and fleet sidecar | Yes | Mapping and durable fixture-sidecar behavior, not an arbitrary crew qualification |\n| Twenty | No example directory at this revision | No | Connector and host source exist, but this inventory provides no runnable-example or fleet-profile evidence |\n\nThe product profile under `deploy/connector-fleet` covers five product hosts.\nIt uses controlled upstream fixtures to test connector and fleet mechanics. It\ndoes not contact the five public products, and it must not be reported as live\nproduct verification.\n\n## Interpret the evidence correctly\n\nAn artifact becomes stronger evidence only when the corresponding step is\nactually completed and recorded:\n\n| Observed state | Claim it can support | Claim it cannot support |\n|---|---|---|\n| Source file exists | The repository contains the described implementation | The example compiles or runs |\n| Exact example compiles | The selected revision type-checks for that build | Runtime behavior or interoperability |\n| Example exits with checked output | The bounded local behavior occurred once | Conformance, qualification, or production readiness |\n| Scenario harness completes | The recorded scenario passed for exact inputs and artifacts | General connector coverage or external-product compatibility |\n| Qualification harness and evidence pass | The identified artifact passed the documented matrix | Other revisions, topologies, tenants, or products |\n| Live external-product run passes | The exact observed upstream behavior succeeded | Future behavior or production SLOs |\n| Production observation meets a defined window | The named deployment met that bounded operational claim | Universal protocol or connector guarantees |\n\nDirectory names, comments, fixture labels, and intended commands are not run\nresults. Keep source truth, current checkout truth, retained evidence, and live\ndeployment truth separate.\n\n## Adapt an example without importing its assumptions\n\nBefore copying code or configuration, record:\n\n1. the exact source revision and example path;\n2. whether the example uses `aip-testkit`, an in-memory transport, a local\n   fixture, or a real external process;\n3. which identities, scopes, tenants, credentials, and signing keys are\n   represented or omitted;\n4. whether state is memory-backed, file-backed, PostgreSQL-backed, or owned by\n   an external product;\n5. which side effects occur and how idempotency, approval, retries, and unknown\n   outcomes are handled;\n6. the exact expected output and the evidence artifact that records it;\n7. every directory, container, network, volume, and secret created by the run.\n\nReplace test manifests and hard-coded credentials before adapting a sample to\nan application. Preserve stable capability IDs and source-owned schemas. Do\nnot copy a product-specific connector into the product-neutral daemon process\nwhen the intended architecture is a standalone connector host.\n\n## Verify a selected artifact\n\nFor a Rust example, verify the command exit status and parse its documented\noutput. Then inspect the source again to confirm whether the result came from a\nreal boundary or an in-memory substitute.\n\nFor a multi-service topology, verify all of these before making a claim:\n\n- exact source, external checkout, image, and configuration identities;\n- readiness of every required component, not only process liveness;\n- expected positive behavior and relevant negative controls;\n- durable state and restart behavior when the claim depends on recovery;\n- an evidence file that records timestamps, inputs, results, and artifact\n  identities;\n- cleanup scoped to the exact Compose project and its generated runtime path.\n\nDo not convert a saved historical result into a current-live claim. Re-run the\ndocumented procedure against the intended artifacts when current evidence is\nrequired.\n\n## Clean up within the artifact boundary\n\nThe registered in-memory examples create no deployment state, although Cargo\nmay update its normal build cache. Multi-service harnesses can create untracked\nsecret directories, evidence directories, images, containers, networks, and\nvolumes.\n\nUse the cleanup procedure owned by the selected harness. Inspect its Compose\nproject name and generated paths first. Do not use a global Docker prune or\nremove unrelated volumes to clean up one example.\n\n## Related documentation\n\n- [Quickstart](../getting-started/quickstart.md)\n- [Connector-fleet quickstart](../getting-started/connector-fleet-quickstart.md)\n- [Use native AIP](use-native-aip.md)\n- [Use AIP through MCP](use-aip-through-mcp.md)\n- [Use AIP through A2A](use-aip-through-a2a.md)\n",
    "text": "Examples and reference deployments\n\nUse this page to choose the smallest source artifact that matches your goal.\nThe repository contains short Rust examples, local smoke topologies, scenario\nharnesses, and qualification environments. These artifact classes answer\ndifferent questions and provide different levels of evidence.\n\nStart with a task guide when you want a supported end-to-end learning path.\nUse an example when you need one focused code pattern. Use a reference topology\nwhen you need to inspect component boundaries before designing a deployment.\n\nThe inventory targets source revision\n97be86e9efedf07ecf1783b03800f683f107fb04. This authoring pass inspected the\nsource without building an example, starting Docker, contacting a product, or\nasserting that a retained evidence run exists.\n\nChoose the smallest useful artifact\n\n| Goal | Start here | Evidence provided by the artifact itself |\n\n| Learn one complete local AIP request | Getting-started quickstart | A documented, source-backed procedure |\n| Understand one Rust mapping or framing type | Registered Rust example | Executable source for one bounded concept |\n| Connect an MCP or A2A client | Compatibility-profile guide | A source-backed client procedure and verification boundary |\n| Learn connector-fleet routing | Connector-fleet quickstart | A bounded tutorial using the deterministic fleet topology |\n| Inspect multi-service composition | Reference topology below | Deployment structure, not production qualification |\n| Evaluate a connector artifact | Its qualification harness and retained evidence | Evidence only after the exact harness and artifacts complete successfully |\n\nDo not begin with the largest Compose file merely because it contains more\ncomponents. Larger fixtures introduce credentials, external checkouts, images,\nstate, cleanup, and evidence assumptions that a focused example avoids.\n\nRun a registered Rust example\n\nThe aip facade crate registers ten examples. Every registered example\ncurrently declares the legacy full feature aggregate as a Cargo requirement.\nRun one from the repository root with this pattern:\n\ncargo run --locked -p aip --example minimal-agent --features full\n\nReplace minimal-agent with another registered name from the table. The\nfull aggregate enables more optional code than most examples use. Treat it as\na repository compatibility boundary, not as dependency guidance for a new\napplication.\n\n| Example | What the source demonstrates | What it does not do |\n\n| minimal-agent | In-process gateway, test manifest, local handler, and one action result | Start aipd, authenticate a transport, or persist state |\n| sse-streaming | Encode one in-memory transport event as SSE | Open an HTTP listener or test reconnect behavior |\n| nats-native | Build a native NATS subject and envelope headers | Connect to a NATS server or send a request |\n| mcp-bridge | Map a local manifest to MCP tools and a tool call back to an action | Start an MCP server or invoke a provider |\n| mcp-client-bridge | Discover an MCP peer through an in-memory client transport | Contact a network peer or prove client interoperability |\n| mcp-server-aipd | Print canonical endpoint names and an MCP initialize request | Start aipd or establish an authenticated session |\n| mcp-stdio-server | Encode one newline-delimited MCP request frame | Spawn a child server or manage a session |\n| mcp-streamable-http | Encode and decode one MCP SSE event | Perform Streamable HTTP initialization or replay |\n| mcp-sampling-elicitation | Construct sampling, elicitation, and response DTOs | Install model, human-input, or completion providers |\n| chatwoot-dify-crewai | Compose local mapping types for Chatwoot, Dify, and CrewAI | Call any of the three products or establish a durable workflow |\n\nThe output of mcp-server-aipd includes an illustrative daemon command from\nthe example source. It is not the current deployment recipe. Use the MCP guide\nfor a runnable loopback endpoint and for the separate production\nintrospection controls.\n\nMost examples print JSON or framing text to standard output. Validate the\nspecific field that matters to your adaptation rather than treating process\nexit alone as behavioral evidence.\n\nChoose a source topology\n\nThe multi-service directories have narrower purposes than their names may\nsuggest:\n\n| Source path | Intended question | Important boundary |\n\n| examples/hermes-agent-aip | Can the Hermes Agent connector discover and smoke-check two local Hermes gateways? | Builds an adjacent external checkout, uses a hard-coded smoke credential, and is not a production topology |\n| examples/cal-diy-qualification | Can one pinned Cal.diy artifact satisfy the isolated qualification procedure? | Requires the exact upstream checkout, local images, Docker, generated secrets, retained run evidence, and the legacy bundled daemon |\n| examples/restaurant-booking | How do Cal.diy, Hermes Agent, a coordinator, MCP, approval, and durable state compose in one scenario? | Uses the legacy bundled daemon and local identity fixtures despite the deployment-oriented Compose name |\n| deploy/connector-fleet | How do admission, registry, control plane, edge, product-neutral daemons, remote hosts, mTLS, and qualification fit together? | It is a deterministic qualification topology with fixture-specific trust, endpoints, images, and evidence paths |\n| examples/aipd-docker | How does the older bundled local E2E assemble its dependencies? | Contains non-public qualification fixtures and is excluded from the public adoption path |\n\nNone of these directories is a drop-in production deployment. A source path\ncan be useful as architecture evidence while remaining unsuitable as an\noperational template.\n\nCompare public connector example coverage\n\nThe six maintained connectors do not have symmetric example coverage at the\nreviewed revision:\n\n| Connector | Focused or scenario example | Deterministic fleet product profile | Current interpretation |\n\n| Cal.diy | Isolated qualification and restaurant-booking scenario | Yes | Strongest dedicated local harness coverage; evidence still belongs to an exact completed run |\n| Hermes Agent | Two-node smoke topology and restaurant-booking scenario | Yes | Covers smoke and scenario composition; neither proves a general production deployment |\n| Chatwoot | Local three-product mapping example | Yes | Mapping plus fixture-backed fleet execution, not a live external-product claim |\n| Dify | Local three-product mapping example | Yes | Mapping plus fixture-backed fleet execution, not a live external-product claim |\n| CrewAI | Local three-product mapping example and fleet sidecar | Yes | Mapping and durable fixture-sidecar behavior, not an arbitrary crew qualification |\n| Twenty | No example directory at this revision | No | Connector and host source exist, but this inventory provides no runnable-example or fleet-profile evidence |\n\nThe product profile under deploy/connector-fleet covers five product hosts.\nIt uses controlled upstream fixtures to test connector and fleet mechanics. It\ndoes not contact the five public products, and it must not be reported as live\nproduct verification.\n\nInterpret the evidence correctly\n\nAn artifact becomes stronger evidence only when the corresponding step is\nactually completed and recorded:\n\n| Observed state | Claim it can support | Claim it cannot support |\n\n| Source file exists | The repository contains the described implementation | The example compiles or runs |\n| Exact example compiles | The selected revision type-checks for that build | Runtime behavior or interoperability |\n| Example exits with checked output | The bounded local behavior occurred once | Conformance, qualification, or production readiness |\n| Scenario harness completes | The recorded scenario passed for exact inputs and artifacts | General connector coverage or external-product compatibility |\n| Qualification harness and evidence pass | The identified artifact passed the documented matrix | Other revisions, topologies, tenants, or products |\n| Live external-product run passes | The exact observed upstream behavior succeeded | Future behavior or production SLOs |\n| Production observation meets a defined window | The named deployment met that bounded operational claim | Universal protocol or connector guarantees |\n\nDirectory names, comments, fixture labels, and intended commands are not run\nresults. Keep source truth, current checkout truth, retained evidence, and live\ndeployment truth separate.\n\nAdapt an example without importing its assumptions\n\nBefore copying code or configuration, record:\n1. the exact source revision and example path;\n2. whether the example uses aip-testkit, an in-memory transport, a local\n   fixture, or a real external process;\n3. which identities, scopes, tenants, credentials, and signing keys are\n   represented or omitted;\n4. whether state is memory-backed, file-backed, PostgreSQL-backed, or owned by\n   an external product;\n5. which side effects occur and how idempotency, approval, retries, and unknown\n   outcomes are handled;\n6. the exact expected output and the evidence artifact that records it;\n7. every directory, container, network, volume, and secret created by the run.\n\nReplace test manifests and hard-coded credentials before adapting a sample to\nan application. Preserve stable capability IDs and source-owned schemas. Do\nnot copy a product-specific connector into the product-neutral daemon process\nwhen the intended architecture is a standalone connector host.\n\nVerify a selected artifact\n\nFor a Rust example, verify the command exit status and parse its documented\noutput. Then inspect the source again to confirm whether the result came from a\nreal boundary or an in-memory substitute.\n\nFor a multi-service topology, verify all of these before making a claim:\n• exact source, external checkout, image, and configuration identities;\n• readiness of every required component, not only process liveness;\n• expected positive behavior and relevant negative controls;\n• durable state and restart behavior when the claim depends on recovery;\n• an evidence file that records timestamps, inputs, results, and artifact\n  identities;\n• cleanup scoped to the exact Compose project and its generated runtime path.\n\nDo not convert a saved historical result into a current-live claim. Re-run the\ndocumented procedure against the intended artifacts when current evidence is\nrequired.\n\nClean up within the artifact boundary\n\nThe registered in-memory examples create no deployment state, although Cargo\nmay update its normal build cache. Multi-service harnesses can create untracked\nsecret directories, evidence directories, images, containers, networks, and\nvolumes.\n\nUse the cleanup procedure owned by the selected harness. Inspect its Compose\nproject name and generated paths first. Do not use a global Docker prune or\nremove unrelated volumes to clean up one example.\n\nRelated documentation\n• Quickstart (../getting-started/quickstart.md)\n• Connector-fleet quickstart (../getting-started/connector-fleet-quickstart.md)\n• Use native AIP (use-native-aip.md)\n• Use AIP through MCP (use-aip-through-mcp.md)\n• Use AIP through A2A (use-aip-through-a2a.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "0e44a0625501cd345f39bc25028c9b9f86ed5cbf1df843021fae829e737863e0"
  }
}