Build Social Spark

An ADK agent that turns an idea into a researched, on-brand, illustrated social post, approved by you, then published for real, all wrapped in a web app you didn't have to build.

Today you write a real ADK backend: an orchestrating agent with a hand-written tool, four Agent Skills (you author one yourself), an isolated research sub-agent, and a live MCP connection to Buffer that actually publishes what you approve. Then you wire up a CopilotKit frontend that's given to you, but you'll open the two files that make it talk to ADK, because that connection is the whole point of Step 8.

What's given vs. what you build

Before you start

• Completed the pre-camp setup guide: Python 3.14+, uv, Node 20+, the Google Cloud SDK authenticated against your DevCamp project, and google-adk installed.
• A terminal, an editor, and roughly two hours. Every step has a time estimate in the sidebar; total for the core path (Steps 1–6, 8–9) is about 1h45; Step 7 (LinkedIn) adds another 15 min and is entirely optional.
• A free Buffer account for Step 6 (takes two minutes, no card needed for the free tier).

Set up your workspace

Clone the starter repo, which holds the plumbing that isn't the point of today, and get your environment talking to Agent Platform.

git clone https://github.com/sonikajanagill/ai-devcamp-labs.git
cd ai-devcamp-labs
cp .env.example backend/social_poster/.env
uv sync

Edit backend/social_poster/.env: set GOOGLE_CLOUD_PROJECT to your DevCamp project id (no service-account key file needed anywhere — gcloud auth application-default login from Step 2 of the setup guide is enough). Leave everything else; you'll fill in BUFFER_API_KEY in Step 6.

You should now have

The smallest possible agent

Everything in ADK starts with one object: an Agent, a model, an instruction, and optionally tools.

from google.adk.agents import Agent

root_agent = Agent(
    name="social_poster",
    model="gemini-2.5-flash",
    description="Helps the user turn an idea into a polished social media post.",
    instruction="You help the user turn an idea into a social media post.",
)

uv run adk web backend

Open http://localhost:8000, select social_poster, say hi. That's a complete, working ADK agent: no tools yet, just a model and an instruction.

Give it a tool

The easiest way to hand ADK a tool: write a plain Python function. ADK inspects its signature and docstring and wraps it automatically: no decorators, no schema to write by hand.

tools.py (already copied in) has generate_image(prompt: str) -> dict, which calls Gemini's image model and writes the result to gallery/. Wire it in:

from google.adk.agents import Agent
from .tools import generate_image

root_agent = Agent(
    name="social_poster",
    model="gemini-2.5-flash",
    description="Helps the user turn an idea into a polished social media post.",
    instruction="""You help the user turn an idea into a social media post.
If the user asks for an image, call generate_image with a detailed visual
description and tell them where the file was saved.""",
    tools=[generate_image],
)

Restart adk web and try: Draft something about remote work, and add an image. Watch the Trace tab: generate_image fires as a real tool call, and a PNG lands in gallery/.

Teach it Agent Skills

A Skill is a folder with a SKILL.md file: YAML frontmatter (name, description) plus markdown instructions. The agent decides when to load one via a tool call; the content isn't in the system prompt until it's actually needed. That's progressive disclosure: keep the default context small, pull in detail only when relevant.

Open the three skills you copied in and read them; that's the whole format:

