_{Setup console · Report illustration with example figures. Presentation varies by runtime.}

Paid Media Agent helps you understand what changed across your ad accounts and decide what to do
next. Ask questions in Slack or the terminal, generate performance reports, and prepare campaign
changes for review.

It comes with ad platform integrations, analysis and reporting skills, and a paid-media wiki.
Connect your accounts, add your company context, and deploy with
Managed Deep Agents
or on your own infrastructure. You choose the model.

What it does

• Compare campaign performance. Track spend, conversions, cost per lead, and budget pacing
  across connected accounts.
• Investigate changes. Find the campaigns behind a shift, check the supporting data, and flag
  gaps that could change the conclusion.
• Produce reports. Generate weekly or monthly summaries with charts, campaign tables, and
  recommendations. Download HTML, or PDF when the host has the rendering libraries installed.
• Prepare changes for review. Propose campaign updates with a reason and a plan for checking
  the result.

The model decides what to investigate. Code calculates the metrics and checks report figures
against the source data. Large responses stay in files; the model receives summaries with the
source, date window, and data-quality flags.

Live ad account changes are off by default. Enabling them requires a configured write policy,
release checks, and approval from an authorized reviewer.
Approval applies to the exact proposal reviewed; editing it requires a new approval.

Quick start

Requires Python 3.11+ and uv.

git clone https://github.com/langchain-ai/paid-media-agent.git
cd paid-media-agent
uv sync
uv run paid-media-agent setup

The setup command opens a local console for choosing a model, connecting ad accounts, and
deploying. No frontend build is needed. The CLI exposes the same connection actions with JSON
output if you prefer the terminal.

You can also ask your coding agent to guide setup:

Read AGENTS.md and .agents/skills/paid-media-onboarding/SKILL.md. Help me connect a model,
connect my ad accounts, add my business context, and choose a deployment path.

Try it without model keys or ad accounts:

uv run paid-media-agent demo --with-proposal

The offline demo runs a scripted analysis and a simulated budget change against synthetic
accounts. It doesn't call a model or touch live campaigns.

Once configured, ask a question or generate a report:

uv run paid-media-agent ask "Which campaigns had the largest increase in cost per lead last week?"
uv run paid-media-agent report --cadence weekly

Questions use your configured model. The report command runs without one, using supported
campaign-performance adapters.

Accounts and business context

Connect the platforms you use:

Connect any subset. Available tools and metrics depend on platform permissions and API access.
Direct adapters are read-only. Provider data without a supported report mapping can still be
explored through ask.

The included paid-media wiki covers attribution, platform
differences, and budget decisions. Your company context gives the agent the goals, conversion
definitions, and campaign briefs it needs to interpret your performance.

Ask your coding agent to follow the
business-context skill, or create
workspace/skills/company-context/ yourself using the
template. Add this context before the first real analysis.

Settings live in .env, account mappings in config/accounts.toml, and company context in
workspace/skills/company-context/. All three are Git-ignored.

Deployment

Choose who operates the infrastructure:

For Managed Deep Agents, choose Deploy agent in setup, or validate and deploy from the terminal:

uv run paid-media-agent mda check
uv run mda deploy .

You'll need a LangSmith organization with MDA access, an API key with deployment permissions,
and a model key. Deployment syncs the instructions and skills, provisions the sandbox, and
configures Slack. Authorize your workspace when prompted. The sandbox snapshot is reused until
its recipe changes. After deployment, open the printed LangSmith URL to inspect your agent.

To self-host, install Docker, configure your model and accounts, then generate API credentials
and start the services:

uv run paid-media-agent config generate PAID_MEDIA_API_TOKENS PAID_MEDIA_APPROVAL_SIGNING_KEY
docker compose up -d --build

Compose starts the API and Postgres. Follow the self-hosting guide
to connect Slack through Socket Mode or signed HTTP. The Docker image includes PDF libraries.

Managed schedules can post text to Slack once you configure a delivery channel. Report files are
available locally and through the self-hosted API. Automatic PDF attachments to Slack are not included.

Managed hosting is paid; model and connector charges depend
on your providers. For local development, uv run mda dev . opens the managed runtime in LangSmith
Studio so you can inspect model calls, tool results, and approval requests.

Build on it

Both deployment paths use the same agent assembly, built on
Deep Agents. It defines the model, tools, middleware,
and approval policy. Extend it without maintaining a separate agent for each interface.

Tools are selected from the connected catalog as needed, limiting how many tool definitions the
model reads on each call. Skills guide the investigation and reporting process; edit them as
Markdown in workspace/skills/.

To apply your company's report style, ask your coding agent to update
DESIGN.md and the renderer tokens together. The
report-design workflow keeps colors, fonts, and
components aligned across HTML, charts, and PDFs.

Warehouse connections are optional extensions. To bring in pipeline or revenue data, add a
connector and metric mappings to the shared tools. The project doesn't assume a BigQuery, dbt,
or CRM schema. See optional data sources.

Use synthetic data for development. Run make check before submitting a change; see
Contributing for the development dependencies and checks.

Apache 2.0 · Changelog · Security · Code of conduct