Ag2 integration

[vvlrff]

Description

Adds an integration guide for AG2 (AutoGen): how to give AG2 agents live web access
through Perplexity's first-party PerplexitySearchToolkit — raw ranked sources via the
Search API, and grounded answers with citations via Sonar. Includes a runnable example
script and per-tool filtering (domains, recency, date ranges, search mode).

AG2 >= 1.0.0 ships Perplexity support in-tree, so there is no adapter package to write
or maintain. The tools run as local function tools, so they work with every model
provider AG2 supports, not just OpenAI-compatible ones.

Type of Contribution

• Article/Integration Guide

Checklist

• My code follows the cookbook's style guidelines
• I have included comprehensive documentation
• I have tested my code and it works as expected
• I have included all necessary dependencies and setup instructions
• My MDX file includes proper frontmatter (title, description, keywords)
• I have linked to any external repositories or live demos

Project Details

What problem does this solve?
AG2 agents have no built-in web access — they answer from model weights alone and go
stale. The cookbook has integration guides for OpenAI Agents and memory management, but
nothing for AG2, which is one of the more widely used multi-agent frameworks. This guide
closes that gap and shows both Perplexity endpoints side by side, so readers can pick
the cheap path (Search API, no LLM hop, no extra token cost) or the grounded path
(Sonar with citations) per tool rather than per agent.

What makes this contribution valuable to other developers?

• Covers first-party support, so there's no third-party adapter to trust or maintain.
• Shows the Search API vs Sonar tradeoff explicitly, which is the decision most people
  get wrong on first integration.
• Provider-agnostic: the tools are local function tools, so the pattern works regardless
  of which model powers the agent.
• Ships a runnable script, not just snippets.

External Links (if applicable):

• GitHub Repository: https://github.com/ag2ai/ag2
• Live Demo: n/a
• Blog Post/Article: https://docs.ag2.ai/docs/user-guide/tools/common_toolkits/#perplexitysearchtoolkit

Testing

• node scripts/validate-mdx.js passes — 42/42 MDX files valid, including
  docs/articles/ag2-integration/README.mdx.
• Frontmatter present and matching the format used by the existing
  openai-agents-integration article.
• ag2_perplexity.py syntax-checked via ast.parse.
• Not executed end-to-end — see Additional Notes.

Additional Notes

Files added:

• docs/articles/ag2-integration/README.mdx — docs-site page
• docs/articles/ag2-integration/README.md — GitHub-facing version
• docs/articles/ag2-integration/ag2_perplexity.py — runnable example

Files changed:

• README.md — AG2 added to the Integration Guides list
• docs/index.mdx — direct links to the AG2 and OpenAI Agents guides

Open questions for reviewers:

1. Sonar vs Agent API. The guide teaches Sonar (/chat/completions), which docs(README): mark Agent API as primary, mark Sonar deprecated #78
   marked deprecated in favour of the Agent API. AG2's toolkit targets Sonar today, so
   the guide reflects what actually ships — but if the cookbook should no longer document
   Sonar at all, say so and I'll restructure around the Agent API.
2. Example not run end-to-end. I don't have an environment with ag2 installed plus
   both a Perplexity key and a model-provider key, so the script is syntax-checked but
   not executed. Would appreciate someone running it once before merge.