• skills/post-formatter/SKILL.md — structural rules (hook line, paragraph limits, hashtags)
• skills/platform-style/SKILL.md — points at a second-level reference file per platform (references/linkedin.md, references/x.md)
• skills/poster-style/SKILL.md — visual style rules for generate_image prompts (you'll wire this in properly once images route through the skill)

Now write one yourself: brand-voice

Create skills/brand-voice/SKILL.md:

---
name: brand-voice
description: Tone-of-voice and language rules for all written content. Load whenever drafting or revising a post.
---

# Brand Voice

## Tone
- Casual and warm, like explaining something interesting to a colleague.
- British English throughout: organise, colour, whilst, learnt.
- Short sentences. Active voice.

## Banned clichés
Never use: "game-changer", "unlock the power of", "seamless", "leverage"
(as a verb), "I'm thrilled to announce".

Wire all four skills in

import pathlib
from google.adk.agents import Agent
from google.adk.skills import load_skill_from_dir
from google.adk.tools.skill_toolset import SkillToolset
from .tools import generate_image

SKILLS_DIR = pathlib.Path(__file__).resolve().parents[2] / "skills"

skill_toolset = SkillToolset(
    skills=[
        load_skill_from_dir(SKILLS_DIR / "post-formatter"),
        load_skill_from_dir(SKILLS_DIR / "platform-style"),
        load_skill_from_dir(SKILLS_DIR / "brand-voice"),
        load_skill_from_dir(SKILLS_DIR / "poster-style"),
    ],
)

root_agent = Agent(
    name="social_poster",
    model="gemini-2.5-flash",
    description="Helps the user turn an idea into a polished social media post.",
    instruction="""You help the user turn an idea into a social media post.

Workflow:
1. When drafting, load and follow the relevant skills: post-formatter
   (structure), platform-style (rules for the target platform), and
   brand-voice (tone).
2. If the user asks for an image, load and follow the poster-style skill,
   then call generate_image with a detailed visual description and tell
   them where the file was saved.""",
    tools=[generate_image, skill_toolset],
)

Restart and try: I want a LinkedIn post about why agent evals matter more than demos. Watch the Trace tab for load_skill calls: notice platform-style triggers a second-level read of references/linkedin.md, only because the draft is for LinkedIn. Ask for an X post instead and it reads references/x.md.

Add web research (and a real ADK constraint)

Add google_search, a built-in tool, so the agent can ground drafts in real facts. This step is designed to fail first. You'll hit a real Agent Platform constraint, read the error, and fix it the idiomatic ADK way.

Part 1: the naive version (this will fail, on purpose)

from google.adk.tools import google_search

root_agent = Agent(
    # ...everything from Step 4 unchanged...
    tools=[google_search, generate_image, skill_toolset],
)

Restart adk web and ask for a post that needs facts. Read the error before you touch anything.

Part 2: the fix

from google.adk.tools import google_search
from google.adk.tools.agent_tool import AgentTool

search_agent = Agent(
    name="web_researcher",
    model="gemini-2.5-flash",
    description="Researches facts, dates, and context on the web.",
    instruction="Research the given query and return a concise summary of relevant facts.",
    tools=[google_search],
)

root_agent = Agent(
    name="social_poster",
    model="gemini-2.5-flash",
    description="Helps the user turn an idea into a polished social media post.",
    instruction="""You help the user turn an idea into a social media post.

Workflow:
1. If the idea needs facts, dates, or context, research it with the
   web_researcher tool first.
2. When drafting, load and follow the relevant skills: post-formatter
   (structure), platform-style (rules for the target platform), and
   brand-voice (tone).
3. If the user asks for an image, load and follow the poster-style skill,
   then call generate_image with a detailed visual description and tell
   them where the file was saved.""",
    tools=[AgentTool(agent=search_agent), generate_image, skill_toolset],
)

Run the full flow: idea → research → skills → draft → image, all in one conversation. This is a complete, standalone agent; everything below adds real publishing.

Publish for real: Buffer + the approval gate

So far every tool has been Python running in-process. MCP (Model Context Protocol) is a standard for connecting to tools that live in a separate process: could be someone else's server, any language, doesn't need to know anything about ADK. Buffer runs one at https://mcp.buffer.com/mcp — no server for you to write or copy, just a key and a URL.

1. Connect a Buffer account

1. Create or log into a free Buffer account, and connect at least one channel (LinkedIn is fine to test with; Buffer authenticates to each platform on its own side).
2. Get an API key: Buffer's Publish settings → developer/API section.
3. Add it to backend/social_poster/.env: BUFFER_API_KEY=...

2. Wire the toolset in, with the approval gate

import os
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import StreamableHTTPConnectionParams

BUFFER_API_KEY = os.environ.get("BUFFER_API_KEY", "")

buffer_toolset = McpToolset(
    connection_params=StreamableHTTPConnectionParams(
        url="https://mcp.buffer.com/mcp",
        headers={"Authorization": f"Bearer {BUFFER_API_KEY}"},
    ),
    # Framework-level approval gate: see below, not just an instruction.
    require_confirmation=True,
)

Add it to root_agent's tools=[...] list, and update the instruction with a posting rule:

    instruction="""... (steps 1-3 from before) ...

4. ALWAYS show the finished draft to the user and ask for their approval
   before any posting action. For an immediate post, ask Buffer to publish
   now rather than schedule.

Posting rules (strict):
- Only post AFTER the user has explicitly approved the exact draft shown to
  them. "Yes", "post it" counts; enthusiasm about the idea does not.
- After posting, share the returned confirmation with the user.""",
    tools=[AgentTool(agent=search_agent), generate_image, skill_toolset, buffer_toolset],

Why require_confirmation, not just an instruction

Right now the instruction text says "ask before posting", but that's a suggestion, not a guarantee. require_confirmation=True is code-level: ADK pauses any call into this toolset and forces an explicit ToolConfirmation before the call actually executes, no matter what the model decides on its own.

Restart and try: draft → Yes, post it. Nothing fires until you approve inside adk web's confirmation control; try rejecting once too, and confirm the post never goes out.

Bonus: add LinkedIn as a second publisher

Buffer covers scheduling and multi-platform posting. LinkedIn's own API adds one thing Buffer can't: an immediate post with an image attached. This step is entirely optional; skip to Step 8 if you're short on time.

1. Read the given LinkedIn MCP server

The starter repo already contains mcp/linkedin_server.py: a FastMCP server with two tools, get_profile and create_post. Open it and find the line where DRY_RUN short-circuits the real LinkedIn API call — that flag is what makes this step safe to run.

2. Get an access token

1. Create a LinkedIn Developer app: linkedin.com/developers/apps → Create app (needs a company page; a dummy one is fine).
2. Add products: Share on LinkedIn (grants w_member_social) and Sign In with LinkedIn using OpenID Connect (grants openid profile), both instant self-serve.
3. Fastest path to a token: the OAuth Token Generator in the Developer Portal: select your app, check all scopes, Request access token, copy it straight in.

DRY_RUN=true
LINKEDIN_ACCESS_TOKEN=...

3. Wire both toolsets in with routing

import sys
from google.adk.tools.mcp_tool.mcp_session_manager import StdioConnectionParams
from mcp import StdioServerParameters

PROJECT_ROOT = pathlib.Path(__file__).resolve().parents[2]
MCP_SERVER = PROJECT_ROOT / "mcp" / "linkedin_server.py"

linkedin_toolset = McpToolset(
    connection_params=StdioConnectionParams(
        server_params=StdioServerParameters(
            command=sys.executable,
            args=[str(MCP_SERVER)],
            env={
                "DRY_RUN": os.environ.get("DRY_RUN", "true"),
                "LINKEDIN_ACCESS_TOKEN": os.environ.get("LINKEDIN_ACCESS_TOKEN", ""),
            },
        ),
    ),
    tool_filter=["get_profile", "create_post"],
    require_confirmation=True,
)

# POST_VIA overrides the LLM's own routing: "buffer" drops the LinkedIn
# tool entirely, "linkedin" drops Buffer even if a key is set. Blank
# exposes both and lets the agent route by what the user asks for.
POST_VIA = os.environ.get("POST_VIA", "").strip().lower()
use_linkedin = POST_VIA != "buffer"
use_buffer = bool(BUFFER_API_KEY) and POST_VIA != "linkedin"

Add the routing guidance to the instruction (choose LinkedIn for an image-carrying immediate post, Buffer for scheduling or other platforms), and add linkedin_toolset to tools=[...] alongside buffer_toolset. Both still gate through require_confirmation=True: same mechanism, two publishers.

Restart and try: ask specifically for an immediate LinkedIn post with an image, then ask to schedule something for next week; watch it pick a different tool each time.

Give it a face: wire up the frontend

CopilotKit + Next.js wiring is its own skill outside ADK, so the frontend is given to you, as-is, already in your starter repo. What matters today is the two connection points that make it talk to the agent you just built.

Nothing to copy: backend/main.py, frontend/, run-backend.sh and run-frontend.sh came with the starter repo. Run chmod +x run-backend.sh run-frontend.sh once if they are not executable.

Connection point 1: the AG-UI bridge (given: read this one)

This is short, and it's the entire reason Step 8 exists: exposing the exact same root_agent object over HTTP.

"""AG-UI bridge: exposes the social_poster agent to the CopilotKit frontend.

Run from the repo root:  uv run uvicorn backend.main:app --port 8000
"""

import pathlib

from ag_ui_adk import ADKAgent, add_adk_fastapi_endpoint
from dotenv import load_dotenv
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from fastapi.staticfiles import StaticFiles

load_dotenv(pathlib.Path(__file__).parent / "social_poster" / ".env")

from backend.social_poster import db  # noqa: E402  (needs .env first)
from backend.social_poster.agent import root_agent  # noqa: E402  (needs .env first)

app = FastAPI(title="social-agent AG-UI backend")

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:3000"],
    allow_methods=["*"],
    allow_headers=["*"],
)

