[AS-320] Tech note: Graph for agentic AI workflows (MCP)

[ilan-bel]

Summary

Adds docs/graph-for-agentic-workflows.md. Frames the architecture (Router + MCP server + agent) and then surfaces what changes about graph design when LLMs are the consumer:

• Operation/field naming matters more (read fresh each inference).
• Tool surface should be curated; contract variants are the natural mechanism.
• GraphQL operation descriptions are the model-facing tool descriptions — write them for LLMs.
• Error messages should instruct on the fix because LLMs treat them as the retry signal.
• Caching pays off more because agents repeat themselves.
• Authorization: prefer service accounts or OBO over privileged tokens.
• Wire apollographql-client-name from the MCP server so agent traffic is separable in telemetry.

Cross-links the working examples in apollosolutions/apollo-mcp-server, agui-solutions-demo, lending-graph-ai-demo, example-router-obo-flow.

Tracks AS-320.

Test plan

• Renders cleanly
• Apollo docs and apollosolutions repo links resolve

🤖 Generated with Claude Code

[apollo-solutions-reviewer]

The technical content is accurate and maps well to AS-320. The MCP framing (operation name to tool name, operation description to tool description, operation variables to input schema), the contract-variants approach for curating the tool surface, the OBO coprocessor pattern, and the apollographql-client-name telemetry guidance are all correct. The architecture diagram and cross-links to apollo-mcp-server, agui-solutions-demo, lending-graph-ai-demo, and example-router-obo-flow are appropriate.

One blocking-level issue before merge: the doc links to ./entity-caching-best-practices.md in two places, but that file does not exist in docs/. The repo's caching doc is response-caching-guide.md. Both links 404; this also fails the PR's own "apollosolutions repo links resolve" test-plan item. Point them at ./response-caching-guide.md (or whichever caching doc is intended).

Minor: the doc describes the tool source exclusively as the "persisted operations manifest." The Apollo MCP server can also source tools from GraphOS operation collections and local operation files; consider noting collections as the recommended Studio-managed path. Not blocking.

[apollo-solutions-reviewer]

Broken relative link: ./entity-caching-best-practices.md does not exist in docs/. The repo's caching doc is response-caching-guide.md. Update to ./response-caching-guide.md.

[apollo-solutions-reviewer]

Verified at 88d89b2: the link in the Cache aggressively section now points to ./response-caching-guide.md, which exists in docs/. This thread can be resolved.

[apollo-solutions-reviewer]

Same broken link as line 73; the See also entry points to ./entity-caching-best-practices.md, which does not exist. Repoint to ./response-caching-guide.md.

[apollo-solutions-reviewer]

Verified at 88d89b2: the See also entry now points to ./response-caching-guide.md, which exists in docs/. This thread can be resolved.

[apollo-solutions-reviewer]

Re-reviewed at 88d89b2. The previously flagged broken links to ./entity-caching-best-practices.md are fixed; both the Cache aggressively reference and the See also entry now point to ./response-caching-guide.md, which exists in docs/. That was the only blocking issue. Technical content remains accurate: the MCP framing (operation name to tool name, operation description to tool description, variables to input schema), contract-variants for curating the tool surface, the OBO coprocessor pattern, and the apollographql-client-name telemetry guidance are all correct. Approving.