adk_agent = ADKAgent(
    adk_agent=root_agent,
    app_name="social_poster",
    user_id="devcamp-user",  # single-user POC; extract from auth in real apps
)

add_adk_fastapi_endpoint(app, adk_agent, path="/api/adk")

# Serve generate_image's output files so the frontend's image gallery
# (PostGallery.tsx) can render them — tools.py writes local file paths, which
# the browser has no way to read directly otherwise.
GALLERY_DIR = pathlib.Path(__file__).resolve().parents[1] / "gallery"
GALLERY_DIR.mkdir(parents=True, exist_ok=True)
app.mount("/outputs", StaticFiles(directory=GALLERY_DIR), name="outputs")


@app.get("/healthz")
def healthz() -> dict:
    return {"status": "ok"}


@app.get("/api/posts")
def posts() -> dict:
    """Published posts (with whatever image they used), read from the local
    SQLite store — durable across reloads/restarts, unlike ADK session state
    or the browser's own chat history."""
    return {"posts": db.list_posts()}

That's the whole bridge, plus a health check and the /api/posts route the post gallery reads. root_agent is imported unchanged from the agent.py you spent the last six steps writing.

Connection point 2: two given files worth reading

Open these; don't retype them, just understand what they're doing, since they're what makes the approval gate and pipeline stepper actually visible in the browser.

useCopilotAction({
  name: "adk_request_confirmation",  // ADK synthesizes exactly this call name
  renderAndWaitForResponse: ({ args, status, respond }) => {
    // ...renders Approve / Reject buttons...
    return (
      <button onClick={() => respond?.({ confirmed: true })}>Approve</button>
    );
  },
});

const { state } = useCoAgent<AgentState>({ name: "social_poster" });
const current = state?.pipeline_stage ?? "idea";  // shared state, not a message

Connection point 3: publish the pipeline stage (you write this one too)

That shared pipeline_stage value has to come from somewhere: three small callbacks on root_agent that write it into session state as the run progresses. Nothing else in the agent changes.

from typing import Any, Optional
from google.adk.agents.callback_context import CallbackContext
from google.adk.tools.base_tool import BaseTool
from google.adk.tools.tool_context import ToolContext

# idea -> researching -> drafting -> awaiting_approval -> posted
_TOOL_STAGES = {
    "web_researcher": "researching",
    "load_skill": "drafting",
    "generate_image": "drafting",
}


def _init_stage(callback_context: CallbackContext) -> None:
    if "pipeline_stage" not in callback_context.state:
        callback_context.state["pipeline_stage"] = "idea"


def _track_stage(
    tool: BaseTool, args: dict[str, Any], tool_context: ToolContext, tool_response: dict
) -> Optional[dict]:
    if tool.name in _TOOL_STAGES:
        tool_context.state["pipeline_stage"] = _TOOL_STAGES[tool.name]
    elif tool.name == "create_post" and tool_response.get("isError") is False:
        tool_context.state["pipeline_stage"] = "posted"  # only a completed MCP call
    return None  # never modify the tool result


def _stage_after_agent(callback_context: CallbackContext) -> None:
    # A turn that ends mid-pipeline is waiting on the user (draft approval).
    if callback_context.state.get("pipeline_stage") in ("researching", "drafting"):
        callback_context.state["pipeline_stage"] = "awaiting_approval"

root_agent = Agent(
    # ...name, model, description, instruction, tools as before...
    before_agent_callback=_init_stage,
    after_tool_callback=_track_stage,
    after_agent_callback=_stage_after_agent,
)

The Consulting memory stage in the panel stays dim today; it lights up when a memory agent joins in the reference build.

Run it: two terminals

./run-backend.sh    # uv sync + uvicorn on :8000

./run-frontend.sh   # npm install + next dev on :3000

Open http://localhost:3000 and continue as guest.

Run the golden path

One full loop, in the browser, exercising everything you built today.

In the chat sidebar: Draft a LinkedIn post about why agent evals matter more than demos, with an illustration, and post it via Buffer.

What to verify

• The stage panel tracks the run live: Idea → Researching → Drafting → Approval → Posted. (Consulting memory stays dim; the image is generated inside Drafting.)
• The activity feed shows every tool call — web_researcher, load_skill, generate_image — with expandable arguments and results.
• A confirmation card appears before publishing, with Approve / Reject; try Reject once and confirm nothing posts.
• On Approve, Buffer's response (or LinkedIn's dry-run URL, if you built Step 7) appears in the chat.

Troubleshooting

What you built

• An Agent with an instruction and a hand-written function tool
• Agent Skills — progressive disclosure via SkillToolset + load_skill_from_dir, including one you wrote yourself
• AgentTool to isolate google_search — a real Agent Platform constraint, not an arbitrary pattern
• McpToolset against Buffer's remote server, gated by require_confirmation=True — a framework-level human-in-the-loop, independent of the model's own judgement
• Optionally, a second publisher (LinkedIn) with request-level routing between the two
• The AG-UI bridge that exposes that exact agent to a real web app, plus the two frontend files that make ADK's confirmation gate and shared state visible

What's next: the other three pillars

This same agent keeps growing — one pillar at a time, each with its own lab:

Assignment

Before moving on to Lab 2, apply what you just built to your own agent idea — something you actually want to build, not this LinkedIn-poster. Working in your own GCP project:

• Write one Agent with a clear, single-purpose instruction and at least one hand-written function tool (not a canned example)
• Give it one Agent Skill of your own — a SKILL.md that encodes a rule your agent should always follow, loaded via SkillToolset
• Isolate any built-in tool (like google_search) in its own sub-agent if you combine it with function tools, and connect it via AgentTool
• Wire in one MCP toolset — local (stdio) or remote (HTTP) — for a real side effect, gated with require_confirmation=True

Done looks like: uv run adk web against your own agent, a full turn that calls your tool and your skill, and the confirmation gate actually blocking an unapproved side effect. No answer key — the point is applying the pattern, not matching this repo's code.

References

• Agent Development Kit docs — agent types, tools, sessions, the full API reference for everything in this lab.
• Gemini Enterprise Agent Platform overview — the four-pillar framework this whole lab series follows.
• Model Context Protocol (MCP) — the open spec behind today's LinkedIn/Buffer toolsets.