DEV Community: SurfaceDocs

SurfaceDocs + Gemini ADK: Agent Output That Sticks Around

SurfaceDocs — Fri, 20 Mar 2026 14:11:11 +0000

Your ADK agent just synthesized a competitive analysis from 15 sources. It's sitting in your terminal. Now what — copy-paste it into a Google Doc? Slack it as a wall of text? Here's what that looks like with SurfaceDocs:

def publish_report(title: str, content: str) -> dict:
    """Publish a document to SurfaceDocs and return the shareable URL."""
    from surfacedocs import SurfaceDocs
    client = SurfaceDocs()
    result = client.save(content)
    return {"url": result.url, "id": result.id}

That's an ADK tool. A Python function. The agent calls it, gets back a URL, and the output exists somewhere permanent. Let's build the full thing.

The Problem: Agent Output Is Ephemeral

If you've built anything with ADK, you've hit this wall. The agent does impressive work — research, analysis, code generation, report writing — and then the output just... evaporates.

It lives in:

Terminal logs that scroll away
Session state that gets garbage collected
JSON blobs that nobody wants to read

None of these are shareable. None of them look professional. And none of them persist in a way that's useful to anyone who wasn't staring at the terminal when the agent ran.

The typical fix is building custom output infrastructure. A React app, a Notion integration, some unholy Apps Script bridge. You end up spending more time on the output pipeline than on the agent itself.

SurfaceDocs exists specifically for this — it's an API-first document host built for machine-generated content. Think S3 for AI documents, but with a built-in viewer. Your agent publishes structured content, SurfaceDocs gives you a shareable URL with professional rendering. No frontend to build, no formatting to wrangle.

Getting Started

pip install google-adk surfacedocs

Set your environment variables:

export GOOGLE_API_KEY="your-gemini-api-key"
export SURFACEDOCS_API_KEY="sd_live_..."

Optionally, set a default folder to organize agent outputs:

export SURFACEDOCS_FOLDER_ID="your-folder-id"

That's the setup. No servers, no databases, no infrastructure.

Building the SurfaceDocs Tool

ADK tools are Python functions. The agent sees the docstring and parameter types, decides when to call them, and uses the return value. Here's a SurfaceDocs publishing tool:

from surfacedocs import SurfaceDocs, DOCUMENT_SCHEMA, SYSTEM_PROMPT

docs_client = SurfaceDocs()  # picks up SURFACEDOCS_API_KEY from env

def publish_document(content: str, folder_id: str = "") -> dict:
    """Publish a structured document to SurfaceDocs.

    Use this tool when you've completed research, analysis, or any work product 
    that should be saved as a shareable document. Format the content as a JSON 
    string matching the SurfaceDocs document schema.

    Args:
        content: JSON string with document title and blocks following the 
                 SurfaceDocs schema.
        folder_id: Optional folder ID to organize the document.

    Returns:
        Dictionary with the shareable URL and document ID.
    """
    kwargs = {}
    if folder_id:
        kwargs["folder_id"] = folder_id

    result = docs_client.save(content, **kwargs)
    return {
        "url": result.url,
        "document_id": result.id,
        "status": "published"
    }

The key detail: SurfaceDocs provides DOCUMENT_SCHEMA and SYSTEM_PROMPT constants that tell the LLM exactly how to structure its output. You feed these into the agent's instructions so Gemini generates content the SDK can consume directly.

The Full Agent: A Research Publisher

Here's a complete, runnable example — a research agent that investigates a topic and publishes its findings as a formatted document:

from google.adk.agents import LlmAgent
from surfacedocs import SurfaceDocs, DOCUMENT_SCHEMA, SYSTEM_PROMPT

# Initialize SurfaceDocs client
docs_client = SurfaceDocs()


def publish_document(content: str, folder_id: str = "") -> dict:
    """Publish a structured document to SurfaceDocs.

    Call this tool when your research is complete and you're ready to 
    publish. Format the content as a JSON string with a title and blocks 
    following the SurfaceDocs document schema provided in your instructions.

    Args:
        content: JSON string with document title and content blocks.
        folder_id: Optional folder ID for organization.

    Returns:
        Dictionary with the shareable URL and document ID.
    """
    kwargs = {}
    if folder_id:
        kwargs["folder_id"] = folder_id
    result = docs_client.save(content, **kwargs)
    return {"url": result.url, "document_id": result.id}


research_agent = LlmAgent(
    name="research_publisher",
    model="gemini-2.5-flash",
    instruction=f"""You are a research analyst. When given a topic, produce a 
thorough, well-structured report and publish it using the publish_document tool.

Your report should include:
- An executive summary
- Key findings with supporting detail
- A conclusion with recommendations

When you're ready to publish, format your document as a JSON string 
following this schema:

{DOCUMENT_SCHEMA}

{SYSTEM_PROMPT}

After publishing, share the URL with the user.""",
    tools=[publish_document],
)

Run it with the ADK runner or CLI:

from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService

session_service = InMemorySessionService()
runner = Runner(
    agent=research_agent,
    app_name="research_app",
    session_service=session_service,
)

When the agent finishes its research, it calls publish_document with structured JSON content. SurfaceDocs renders it — headings, code blocks, tables, callouts, the works — and returns a URL like https://app.surfacedocs.dev/d/abc123.

The agent gets that URL back and can share it in its response. The user clicks the link and sees a clean, formatted document. Not a JSON blob. Not a terminal dump. A real document.

What You Get

The published document supports all the block types you'd expect:

Headings at multiple levels
Code blocks with syntax highlighting
Tables for structured data
Callouts for warnings, tips, and key takeaways
Mermaid diagrams for architecture and flow charts
Lists, blockquotes, images, dividers

Everything renders in a clean viewer at a stable URL. No expiration, no login wall. Send the link to your team, your client, your Slack channel — it just works.

If you set a folder_id, documents are organized together. Run the agent daily and you build up a library of reports, all browsable in one place.

Multi-Agent Systems: Every Agent Gets an Output Layer

This gets more interesting with ADK's sub_agents pattern. In a multi-agent system, each agent can publish its own work products independently:

from google.adk.agents import LlmAgent

market_analyst = LlmAgent(
    name="market_analyst",
    model="gemini-2.5-flash",
    instruction="Analyze market trends and publish your report...",
    tools=[publish_document],
)

technical_reviewer = LlmAgent(
    name="technical_reviewer",
    model="gemini-2.5-flash",
    instruction="Review technical architecture and publish findings...",
    tools=[publish_document],
)

coordinator = LlmAgent(
    name="coordinator",
    model="gemini-2.5-flash",
    instruction="""Coordinate the research team. Delegate market analysis 
    to market_analyst and technical review to technical_reviewer. 
    Each will publish their own reports and return URLs.""",
    sub_agents=[market_analyst, technical_reviewer],
)

The coordinator delegates. Each sub-agent does its work and publishes to SurfaceDocs. The coordinator collects the URLs and presents them. You end up with multiple professional documents from a single prompt — each with its own shareable link, each organized in your folder.

This is where the "output layer" concept clicks. You're not building per-agent output handling. You're not stitching together markdown files. Every agent in the system has the same publishing primitive, and the output is instantly accessible to anyone with the link.

Why This Matters

The gap between "agent did something useful" and "someone can use what the agent did" is where most agent projects stall. You build an impressive demo, the agent generates great analysis, and then you spend a week building a way to get that analysis in front of people.

SurfaceDocs collapses that gap to a function call. The agent's output is a first-class artifact with a URL the moment it's generated. No infrastructure to maintain, no frontend to build, no formatting pipeline to debug.

For ADK specifically, the fit is clean — tools are just Python functions, SurfaceDocs is a Python SDK, and the integration is a few lines of code wiring them together. The agent doesn't need to know about document hosting. It just calls a tool and gets a URL back.

If you're building ADK agents that generate anything worth reading twice, give them somewhere to put it.

SurfaceDocs + LlamaIndex: From RAG Pipeline to Shareable Report

SurfaceDocs — Tue, 17 Mar 2026 17:02:57 +0000

SurfaceDocs + LlamaIndex: From RAG Pipeline to Shareable Report

Your RAG pipeline answers questions beautifully. It retrieves the right chunks, synthesizes a coherent response, even cites its sources. Then the output prints to stdout and dies. What if every answer your pipeline produced was instantly a shareable, hosted document?

The last mile problem

RAG pipelines are the backbone of most production LLM applications. You invest real engineering effort into chunking strategies, embedding models, retrieval tuning, prompt design. The analysis is the hard part, and we've gotten good at it.

But sharing the result? That's where things fall apart. You copy-paste into a Google Doc. You screenshot a notebook cell. You build a bespoke Flask app to render responses. You email a JSON blob and hope someone reads it. Every team reinvents this output layer, and it's never the part anyone wants to work on.

The pipeline deserves a better destination than print(response).

The minimal version: query and publish

Let's start with something concrete. A LlamaIndex RAG pipeline that queries a document collection and saves the response to SurfaceDocs. No agent framework, no complexity — just the core loop.

from datetime import datetime, timezone
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from surfacedocs import SurfaceDocs

# Build the index
documents = SimpleDirectoryReader("./data").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()

# Query
query = "What are the key architectural decisions and their tradeoffs?"
response = query_engine.query(query)

# Publish
sd = SurfaceDocs()  # uses SURFACEDOCS_API_KEY env var
result = sd.save_raw(
    title=f"Research: {query[:80]}",
    blocks=[
        {"type": "heading", "content": "Query", "metadata": {"level": 2}},
        {"type": "paragraph", "content": query},
        {"type": "heading", "content": "Analysis", "metadata": {"level": 2}},
        {"type": "paragraph", "content": str(response)},
        {"type": "heading", "content": "Sources", "metadata": {"level": 2}},
        {"type": "list", "content": "\n".join(
            f"- {node.metadata.get('file_name', 'unknown')} (score: {node.score:.3f})"
            for node in response.source_nodes
        ), "metadata": {"listType": "bullet"}},
    ],
    metadata={
        "query": query,
        "timestamp": datetime.now(timezone.utc).isoformat(),
        "source_count": len(response.source_nodes),
    }
)

print(f"Published: {result.url}")

That's it. Your RAG response now has a URL. Send it in Slack, drop it in a ticket, bookmark it for later. The response, its sources, and the original query are all preserved together as a formatted document.

The source_nodes part matters. RAG without provenance is just vibes. By extracting the source filenames and relevance scores into the published doc, anyone reading it can evaluate the answer's grounding — not just take it on faith.

Building a research agent

The basic version works, but it's a script. Let's make the pipeline smarter. LlamaIndex's FunctionAgent lets you build agents that use tools — including a tool that publishes findings as it works.

import asyncio
from datetime import datetime, timezone
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from llama_index.core.agent.workflow import FunctionAgent
from llama_index.llms.openai import OpenAI
from surfacedocs import SurfaceDocs

# Setup
documents = SimpleDirectoryReader("./data").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine()

sd = SurfaceDocs()

# Tools
async def search_docs(query: str) -> str:
    """Search the document index for relevant information."""
    response = query_engine.query(query)
    sources = [n.metadata.get("file_name", "unknown") for n in response.source_nodes]
    return f"{response}\n\nSources: {', '.join(sources)}"

async def publish_report(title: str, summary: str, findings: str, recommendations: str) -> str:
    """Publish a research report to SurfaceDocs. Call this when your analysis is complete."""
    result = sd.save_raw(
        title=title,
        blocks=[
            {"type": "heading", "content": "Executive Summary", "metadata": {"level": 1}},
            {"type": "paragraph", "content": summary},
            {"type": "divider", "content": ""},
            {"type": "heading", "content": "Findings", "metadata": {"level": 2}},
            {"type": "paragraph", "content": findings},
            {"type": "heading", "content": "Recommendations", "metadata": {"level": 2}},
            {"type": "paragraph", "content": recommendations},
        ],
        metadata={
            "generated_by": "research-agent",
            "model": "gpt-4o",
            "timestamp": datetime.now(timezone.utc).isoformat(),
        }
    )
    return f"Report published: {result.url}"

# Agent
agent = FunctionAgent(
    tools=[search_docs, publish_report],
    llm=OpenAI(model="gpt-4o"),
    system_prompt="""You are a research analyst. When given a research question:
1. Search the documents thoroughly (multiple queries if needed)
2. Synthesize findings into a structured analysis
3. Publish the final report using the publish tool
Always publish your work — don't just print it.""",
)

async def main():
    response = await agent.run(
        user_msg="Analyze the system's authentication architecture. "
                 "What are the security implications and what would you change?"
    )
    print(response)

asyncio.run(main())

The key design choice here: the agent decides when to publish. The publish_report tool is just another tool in its toolkit. You give the agent a research question, it searches the index (potentially multiple times from different angles), synthesizes its findings, and saves the result — all autonomously.

The tool's docstring does real work here. "Call this when your analysis is complete" guides the agent to publish as a final step rather than dumping intermediate results. Tool descriptions are part of your agent architecture; treat them like API documentation.

Multi-step pipeline with structured output

For production use, you usually want more control over the output format. Here's a pipeline that runs multiple queries, assembles a structured report, and publishes with full metadata.

import asyncio
from datetime import datetime, timezone
from llama_index.core import VectorStoreIndex, SimpleDirectoryReader
from surfacedocs import SurfaceDocs

documents = SimpleDirectoryReader("./data").load_data()
index = VectorStoreIndex.from_documents(documents)
query_engine = index.as_query_engine(similarity_top_k=5)
sd = SurfaceDocs()

def build_report_blocks(sections: list[dict]) -> list[dict]:
    """Convert analysis sections into SurfaceDocs blocks."""
    blocks = []
    for section in sections:
        blocks.append({
            "type": "heading",
            "content": section["title"],
            "metadata": {"level": section.get("level", 2)}
        })

        if section.get("quote"):
            blocks.append({
                "type": "quote",
                "content": section["quote"]
            })

        blocks.append({
            "type": "paragraph",
            "content": section["content"]
        })

        if section.get("code"):
            blocks.append({
                "type": "code",
                "content": section["code"],
                "metadata": {"language": section.get("language", "text")}
            })

        if section.get("data"):
            blocks.append({
                "type": "table",
                "content": section["data"]
            })

        blocks.append({"type": "divider", "content": ""})

    return blocks

async def analyze_and_publish(topic: str, queries: list[str]) -> str:
    """Run multiple queries against the index and publish a combined report."""
    sections = []

    for query in queries:
        response = query_engine.query(query)

        source_table = "| Source | Relevance |\n|--------|----------|\n"
        for node in response.source_nodes:
            name = node.metadata.get("file_name", "unknown")
            source_table += f"| {name} | {node.score:.2f} |\n"

        sections.append({
            "title": query,
            "content": str(response),
            "data": source_table,
            "level": 2,
        })

    blocks = [
        {"type": "heading", "content": topic, "metadata": {"level": 1}},
        {"type": "paragraph", "content": (
            f"Automated analysis covering {len(queries)} research questions. "
            f"Generated {datetime.now(timezone.utc).strftime('%Y-%m-%d %H:%M UTC')}."
        )},
        {"type": "divider", "content": ""},
    ] + build_report_blocks(sections)

    result = sd.save_raw(
        title=f"Analysis: {topic}",
        blocks=blocks,
        metadata={
            "topic": topic,
            "query_count": len(queries),
            "model": "gpt-4o",
            "timestamp": datetime.now(timezone.utc).isoformat(),
            "tags": ["automated-analysis", "rag-pipeline"],
        }
    )
    return result.url

async def main():
    url = await analyze_and_publish(
        topic="System Security Audit",
        queries=[
            "What authentication mechanisms are used and how are credentials stored?",
            "How is authorization handled across services?",
            "What are the known security vulnerabilities or risks?",
            "What logging and monitoring exists for security events?",
        ]
    )
    print(f"Report: {url}")

asyncio.run(main())

A few things worth noting about this approach:

Source tables per section. Each query's response includes a relevance-scored source table. When someone reads the report, they can see exactly which documents backed each section. This is table stakes for auditable RAG output.

Metadata as first-class data. The metadata dict on save_raw() isn't decoration — it's structured data you can use for organization and filtering. Tag your reports by pipeline, model version, topic. When you've generated 500 reports, you'll want to filter.

build_report_blocks is your formatting layer. It maps a simple dict structure to SurfaceDocs blocks. This separation matters because your analysis logic shouldn't know about rendering. If you swap output destinations later, you change one function.

Why this matters

The pattern here is simple: RAG pipeline → structured blocks → hosted document. A few lines of SurfaceDocs code on top of a pipeline you've already built.

SurfaceDocs handles the hosting, rendering, and sharing. You don't build a viewer, deploy a static site, or set up auth. Your pipeline's output just has a URL now.

The engineering value isn't in any single tool — it's in closing the loop. A RAG pipeline that produces a shareable artifact is a product. One that prints to a terminal is a demo.

Links:

SurfaceDocs + AutoGen: Multi-Agent Reports That Don't Disappear

SurfaceDocs — Fri, 13 Mar 2026 14:07:24 +0000

Your multi-agent team just spent 30 seconds coordinating across three LLM calls to produce a research report. The output? A string in your terminal. You copy it into a Google Doc, lose the formatting, forget to share it, and next week nobody can find it. The agents did their job. Your output pipeline didn't.

Here's how to fix that with SurfaceDocs — an API-first document layer that turns agent output into hosted, shareable, versioned documents. No frontend to build. No S3 buckets to configure.

The Problem: AutoGen Output Goes Nowhere

Let's start with a typical AutoGen 0.4 setup. Three agents collaborate in a RoundRobinGroupChat to research a topic and produce a report:

import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.conditions import TextMentionTermination
from autogen_ext.models.openai import OpenAIChatCompletionClient

model_client = OpenAIChatCompletionClient(model="gpt-4o")

researcher = AssistantAgent(
    "researcher",
    model_client=model_client,
    system_message="You are a research analyst. Given a topic, find key facts, trends, and data points. Be thorough but concise.",
)

analyst = AssistantAgent(
    "analyst",
    model_client=model_client,
    system_message="You are a strategic analyst. Take the researcher's findings and identify insights, risks, and opportunities. Be opinionated.",
)

writer = AssistantAgent(
    "writer",
    model_client=model_client,
    system_message="You are a report writer. Synthesize the research and analysis into a clear, structured report. When done, end your message with FINAL_REPORT.",
)

team = RoundRobinGroupChat(
    [researcher, analyst, writer],
    termination_condition=TextMentionTermination("FINAL_REPORT"),
)

async def main():
    result = await team.run(task="Research the current state of edge AI deployment in manufacturing")
    # Now what?
    print(result.messages[-1].content)  # <- This is where most pipelines stop

asyncio.run(main())

That print() at the end is the whole problem. The report exists for exactly as long as your terminal session does. Maybe you pipe it to a file. Maybe you paste it into Slack. Either way, it's not searchable, not shareable via URL, and not versioned.

The Fix: Three Lines to a Hosted Document

Install the SurfaceDocs SDK alongside your AutoGen dependencies:

pip install autogen-agentchat autogen-ext[openai] surfacedocs

Now replace that print() with something useful:

from surfacedocs import SurfaceDocs

docs = SurfaceDocs()  # reads SURFACEDOCS_API_KEY from env

result = docs.save_raw(
    title="Edge AI in Manufacturing — Research Report",
    blocks=[
        {"type": "heading", "content": "Edge AI in Manufacturing", "metadata": {"level": 1}},
        {"type": "paragraph", "content": report_content},
    ],
    metadata={"source": "autogen-team", "tags": ["research", "edge-ai"]},
)

print(result.url)  # https://app.surfacedocs.dev/d/abc123

That URL is live immediately. Share it in Slack, drop it in a ticket, send it to a stakeholder. The document is hosted, formatted, and permanent.

But we can do better than manually constructing blocks.

Full Working Example: Structured Output From Agents

The real power comes from having your writer agent output structured content that maps directly to SurfaceDocs' document schema. SurfaceDocs ships a SYSTEM_PROMPT and DOCUMENT_SCHEMA you can inject into your agent's instructions — the LLM outputs JSON, and the SDK saves it directly.

Here's the complete, runnable pipeline:

import asyncio
import json
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.conditions import TextMentionTermination
from autogen_ext.models.openai import OpenAIChatCompletionClient
from surfacedocs import SurfaceDocs, SYSTEM_PROMPT, DOCUMENT_SCHEMA

model_client = OpenAIChatCompletionClient(model="gpt-4o")
docs = SurfaceDocs()  # uses SURFACEDOCS_API_KEY env var

researcher = AssistantAgent(
    "researcher",
    model_client=model_client,
    system_message=(
        "You are a research analyst. Given a topic, identify key facts, "
        "recent developments, statistics, and notable players. "
        "Present findings as structured bullet points. Be thorough."
    ),
)

analyst = AssistantAgent(
    "analyst",
    model_client=model_client,
    system_message=(
        "You are a strategic analyst. Review the researcher's findings and "
        "provide: 1) Key insights, 2) Risks and challenges, 3) Opportunities. "
        "Be direct and opinionated. Support claims with the research provided."
    ),
)

writer = AssistantAgent(
    "writer",
    model_client=model_client,
    system_message=(
        "You are a report writer. Take the research and analysis from your "
        "teammates and produce a final report.\n\n"
        "OUTPUT FORMAT: You must output ONLY valid JSON matching this schema:\n"
        f"{json.dumps(DOCUMENT_SCHEMA, indent=2)}\n\n"
        "Use heading, paragraph, list, and quote block types to structure "
        "the report clearly. Include a title field.\n\n"
        "When your JSON output is complete, add FINAL_REPORT on the last line."
    ),
)

team = RoundRobinGroupChat(
    [researcher, analyst, writer],
    termination_condition=TextMentionTermination("FINAL_REPORT"),
)


async def run_research_team(topic: str, folder_id: str | None = None) -> str:
    """Run the research team and publish output to SurfaceDocs."""
    result = await team.run(task=topic)

    # The writer's output is the last message (before termination)
    final_output = result.messages[-1].content

    # Strip the FINAL_REPORT marker and parse JSON
    json_str = final_output.replace("FINAL_REPORT", "").strip()

    try:
        doc_json = json.loads(json_str)
        # Use docs.save() which accepts LLM-structured JSON directly
        doc_result = docs.save(doc_json, folder_id=folder_id)
    except json.JSONDecodeError:
        # Fallback: save as raw paragraphs if JSON parsing fails
        doc_result = docs.save_raw(
            title=f"Research Report: {topic[:50]}",
            blocks=[
                {"type": "heading", "content": f"Research: {topic}", "metadata": {"level": 1}},
                {"type": "paragraph", "content": final_output},
            ],
            metadata={"source": "autogen-team", "tags": ["research"]},
        )

    return doc_result.url


async def main():
    url = await run_research_team(
        topic="Analyze the current state of edge AI deployment in manufacturing: "
              "key vendors, adoption barriers, and 2026 outlook.",
        folder_id="your_folder_id",  # optional: organize into a folder
    )
    print(f"Report published: {url}")


asyncio.run(main())

A few things to note:

DOCUMENT_SCHEMA tells the writer agent exactly what JSON structure to produce. No prompt engineering guesswork.
docs.save() accepts the raw LLM JSON output and handles validation. If the agent produces well-formed document JSON, it goes straight to a hosted doc.
The fallback matters. LLMs sometimes fumble structured output. Wrapping the parse in a try/except with save_raw() means you never lose output — worst case, it's a plain paragraph instead of a formatted report.
folder_id is optional but useful. Organize reports by project, client, or team.

Versioning: Same URL, Updated Content

Research isn't a one-shot task. You run the team on Monday, get feedback, run it again on Wednesday with a refined prompt. Without versioning, that's two separate documents and a broken link in someone's Slack message.

push_version solves this. Same document URL, new content:

async def update_report(document_id: str, topic: str) -> str:
    """Re-run the team and push a new version to an existing document."""
    result = await team.run(task=topic)
    final_output = result.messages[-1].content
    json_str = final_output.replace("FINAL_REPORT", "").strip()

    try:
        doc_json = json.loads(json_str)
        version_result = docs.push_version(document_id, doc_json)
    except json.JSONDecodeError:
        # Fallback: push raw content as new version
        version_result = docs.push_version(document_id, {
            "title": f"Research Report (Updated): {topic[:50]}",
            "blocks": [
                {"type": "paragraph", "content": final_output},
            ],
        })

    return version_result.url


async def main():
    # First run — creates the document
    url = await run_research_team("Edge AI in manufacturing: 2026 outlook")
    document_id = url.split("/")[-1]  # extract ID from URL
    print(f"v1 published: {url}")

    # Second run — updates the same document
    url = await update_report(document_id, "Edge AI in manufacturing: 2026 outlook with focus on ROI data")
    print(f"v2 published: {url}")  # same URL, new content


asyncio.run(main())

Anyone who bookmarked or received the original URL now sees the latest version. Previous versions are still accessible through the SurfaceDocs UI. This is particularly useful for recurring reports — weekly market scans, daily standups, ongoing research threads.

Why This Matters

The pattern here isn't specific to research reports. Any AutoGen pipeline that produces human-readable output benefits from a proper output layer:

Code review summaries from a multi-agent review team → versioned docs per PR
Competitive analysis from researcher + analyst agents → shared with the sales team via URL
Incident postmortems from log-analyzer + writer agents → searchable via the SurfaceDocs API
Meeting notes from transcription + summarizer agents → organized in folders by project

The point is: agent output deserves better than print(). It deserves a URL.

Where to Go From Here

SurfaceDocs docs: docs.surfacedocs.dev — full SDK reference, block types, search API
SurfaceDocs: surfacedocs.dev — free tier, no credit card
AutoGen docs: microsoft.github.io/autogen — team patterns, custom agents, tool use
pip install surfacedocs autogen-agentchat autogen-ext[openai] — everything you need

The multi-agent coordination problem is mostly solved. The output problem isn't. Wire in a proper output layer and your agents' work actually goes somewhere.

SurfaceDocs + OpenAI Agents SDK: Structured Output to Shareable Docs

SurfaceDocs — Tue, 10 Mar 2026 14:09:18 +0000

The Output Problem

Here's something that bugs me about most agent frameworks: they're obsessed with input — tools, RAG, memory, context windows — but nobody talks about where the output goes.

You build a multi-agent workflow. A research agent gathers data, an analyst crunches it, a writer produces a report. Beautiful architecture. Then result.final_output dumps to stdout and... that's it. You copy-paste it into a Google Doc. Or worse, it lives in a log file forever.

Agents need output surfaces — places where their work product becomes something you can share, link to, and actually use. Not just tools for doing things, but infrastructure for producing things.

I've been using SurfaceDocs for this. It's an API-first document service built specifically for machine-generated content. Agent produces structured output, SurfaceDocs turns it into a shareable URL. No templates, no CMS, no infrastructure to maintain. Here's how I wire it up with the OpenAI Agents SDK.

The OpenAI Agents SDK in 30 Seconds

If you're reading this, you probably know the Agents SDK. Quick refresher on the parts that matter here:

from agents import Agent, Runner

agent = Agent(
    name="Writer",
    instructions="You write technical reports.",
    output_type=MyPydanticModel,  # structured output
)

result = Runner.run_sync(agent, "Write a report on X")
# result.final_output is a MyPydanticModel instance

The key feature for us: output_type. Pass a Pydantic model and the SDK uses OpenAI's structured outputs under the hood. You get typed, validated output — not a blob of text you have to parse. This is what makes the SurfaceDocs integration clean.

The Integration Pattern

The pattern is straightforward:

Define a Pydantic model that matches SurfaceDocs' document schema
Use it as your agent's output_type
After the run, pass the structured output to docs.save()

Agent focuses on content. Publishing is a post-processing step. Clean separation.

Agent → structured output (Pydantic) → SurfaceDocs → shareable URL

Let's build it.

Example 1: Agent That Publishes a Report

First, install both packages:

pip install openai-agents surfacedocs

Now the code. I'll define a Pydantic model that mirrors the SurfaceDocs document format, use it as the agent's output type, and save the result:

from __future__ import annotations
from pydantic import BaseModel
from agents import Agent, Runner
from surfacedocs import SurfaceDocs

# -- Define the document structure as Pydantic models --

class BlockMetadata(BaseModel):
    level: int | None = None
    language: str | None = None
    listType: str | None = None

class Block(BaseModel):
    type: str  # heading, paragraph, code, list, quote, etc.
    content: str
    metadata: BlockMetadata | None = None

class Document(BaseModel):
    title: str
    blocks: list[Block]

# -- Create the agent --

agent = Agent(
    name="Report Writer",
    instructions="""You write well-structured technical reports.

    Output a document with a clear title and blocks of content.
    Use a variety of block types:
    - heading blocks (with metadata.level = 1, 2, or 3)
    - paragraph blocks for body text
    - code blocks (with metadata.language set appropriately)
    - list blocks for enumerations (metadata.listType = "bullet" or "ordered")
    - quote blocks for key takeaways

    Write substantive, information-dense content. No filler.""",
    output_type=Document,
)

# -- Run and publish --

result = Runner.run_sync(
    agent,
    "Write a technical report on Python async patterns: "
    "when to use asyncio vs threading vs multiprocessing. "
    "Include code examples.",
)

doc: Document = result.final_output

# Publish to SurfaceDocs
docs = SurfaceDocs()  # uses SURFACEDOCS_API_KEY env var
saved = docs.save_raw(
    title=doc.title,
    blocks=[block.model_dump(exclude_none=True) for block in doc.blocks],
    metadata={"source": "report-writer-agent"},
)

print(f"Published: {saved.url}")

Run it, and you get a URL. Open it in a browser — a clean, formatted document you can share with anyone. No copy-pasting, no formatting, no "let me put this in a Google Doc."

The docs.save_raw() method takes the title and blocks directly. The exclude_none=True keeps the payload clean — no null metadata fields cluttering things up.

A note on the schema approach

You could also use SurfaceDocs' built-in DOCUMENT_SCHEMA and SYSTEM_PROMPT with the raw OpenAI API. But the Agents SDK's output_type is Pydantic-native, so defining your own model gives you more control and keeps everything in Agents SDK patterns. Either approach works.

Example 2: Multi-Agent Research → Report Pipeline

This is where it gets interesting. Two agents:

Research Agent — gathers information using a tool (simulated here, but you'd wire up web search or a database)
Report Writer Agent — takes research findings and produces a structured document

The research agent hands off to the writer via the SDK's handoff mechanism.

from __future__ import annotations
from pydantic import BaseModel
from agents import Agent, Runner, function_tool
from surfacedocs import SurfaceDocs

# -- Document schema (same as before) --

class BlockMetadata(BaseModel):
    level: int | None = None
    language: str | None = None
    listType: str | None = None

class Block(BaseModel):
    type: str
    content: str
    metadata: BlockMetadata | None = None

class Document(BaseModel):
    title: str
    blocks: list[Block]

# -- Research tool --

@function_tool
def search_web(query: str) -> str:
    """Search the web for information on a topic."""
    # In production, wire this to Brave Search, Tavily, etc.
    # Returning mock data for the example.
    return (
        f"Search results for '{query}':\n"
        "1. FastAPI has become the most popular async Python framework, "
        "growing 300% in GitHub stars since 2023.\n"
        "2. Litestar emerged as a strong alternative with built-in "
        "dependency injection.\n"
        "3. Django 5.x added async view support but adoption is gradual.\n"
        "4. Starlette remains the foundation for most async frameworks."
    )

# -- The report writer agent (produces structured output) --

report_writer = Agent(
    name="Report Writer",
    instructions="""You receive research findings and produce a polished
    technical report as a structured document.

    Use these block types:
    - heading (metadata.level: 1 for title sections, 2 for subsections)
    - paragraph for body text
    - list for comparisons and enumerations  
    - quote for key insights or conclusions
    - code for any technical examples

    Synthesize the research into a coherent narrative.
    Be opinionated — make recommendations, not just summaries.""",
    output_type=Document,
)

# -- The research agent (gathers info, then hands off) --

research_agent = Agent(
    name="Research Lead",
    instructions="""You are a senior technical researcher. Given a topic:

    1. Use the search tool to gather information (make 2-3 searches 
       with different angles)
    2. Once you have enough material, hand off to the Report Writer 
       with a clear summary of your findings.

    Include specific data points, comparisons, and trends.""",
    tools=[search_web],
    handoffs=[report_writer],
)

# -- Run the pipeline --

result = Runner.run_sync(
    research_agent,
    "Research the current state of async Python web frameworks in 2025. "
    "Compare FastAPI, Django, Litestar, and Starlette.",
)

doc: Document = result.final_output

# Publish
docs = SurfaceDocs()
saved = docs.save_raw(
    title=doc.title,
    blocks=[block.model_dump(exclude_none=True) for block in doc.blocks],
    metadata={
        "source": "research-pipeline",
        "agents": ["research-lead", "report-writer"],
    },
)

print(f"Published: {saved.url}")

What's happening here: the research agent runs its searches, accumulates context, then hands off to the report writer. The report writer's output_type=Document ensures the final output is structured. We catch it at the end and publish.

The metadata field is handy — I tag documents with which agents produced them, what pipeline they came from, timestamps, whatever makes sense. Useful when you're publishing dozens of documents and need to trace provenance.

Organizing output with folders

When your agents produce documents regularly, folders keep things sane:

docs = SurfaceDocs()

# Create a folder for this pipeline's output
folder = docs.create_folder("Async Python Research")

saved = docs.save_raw(
    title=doc.title,
    blocks=[block.model_dump(exclude_none=True) for block in doc.blocks],
    folder_id=folder.id,
    metadata={"source": "research-pipeline"},
)

Why This Matters

There's a conceptual gap in how we build agents today. We've gotten good at giving agents capabilities — tools, function calling, code execution. But we haven't thought enough about giving agents output surfaces.

Think about how human knowledge workers operate. A consultant doesn't just "think about the problem" — they produce a deliverable. A slide deck, a report, a memo. The artifact is the point.

Agents should work the same way. The value isn't in the inference call. It's in the artifact that comes out the other side — something with a URL, something you can send to a stakeholder, something that persists beyond the terminal session.

This is the pattern I keep coming back to:

Structured output to ensure the agent produces well-formed content (not just freeform text)
A document service to turn that content into something shareable
Metadata and folders to organize output at scale

SurfaceDocs handles steps 2 and 3. The Agents SDK handles step 1 beautifully with Pydantic models. Together, they close the loop from "agent ran successfully" to "here's the URL with the results."

Getting Started

SurfaceDocs: surfacedocs.dev — grab an API key, pip install surfacedocs

OpenAI Agents SDK: pip install openai-agents — docs on GitHub

The full examples from this article work as-is. Set your OPENAI_API_KEY and SURFACEDOCS_API_KEY environment variables and run them.

The broader point: if you're building agents, think about where the output goes. Your agents are doing real work. Give that work a place to live.

SurfaceDocs + CrewAI: Publishable Agent Work Products

SurfaceDocs — Fri, 06 Mar 2026 15:05:49 +0000

The Output Problem

CrewAI crews produce real work. Research reports, competitive analyses, technical documentation, content drafts. You define your agents, wire up the tasks, call crew.kickoff(), and get back... a string.

result = crew.kickoff()
print(result)  # 800 words of competitive analysis, dumped to stdout

Now what? You copy-paste it into a Google Doc. Or write it to a markdown file that lives on your laptop. Maybe you pipe it into Slack. The work product your agents spent tokens and time producing gets treated like log output — ephemeral, unstructured, unshareable.

This is a gap in the agent tooling ecosystem. We've invested heavily in making agents do work — better prompting, tool use, multi-agent orchestration. But we've barely thought about what happens to the output. Every team running CrewAI crews in production ends up building some bespoke viewer, or manually reformatting agent output into something presentable. It's the last mile problem nobody's solving at the framework level.

The Fix: A Publishing Layer

SurfaceDocs is a hosted document service built for machine-generated content — the output layer for AI pipelines. pip install surfacedocs, call docs.save(), get a shareable URL. That's the whole integration surface.

Here's a complete CrewAI crew that researches a topic and publishes the result:

import os
from crewai import Agent, Task, Crew
from crewai.tools import BaseTool
from surfacedocs import SurfaceDocs, SYSTEM_PROMPT, OPENAI_DOCUMENT_SCHEMA

docs = SurfaceDocs(api_key=os.environ["SURFACEDOCS_API_KEY"])

class PublishTool(BaseTool):
    name: str = "publish_document"
    description: str = "Publish a structured document and return a shareable URL."

    def _run(self, content: str) -> str:
        result = docs.save(content, folder_id=os.environ.get("SURFACEDOCS_FOLDER_ID"))
        return f"Published: {result.url}"

researcher = Agent(
    role="Senior Research Analyst",
    goal="Produce a comprehensive market research report",
    backstory="You're a seasoned analyst who writes clear, data-driven reports.",
    llm="gpt-4o",
)

publisher = Agent(
    role="Report Publisher",
    goal="Format and publish the final report as a shareable document",
    backstory=f"""You take research output and structure it for publication.

{SYSTEM_PROMPT}""",
    tools=[PublishTool()],
    llm="gpt-4o",
)

research_task = Task(
    description="Research the current state of AI agent frameworks. "
                "Cover CrewAI, LangGraph, AutoGen, and Swarm. "
                "Include strengths, weaknesses, and adoption trends.",
    expected_output="A detailed research report with sections and analysis.",
    agent=researcher,
)

publish_task = Task(
    description="Take the research report and publish it as a structured document. "
                "Use the publish_document tool with the formatted content.",
    expected_output="A shareable URL to the published report.",
    agent=publisher,
)

crew = Crew(
    agents=[researcher, publisher],
    tasks=[research_task, publish_task],
)

result = crew.kickoff()
print(result)  # https://app.surfacedocs.dev/d/abc123

Instead of a string that evaporates, you get a hosted URL. Send it to your team, your client, your stakeholders. The document is rendered, shareable, and persistent.

How the Schema Approach Works

The key to getting well-structured output from SurfaceDocs is the schema approach. Two imports do the heavy lifting:

SYSTEM_PROMPT — Instructions that tell the LLM how to structure content in SurfaceDocs' block format (headings, paragraphs, code blocks, lists, Mermaid diagrams)
OPENAI_DOCUMENT_SCHEMA — A JSON schema for OpenAI-compatible structured output

The flow looks like this:

CrewAI Task Output (raw text)
    → Publisher Agent (with SYSTEM_PROMPT in backstory)
        → Structured document (matching DOCUMENT_SCHEMA)
            → docs.save(structured_content)
                → Shareable URL

When the publisher agent has SYSTEM_PROMPT in its context, it knows how to format content into SurfaceDocs' block structure. The LLM does the formatting work — you just save the result.

For tighter control, you can define a Pydantic model that mirrors the SurfaceDocs schema and use CrewAI's output_pydantic:

from pydantic import BaseModel

class SurfaceDocument(BaseModel):
    title: str
    blocks: list[dict]

publish_task = Task(
    description="Publish the research report as a structured document.",
    expected_output="A structured document with title and blocks.",
    output_pydantic=SurfaceDocument,  # Force schema compliance
    agent=publisher,
)

This guarantees the task output is structured before you pass it to docs.save().

The Callback Approach: Automatic Publishing

The tool-based approach gives agents control over when to publish. But sometimes you just want every crew run to produce a document automatically. CrewAI's task callbacks make this clean:

from surfacedocs import SurfaceDocs, SYSTEM_PROMPT

docs = SurfaceDocs(api_key=os.environ["SURFACEDOCS_API_KEY"])
FOLDER_ID = os.environ.get("SURFACEDOCS_FOLDER_ID")

def publish_on_complete(output):
    """Auto-publish task output to SurfaceDocs."""
    result = docs.save(output.raw, folder_id=FOLDER_ID)
    print(f"📄 Published: {result.url}")

research_task = Task(
    description="Research AI agent frameworks and write a report. "
                "Structure your output with clear headings and sections.",
    expected_output="A well-structured research report.",
    agent=researcher,
    callback=publish_on_complete,  # Auto-publish when task completes
)

No publisher agent needed. The callback fires when the task finishes, saves the output, and you have your URL. This is the simpler pattern when you don't need a dedicated formatting step.

Advanced Patterns

Multiple Documents Per Crew

Real crews produce multiple deliverables. A due diligence crew might generate a research report and a risk assessment and an executive summary. Each task can publish its own document:

def make_publisher(doc_type: str):
    def callback(output):
        result = docs.save(output.raw, folder_id=FOLDER_ID)
        print(f"📄 {doc_type}: {result.url}")
    return callback

research_task = Task(
    description="Deep-dive research on the target company.",
    agent=researcher,
    callback=make_publisher("Research Report"),
)

risk_task = Task(
    description="Identify and assess key risks based on the research.",
    agent=analyst,
    callback=make_publisher("Risk Assessment"),
)

summary_task = Task(
    description="Write an executive summary of findings and risks.",
    agent=writer,
    callback=make_publisher("Executive Summary"),
)

Three tasks, three published documents, three shareable URLs. Each lands in the same folder for easy organization.

Organizing by Project

SurfaceDocs folders map naturally to projects or clients. Create a folder per engagement, pass the folder ID, and every crew run for that project is automatically organized:

PROJECT_FOLDERS = {
    "acme-corp": "folder_abc123",
    "globex": "folder_def456",
    "initech": "folder_ghi789",
}

def run_research_crew(project: str, topic: str):
    folder_id = PROJECT_FOLDERS[project]

    def publish(output):
        result = docs.save(output.raw, folder_id=folder_id)
        return result.url

    # ... crew setup with callback=publish ...
    crew.kickoff()

Your client deliverables are organized before anyone has to think about it.

Post-Kickoff Publishing

If you'd rather publish the crew's final output as one document instead of per-task, just handle it after kickoff():

crew = Crew(
    agents=[researcher, analyst, writer],
    tasks=[research_task, analysis_task, summary_task],
)

output = crew.kickoff()
result = docs.save(output.raw, folder_id=FOLDER_ID)
print(f"📄 Crew output: {result.url}")

Simple. The crew runs, you publish the final result, done.

What This Unlocks

The shift is small in code but significant in practice. Your agents stop producing text blobs and start producing deliverables — documents with URLs you can drop into a Slack thread, an email, or a client portal.

It also changes how you think about crew design. When the output has a destination, you design tasks around publishable artifacts. The research task becomes a report. The analysis task becomes a dashboard. The crew isn't just processing — it's producing.

pip install surfacedocs and give your crews somewhere to put their work.

SurfaceDocs + LangChain: Give Your Agents an Output Layer

SurfaceDocs — Tue, 03 Mar 2026 15:07:07 +0000

Your LangChain agent just spent 30 seconds orchestrating five tools, synthesizing three sources, and producing a solid competitive analysis. It printed to stdout. Now it's gone.

If you've built anything serious with LangChain agents, you've hit this wall. The generation is the easy part. The "where does the output live?" question is what eats your weekend.

The Output Problem

Every LangChain project eventually faces the same fork:

Console output — Fine for debugging. Useless for sharing with stakeholders.
Write to files — Now you need a file server, naming conventions, and a way to find things later.
Custom React app — Three days of work for a document viewer nobody asked for.
Dump to a database — Great, now build a frontend to read it.

None of these are the agent's job. The agent's job is generating output. But without a destination, you end up building bespoke infrastructure for every project. A research agent gets a different viewer than a report generator, which gets a different viewer than a summarization pipeline.

What you actually want is a publish() call that gives you back a URL. That's it.

The Simplest Integration

pip install langchain langchain-openai surfacedocs

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from surfacedocs import SurfaceDocs, DOCUMENT_SCHEMA, SYSTEM_PROMPT

llm = ChatOpenAI(model="gpt-4o")
docs = SurfaceDocs()  # reads SURFACEDOCS_API_KEY from env

prompt = ChatPromptTemplate.from_messages([
    ("system", SYSTEM_PROMPT),
    ("human", "Write a technical overview of WebSocket connection pooling strategies."),
])

chain = prompt | llm
response = chain.invoke({})

result = docs.save(response.content)
print(result.url)  # https://app.surfacedocs.dev/d/abc123

That's the whole thing. SYSTEM_PROMPT tells the LLM to structure its output in SurfaceDocs' block format. docs.save() parses the response and publishes it. You get a URL back.

The key insight: SurfaceDocs ships a SYSTEM_PROMPT and DOCUMENT_SCHEMA that teach the LLM how to format output as structured blocks (headings, paragraphs, code, tables, lists). The LLM does the formatting. The SDK does the publishing. You write neither.

Building a Research Agent

A real agent does more than call an LLM once. Here's a research agent that searches the web, synthesizes findings, and publishes a shareable report:

from langchain_openai import ChatOpenAI
from langchain_community.tools import TavilySearchResults
from langchain_core.messages import HumanMessage, SystemMessage
from langgraph.prebuilt import create_react_agent
from surfacedocs import SurfaceDocs, SYSTEM_PROMPT

# Tools
search = TavilySearchResults(max_results=5)

# Agent
llm = ChatOpenAI(model="gpt-4o", temperature=0.2)
agent = create_react_agent(llm, [search])

# Run the research task
research_prompt = """Research the current state of WebAssembly adoption in server-side 
applications. Cover: major runtimes, production use cases, performance characteristics, 
and limitations. Be thorough — this will be published as a report."""

result = agent.invoke({
    "messages": [
        SystemMessage(content=f"""You are a senior technical researcher. 
When producing your final report, format it using these instructions:

{SYSTEM_PROMPT}

Use heading blocks for sections, code blocks for examples, 
and paragraph blocks for analysis."""),
        HumanMessage(content=research_prompt),
    ]
})

# Extract the final message content
final_message = result["messages"][-1].content

# Publish
docs = SurfaceDocs()
doc = docs.save(final_message)
print(f"Published: {doc.url}")

The agent searches the web, reads results, reasons about them, and produces a structured report. The last two lines publish it. Your stakeholder gets a link, not a terminal screenshot.

For richer metadata tracking (model, agent name, run ID), use save_raw() instead — it accepts a metadata dict alongside explicit title and blocks. Useful when you're running multiple agents and need to trace which one produced what.

The Custom Tool Approach

The examples above publish after the agent finishes. But sometimes you want the agent itself to decide when to publish — maybe it produces intermediate artifacts, or it needs to publish different documents for different sub-tasks.

Make SurfaceDocs a LangChain tool:

from langchain_core.tools import tool
from surfacedocs import SurfaceDocs

docs = SurfaceDocs()

@tool
def publish_document(
    title: str,
    content: str,
    doc_type: str = "report",
) -> str:
    """Publish a document to SurfaceDocs and return the shareable URL.

    Use this when you've completed a piece of analysis, report, or research
    that should be saved as a permanent, shareable document.

    Args:
        title: Document title.
        content: Full document content in markdown.
        doc_type: Type of document (report, analysis, summary, research).

    Returns:
        The shareable URL for the published document.
    """
    result = docs.save_raw(
        title=title,
        blocks=[
            {"type": "heading", "content": title, "metadata": {"level": 1}},
            {"type": "paragraph", "content": content},
        ],
        metadata={"type": doc_type, "source": "langchain-agent"},
    )
    return f"Published: {result.url}"

For richer documents, parse the markdown into proper blocks:

@tool
def publish_structured_document(
    title: str,
    sections: list[dict],
    doc_type: str = "report",
) -> str:
    """Publish a structured document with multiple sections to SurfaceDocs.

    Args:
        title: Document title.
        sections: List of dicts with 'heading' and 'content' keys.
        doc_type: Type of document.

    Returns:
        The shareable URL for the published document.
    """
    blocks = [{"type": "heading", "content": title, "metadata": {"level": 1}}]

    for section in sections:
        blocks.append({"type": "heading", "content": section["heading"], "metadata": {"level": 2}})
        blocks.append({"type": "paragraph", "content": section["content"]})

    result = docs.save_raw(
        title=title,
        blocks=blocks,
        metadata={"type": doc_type, "source": "langchain-agent"},
    )
    return f"Published: {result.url}"

Now wire it into an agent:

from langchain_openai import ChatOpenAI
from langchain_community.tools import TavilySearchResults
from langgraph.prebuilt import create_react_agent

llm = ChatOpenAI(model="gpt-4o")
tools = [TavilySearchResults(max_results=5), publish_structured_document]
agent = create_react_agent(llm, tools)

result = agent.invoke({
    "messages": [
        HumanMessage(content="""Research the top 3 Python web frameworks in 2025. 
        For each, analyze performance, ecosystem, and developer experience. 
        Publish your findings as a structured report.""")
    ]
})

The agent researches, then calls publish_structured_document on its own when it's ready. The tool description guides when it gets used — write it clearly and the agent makes good decisions about publishing timing.

This pattern scales well. You can have agents that publish multiple documents per run, organize them into folders, and build up a library of artifacts over time.

What You Get

Once output is published, you're working with hosted documents instead of terminal output:

Shareable URLs — Every document gets a permanent link. Send it in Slack, embed it in a ticket, share it with a client. No "let me copy-paste this for you."
Folder organization — Pass a folder_id to save() or save_raw() to group related documents. Research reports in one folder, weekly summaries in another.
Metadata tracking — Tag documents with model, agent, pipeline, run ID, whatever you need. Useful when you're debugging why Tuesday's report looks different from Monday's.
Structured blocks — Documents aren't just markdown blobs. They're structured: headings, code blocks with syntax highlighting, tables, Mermaid diagrams. The rendering is handled for you.
Zero infrastructure — No S3 buckets, no static site generators, no React apps. The output layer is managed.

The block format also means your documents render consistently. Code blocks get syntax highlighting. Tables are actual tables. Mermaid diagrams render as diagrams. You're not fighting with markdown rendering quirks in whatever viewer you duct-taped together.

Wrapping Up

The pattern is simple: LangChain agents generate, SurfaceDocs publishes. Whether you publish after the agent runs or give the agent a tool to publish itself depends on your use case — both work, and the code is minimal either way.

Check out the SurfaceDocs docs to get an API key and start publishing. The Python SDK is pip install surfacedocs and you're about three lines of code from your first published agent output.

The Missing Layer in Every AI Pipeline

SurfaceDocs — Fri, 27 Feb 2026 18:51:49 +0000

You built the pipeline. The model works. The output is good — surprisingly good, actually. You paste it into Slack to show your team.

Then someone asks: "Cool, but where do users see this?"

And you realize you have no idea.

The Duct-Tape Gallery

If you've built anything with LLMs, you've done at least one of these:

print(response.choices[0].message.content) and called it a day
Written output to a local markdown file that only you can access
Built a "quick" React app that took three weeks and still doesn't handle tables
Piped structured output into a Google Doc via a script that breaks every time Google changes their API
Dumped JSON into Notion through an integration that rate-limits you after 3 requests
Stored everything in S3 and built a viewer on top because apparently that's your job now

Here's the thing — every single one of these is a document rendering and hosting problem disguised as an application feature. You're not building output infrastructure because you want to. You're building it because nothing exists.

Meanwhile, your actual pipeline looks like this:

# The part you spent weeks on
response = openai.chat.completions.create(
    model="gpt-4o",
    messages=messages,
    response_format=schema,
)

# The part you spent months on
output = response.choices[0].message.content
# ... now what?

That # ... now what? comment is doing a lot of heavy lifting in production codebases.

This Is an Architecture Problem

Think about any well-designed system. There's always a three-layer pattern:

Input → Processing → Output

In web apps: HTTP requests → business logic → rendered HTML. In data engineering: sources → transformations → warehouses and dashboards. In CI/CD: commits → build/test → artifacts and deployments.

Now look at a typical AI pipeline:

Input (APIs, databases, user prompts) → Processing (LLMs, agents, chains, RAG) → Output (???)

The output layer is conspicuously absent. Not under-invested — absent. Pull up any AI architecture diagram on the internet. You'll see boxes for vector databases, embedding models, orchestration frameworks, prompt management, evaluation suites, guardrails, observability. The arrow at the end just says "response" and points at nothing.

We've built an entire ecosystem around getting data into models and making models smarter. The ecosystem for getting structured output out of models and into the hands of users essentially doesn't exist.

This isn't a convenience problem. It's a missing architectural layer.

What an Output Layer Actually Requires

Once you frame it as infrastructure, the requirements become obvious:

API-first. Machines are generating this content, not humans. The primary interface needs to be a programmatic one. If the first step is "open a browser," you've already failed.

Structured content handling. LLM output isn't plain text. It's headings, code blocks, tables, lists, diagrams. The output layer needs to understand document structure natively, not treat everything as a string.

Instant shareability. The output needs a URL the moment it's created. No deploy step, no build process, no "publish" button. Generated → shareable, in one call.

Zero infrastructure. If I have to provision a server, set up a database, or configure a CDN to display AI-generated content, I'm solving the wrong problem. The output layer should be as invisible as the logging layer.

Built for machine-generated volume. Humans write a few documents a day. AI agents can generate hundreds per hour. The output layer needs to handle this without rate limits designed for human typing speed.

None of these requirements are exotic. They're just... not met by anything that currently exists in the AI toolchain.

The Output Layer, Concretely

This is why we built SurfaceDocs — as the output layer for AI pipelines. Not a document editor. Not a collaboration tool. Infrastructure. A place machines publish, not where humans type.

The core integration is three lines:

from surfacedocs import SurfaceDocs, DOCUMENT_SCHEMA, SYSTEM_PROMPT

docs = SurfaceDocs(api_key="sd_live_...")
result = docs.save(llm_output)
print(result.url)  # https://app.surfacedocs.dev/d/abc123

The SDK exports two things that make integration with any LLM trivial: DOCUMENT_SCHEMA (a JSON schema that tells the model how to structure its output) and SYSTEM_PROMPT (instructions that guide the model to generate well-structured documents). You wire these into whatever LLM you're already using.

With OpenAI

from surfacedocs import SurfaceDocs, DOCUMENT_SCHEMA, SYSTEM_PROMPT
from openai import OpenAI

openai = OpenAI()
docs = SurfaceDocs()

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": SYSTEM_PROMPT},
        {"role": "user", "content": "Write documentation for user authentication"},
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {"name": "document", "schema": DOCUMENT_SCHEMA},
    },
)

result = docs.save(response.choices[0].message.content)
print(f"Saved: {result.url}")

With Anthropic

from surfacedocs import SurfaceDocs, DOCUMENT_SCHEMA, SYSTEM_PROMPT
import anthropic

client = anthropic.Anthropic()
docs = SurfaceDocs()

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=4096,
    system=SYSTEM_PROMPT,
    messages=[{"role": "user", "content": "Write documentation for user authentication"}],
    tools=[{
        "name": "create_document",
        "description": "Create a structured document",
        "input_schema": DOCUMENT_SCHEMA,
    }],
    tool_choice={"type": "tool", "name": "create_document"},
)

tool_use = next(b for b in response.content if b.type == "tool_use")
result = docs.save(tool_use.input)
print(f"Saved: {result.url}")

With Gemini

from surfacedocs import SurfaceDocs, DOCUMENT_SCHEMA, SYSTEM_PROMPT
import google.generativeai as genai

genai.configure(api_key="...")
docs = SurfaceDocs()

model = genai.GenerativeModel(
    model_name="gemini-2.0-flash",
    system_instruction=SYSTEM_PROMPT,
    generation_config=genai.GenerationConfig(
        response_mime_type="application/json",
        response_schema=DOCUMENT_SCHEMA,
    ),
)

response = model.generate_content("Write documentation for user authentication")
result = docs.save(response.text)
print(f"Saved: {result.url}")

Same pattern every time: give the model the schema, get structured output back, save it, get a URL. The document supports headings, paragraphs, code blocks, lists, quotes, tables, images, dividers, Mermaid diagrams, and even Slidev presentations. Inline markdown just works.

Think of it as S3 for AI documents, but with a built-in viewer. You don't build a viewer for files stored in S3 from scratch every time — and you shouldn't have to build one for AI-generated documents either.

This Will Become Standard

Logging wasn't always standard infrastructure. There was a time when every team rolled their own log files, their own rotation scripts, their own search tools. Then centralized logging became a thing and nobody went back.

Monitoring followed the same arc. Error tracking. Feature flags. Auth. Each started as something teams built custom, then crystallized into dedicated infrastructure that everyone just uses.

The output layer for AI is at the beginning of that same curve. Right now, every team is building their own duct-tape solution. Custom React apps, Notion integrations, Google Docs hacks. It works, barely, and it's a massive distraction from the actual product.

The teams that adopt a real output layer early will have cleaner architectures, faster iteration, and fewer Sunday nights spent debugging why their document rendering broke after a dependency update.

The pipeline doesn't end at the model. It ends where the user sees the result. Build accordingly.

SurfaceDocs Now Has Versioning, Search, and Real Docs

SurfaceDocs — Sun, 15 Feb 2026 17:38:24 +0000

SurfaceDocs Now Has Versioning, Search, and Real Docs

SurfaceDocs is the output layer for AI pipelines. Your agents generate documents — reports, summaries, analyses — and SurfaceDocs gives them instant shareable URLs via a Python SDK or REST API. No storage config, no hosting, no frontend work.

We just shipped three features that make it actually useful at scale: document versioning, search, and a proper documentation site.

Here's what landed.

Document Versioning

Every document is now versioned. When your AI agent iterates on a report — refining analysis, incorporating feedback, reprocessing with new data — you get a full version history instead of overwriting the previous output.

from surfacedocs import SurfaceDocsClient

client = SurfaceDocsClient(api_key="sd_live_...")

# Push a new version of an existing document
client.push_version(
    document_id="doc_abc123",
    content="# Q4 Report v3\n\nUpdated with final revenue numbers..."
)

# See what versions exist
versions = client.list_versions(document_id="doc_abc123")
# Returns version history with timestamps and metadata

# Grab a specific version
v2 = client.get_version(document_id="doc_abc123", version=2)

# Roll back if the latest version is wrong
client.restore_version(document_id="doc_abc123", version=2)

Every document now tracks current_version and version_count. There's also push_version_raw() for when you're working with HTML or plain text instead of markdown.

Why this matters: AI agents don't get things right on the first pass. They iterate. A research agent might refine a report five times as new sources come in. A documentation agent might rebuild API docs after every deploy. Without versioning, you're either overwriting history or creating a mess of duplicate documents. Now you get both — a clean URL that always shows the latest, and a full history of how it got there.

Document Search

Once you have hundreds of documents across multiple pipelines, you need to find things. Now you can.

# Search by title prefix (case-insensitive)
results = client.search_documents(query="Q4 Report")

# Filter by tag
results = client.search_documents(tag="financial-analysis")

# Combine filters, scope to a folder, paginate
results = client.search_documents(
    query="weekly",
    tag="metrics",
    folder_id="folder_xyz",
    limit=20,
    offset=0
)

The REST API equivalent:

curl -H "Authorization: Bearer sd_live_..." \
  "https://api.surfacedocs.dev/v1/documents/search?query=Q4&tag=metrics&limit=10"

Search works on title prefix (case-insensitive) and tags. You can filter by folder and paginate with limit/offset. Requires the documents:read API key role.

Why this matters: If you're running multiple AI pipelines — one for customer reports, one for internal docs, one for monitoring summaries — you need a way to find documents without tracking every ID yourself. Tag your documents by pipeline, search by prefix, filter by folder. Your orchestration layer can now query SurfaceDocs like a lightweight document store.

New Documentation Site

We rebuilt the docs from scratch: docs.surfacedocs.dev

Python SDK — every method with copy-paste examples
REST API reference — full endpoint documentation
LLM provider guides — dedicated walkthroughs for OpenAI, Gemini, Anthropic, and a generic guide for any LLM
Document schema — what a document object looks like, all fields explained
Pricing — no surprises

Every method in the SDK has a corresponding docs page with working examples. If you're integrating SurfaceDocs into an agent framework, the LLM provider guides show exactly how to wire it up.

The Bigger Picture

These three features solve the same underlying problem: AI agents need infrastructure for their output.

We've spent years building infrastructure for AI input — vector databases, embedding pipelines, RAG systems. But what about the other direction? When your agent produces a 10-page analysis, where does it go? A JSON blob in a database? A file on S3 that nobody can find?

SurfaceDocs treats AI-generated documents as first-class artifacts. Versioned, searchable, instantly shareable. Your agent pushes content, gets a URL, and moves on. The human reviews it when they're ready.

With versioning, your agent can iterate without losing history. With search, your orchestration layer can find documents across pipelines. With proper docs, you can actually integrate all of this without reading source code.

Get Started

pip install surfacedocs

from surfacedocs import SurfaceDocsClient

client = SurfaceDocsClient(api_key="sd_live_...")
doc = client.create_document(
    title="My First Document",
    content="# Hello World",
    tags=["test"]
)
print(doc.url)  # Instant shareable URL

📖 Docs: docs.surfacedocs.dev
🚀 App: app.surfacedocs.dev
🌐 Website: surfacedocs.dev

If you're building AI agents that produce documents, reports, or any text output — give SurfaceDocs a look. It's the plumbing you don't want to build yourself.

The SurfaceDocs SDK Just Went From Write-Only to Full CRUD

SurfaceDocs — Sat, 14 Feb 2026 23:15:45 +0000

When we first shipped the SurfaceDocs Python SDK, it did one thing: take your LLM output and give you a URL. docs.save(content) — done.

That was intentional. The output layer for AI pipelines should be dead simple. But as people started building real workflows on top of it, the requests were predictable: "Can I read documents back?" "Can I organize things into folders?" "Can I clean up old runs?"

Fair. Here's what's new.

Read Documents

The SDK can now fetch documents back by ID:

from surfacedocs import SurfaceDocs

docs = SurfaceDocs()

doc = docs.get_document("doc_abc123")
print(doc.title)              # "Q4 Analysis"
print(doc.blocks[0].type)     # "heading"
print(doc.blocks[0].content)  # "Executive Summary"
print(doc.visibility)         # "private"

You get the full document — title, blocks, metadata, timestamps, visibility status. Every block has its type, content, and metadata.

Why this matters: Your agent can now read its own previous output. Run a daily analysis pipeline, then have tomorrow's run pull yesterday's document for comparison. Build context over time instead of starting from scratch.

Create and List Folders

Organize programmatically instead of through the UI:

# Create a folder structure
reports = docs.create_folder("Research Reports")
q1 = docs.create_folder("Q1 2026", parent_id=reports.id)

# Save directly to a subfolder
result = docs.save(analysis_output, folder_id=q1.id)

# See what's where
folders = docs.list_folders()
subfolders = docs.list_folders(parent_id=reports.id)

Why this matters: Pipelines that run on schedules can auto-organize. Daily reports go into date-based folders. Per-client analyses go into client folders. Your agent builds a clean library instead of dumping everything into one pile.

Delete Documents

docs.delete_document("doc_abc123")

Simple. Why this matters: Cleanup scripts. Your pipeline generates 30 drafts before producing a final version — now you can programmatically delete the drafts. Retention policies become code, not manual housekeeping.

Editable Titles in the Viewer

Not an SDK change, but a quality-of-life update: document titles are now editable directly in the viewer. Click the title, type, done. No more "Untitled Document" shame.

What This Enables

The SDK went from "fire and forget" to "manage your document lifecycle." A few patterns that are now possible:

Self-referencing agents:

# Agent reads yesterday's report for context
yesterday = docs.get_document(last_report_id)
context = "\n".join(b.content for b in yesterday.blocks)

# Generate today's with awareness of what came before
response = llm.generate(f"Update this analysis with today's data:\n{context}")
result = docs.save(response, folder_id=daily_folder.id)

Automated folder management:

import datetime

# Create today's folder
today = datetime.date.today().isoformat()
folder = docs.create_folder(today, parent_id=archive.id)

# Route all pipeline output there
for report in pipeline.run():
    docs.save(report, folder_id=folder.id)

Cleanup scripts:

# Delete documents older than 30 days from a working folder
for doc_id in get_old_document_ids(days=30):
    docs.delete_document(doc_id)

Get It

pip install --upgrade surfacedocs

Everything is backward compatible. Your existing docs.save() calls don't change. You just have more tools now.

app.surfacedocs.dev →

SurfaceDocs is the output layer for AI pipelines. Now with read, write, organize, and delete — so your AI output actually has a lifecycle.

SurfaceDocs + Gemini: From LLM Output to Shareable Doc in 30 Seconds

SurfaceDocs — Sat, 14 Feb 2026 21:04:05 +0000

You just built a Gemini pipeline. It generates great output — structured analysis, technical breakdowns, research summaries. Now you need to share it with someone who doesn't have a terminal open.

Your options: copy-paste into Google Docs (fight with formatting), save to a file and Slack it (watch it disappear in 20 minutes), or build a custom viewer (spend a week on something that isn't your actual project).

Or: three lines of code.

The Setup

pip install google-genai surfacedocs

You'll need two API keys:

Google AI API key from aistudio.google.com
SurfaceDocs API key from app.surfacedocs.dev (free tier, no credit card)

The Minimal Example

import os
from google import genai
from surfacedocs import SurfaceDocs, SYSTEM_PROMPT, GEMINI_DOCUMENT_SCHEMA

# Initialize clients
client = genai.Client(api_key=os.environ["GOOGLE_API_KEY"])
docs = SurfaceDocs(api_key=os.environ["SURFACEDOCS_API_KEY"])

# Generate structured content with Gemini
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="Write a technical overview of WebSocket protocol vs HTTP polling",
    config={
        "system_instruction": SYSTEM_PROMPT,
        "response_mime_type": "application/json",
        "response_schema": GEMINI_DOCUMENT_SCHEMA,
    },
)

# Publish to SurfaceDocs
result = docs.save(response.text)
print(result.url)  # https://app.surfacedocs.dev/d/...

That's it. Gemini generates structured content, SurfaceDocs renders and hosts it. Click the URL and you've got a formatted, shareable document.

What's happening under the hood

The key is three things the SurfaceDocs SDK provides:

SYSTEM_PROMPT — Instructions that tell Gemini how to structure its output into document blocks (headings, paragraphs, code blocks, tables, lists)
GEMINI_DOCUMENT_SCHEMA — A JSON schema specifically shaped for Gemini's response_schema parameter, so output is guaranteed to be valid structured JSON
docs.save() — Takes that JSON, pushes it to SurfaceDocs, returns a URL

The SDK ships with both GEMINI_DOCUMENT_SCHEMA (for Gemini's native structured output) and OPENAI_DOCUMENT_SCHEMA (for OpenAI's response_format). Same idea, different shapes for each provider's API.

A More Realistic Example: Multi-Step Pipeline

In practice, you probably have a pipeline that does real work — not just a single generation call. Here's a two-step pattern: generate raw analysis, then format it as a publishable document.

import os
from google import genai
from surfacedocs import SurfaceDocs, SYSTEM_PROMPT, GEMINI_DOCUMENT_SCHEMA

client = genai.Client(api_key=os.environ["GOOGLE_API_KEY"])
docs = SurfaceDocs(api_key=os.environ["SURFACEDOCS_API_KEY"])

# Step 1: Generate raw analysis (unstructured)
raw = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=(
        "Compare FastAPI, Flask, and Django for building REST APIs in 2026. "
        "Cover performance, developer experience, ecosystem, and when to pick each."
    ),
)

print(f"Generated {len(raw.text)} chars of analysis")

# Step 2: Format as a SurfaceDocs document
formatted = client.models.generate_content(
    model="gemini-2.5-flash",
    contents=f"Turn this analysis into a well-structured document:\n\n{raw.text}",
    config={
        "system_instruction": SYSTEM_PROMPT,
        "response_mime_type": "application/json",
        "response_schema": GEMINI_DOCUMENT_SCHEMA,
    },
)

# Step 3: Publish
result = docs.save(formatted.text)
print(f"Published → {result.url}")

Why two steps? Your first call does the actual thinking — analysis, comparison, research. It can be freeform, messy, detailed. The second call just reshapes that output into SurfaceDocs' block format. You get the best of both worlds: unconstrained reasoning followed by clean formatting.

This also means you can plug SurfaceDocs into any existing pipeline. Whatever your agent or chain produces, just add a formatting step at the end and save it.

Organizing with Folders

As your pipeline generates more documents, you'll want to organize them. Pass a folder_id to route documents into specific folders:

# Publish to a specific folder
result = docs.save(
    formatted.text,
    folder_id="your-folder-id"
)

Create folders in the SurfaceDocs dashboard and grab the ID from the URL. Useful for pipelines that produce daily reports, per-client analyses, or categorized research.

When This Clicks

This pattern works best when:

Your pipeline runs on a schedule — Daily market analysis, weekly reports, automated monitoring summaries. Each run produces a document with a permanent URL.
You're sharing with non-technical stakeholders — Your PM, your client, your CEO doesn't want to cat output.json. They want a link.
Your agent produces work products — Research agents, analysis agents, documentation generators. The agent does work, and that work needs to live somewhere.
You're prototyping fast — You're iterating on a Gemini pipeline and want to see formatted output without building a viewer. SurfaceDocs becomes your instant preview layer.

The Full Pattern

Here's the general flow for any Gemini pipeline:

Your pipeline (any logic)
        │
        ▼
Raw LLM output (unstructured)
        │
        ▼
Gemini + SYSTEM_PROMPT + GEMINI_DOCUMENT_SCHEMA
        │
        ▼
docs.save() → Shareable URL

The structured output step can go anywhere — at the end of a chain, after post-processing, or directly as your only generation call. SurfaceDocs doesn't care what your pipeline does upstream. It's just the output layer.

Get Started

pip install google-genai surfacedocs

Free tier gives you 10 documents/month with 90-day retention — plenty to try it out. Pro ($19/month) bumps that to 1,000 docs with unlimited retention when your pipeline goes to production.

The full code examples from this article are on GitHub.

SurfaceDocs is the output layer for AI pipelines. pip install surfacedocs and stop building custom viewers.

Your AI Pipeline Deserves Better Than `print()`

SurfaceDocs — Sat, 14 Feb 2026 20:39:34 +0000

You know the moment. You've spent three days wiring up an LLM pipeline. The prompt engineering is dialed. The retrieval is fast. The output is genuinely good — structured analysis, beautiful reports, actionable summaries. Your model is producing real work product.

And then you hit the last mile.

print(result)

That's it. That's the output layer. A wall of text in your terminal. Maybe you get fancy and write it to a file:

with open(f"output_{datetime.now().isoformat()}.md", "w") as f:
    f.write(result)

Now you've got 47 markdown files in a folder called outputs/ and your PM is asking "can you just send me a link?"

We've all been here. And somehow, despite the billions flowing into AI infrastructure, the last mile of AI output is still held together with duct tape.

The Duct Tape Taxonomy

I've seen teams solve this problem in increasingly creative (desperate) ways:

The Console Cowboy: Output goes to stdout. Screenshots get pasted into Slack. Nobody can find anything after 48 hours. "Can you re-run that analysis from last Tuesday?" becomes a recurring nightmare.

The Local File Hoarder: A growing graveyard of report_final_v2_FINAL.json files. Maybe there's a naming convention. Maybe there was, once. Now it's chaos and everyone knows it.

The Custom React App: Someone on the team spent two weeks building a viewer. It works! Until it doesn't. Now you're maintaining a React app, a database, auth, hosting — all to display LLM output. The viewer becomes its own product with its own bugs, and suddenly your AI engineer is debugging CSS.

The Google Docs Hack: Pipe output to the Google Docs API. Pray the formatting survives. Share links manually. Lose all structure in the process. Watch your carefully structured JSON become a wall of unstyled text.

The Notion/Confluence Dump: Similar energy. Different API. Same sadness.

Every one of these solutions shares the same fundamental problem: you're building infrastructure to display output instead of building the thing that generates the output. The presentation layer becomes a project unto itself, and it's never anyone's priority.

Three Lines of Code

Here's what the last mile should look like:

from surfacedocs import SurfaceDocs, DOCUMENT_SCHEMA, SYSTEM_PROMPT

docs = SurfaceDocs()
result = docs.save(llm_output)
print(result.url)  # https://app.surfacedocs.dev/d/abc123

That's SurfaceDocs. pip install surfacedocs. Three lines. Instant shareable URL. Zero infrastructure.

Your LLM output gets a permanent, rendered, shareable document — not a file, not a screenshot, not a Slack message that disappears into the void. A URL you can hand to anyone.

But here's the part that makes this actually good instead of just convenient. The SDK ships with a SYSTEM_PROMPT and DOCUMENT_SCHEMA that you pass directly to your LLM:

from openai import OpenAI
from surfacedocs import SurfaceDocs, DOCUMENT_SCHEMA, SYSTEM_PROMPT

client = OpenAI()
docs = SurfaceDocs()

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "system", "content": SYSTEM_PROMPT},
        {"role": "user", "content": "Analyze Q4 sales data and produce an executive summary"}
    ],
    response_format=DOCUMENT_SCHEMA
)

result = docs.save(response.choices[0].message.content)
print(result.url)

The LLM outputs structured content that SurfaceDocs knows how to render beautifully. Headers, tables, callouts, metrics — all formatted and interactive in the viewer. Works with OpenAI, Anthropic, Gemini, Ollama, whatever. If it can follow a schema, it works.

No React app. No database. No CSS. No hosting. You build the pipeline, SurfaceDocs handles the output.

Introducing SurfaceDocs Pro

Since launching SurfaceDocs, people have started building things we didn't expect.

Someone wired it into a daily market analysis agent that publishes a new document every morning. A team is using it as the output layer for their customer support summarization pipeline — hundreds of documents a day. Another developer built an autonomous research agent that publishes its findings as it goes, creating a living paper trail of AI-generated analysis.

The free tier — 10 documents a month, 90-day retention — is enough to kick the tires and build a prototype. But these teams were bumping into limits fast. They needed this to be production infrastructure, not a toy.

That's why we're introducing SurfaceDocs Pro at $19/month. Here's what you get, and more importantly, why each piece matters:

1,000 Documents/Month

Ten documents is a demo. A thousand documents is a pipeline. This is the difference between "I tried it once" and "this runs in production every day." If your agent produces a report per customer, per analysis, per run — you need headroom. A thousand documents means you can build real workflows without counting.

300 req/min, 50,000 req/day

The free tier rate limits are fine for development. But when your pipeline gets triggered by webhooks, runs on a schedule, or handles concurrent users — you need burst capacity. 300 requests per minute means your batch jobs don't get throttled. 50K daily requests means your production traffic has room to breathe.

Unlimited Document Retention

This is the big one. On free, your documents expire after 90 days. For a demo, that's fine. For an audit trail? For compliance? For a knowledge base that compounds over time? You need documents that stick around. Pro documents live forever. Your AI-generated analysis from January is still there in December. Build a library, not a buffer.

Document-Level Sharing

All documents are private by default — on both tiers you can make individual documents public with a shareable link. But Pro unlocks sharing between users: grant specific people access to specific documents without making anything public. When your pipeline handles customer data, internal metrics, or anything sensitive, you need that granularity.

The Bigger Picture

Here's what I think is actually happening, and why we're building this:

The agentic era needs an output layer.

Right now, AI agents are getting really good at doing work. They can research, analyze, summarize, generate, review. But every agent framework — LangChain, CrewAI, AutoGen, your custom thing — has the same blind spot: what happens to the output?

Agents produce work products. Reports, analyses, summaries, recommendations, code reviews, data breakdowns. Today those work products evaporate into logs or get wedged into formats that weren't designed for them.

Think about where this is going. In six months, you'll have agents running autonomously, producing dozens of documents a day. Research agents publishing findings. Monitoring agents generating incident reports. Sales agents creating customer briefs. Each of these needs a place to land — somewhere structured, shareable, persistent, and accessible to both humans and other agents.

SurfaceDocs is that place. The output layer for AI pipelines.

We're not building a document editor. We're not competing with Notion or Google Docs. We're building the place where AI work products live. The read layer for what AI writes.

# This is the future: agents that publish their work
agent = ResearchAgent(topic="competitor analysis")
findings = agent.run()

docs = SurfaceDocs()
result = docs.save(findings)

# Share with the team, feed to other agents, build a knowledge base
notify_team(result.url)
knowledge_base.index(result.url)

The architecture is intentionally simple: Python SDK → FastAPI on Cloud Run → Firestore → React viewer. We're not over-engineering this. Fast ingress, reliable storage, clean rendering. The complexity belongs in your pipeline, not in the output layer.

Get Started

The free tier is still there. Ten documents a month, 90-day retention, private by default with public sharing. Enough to build something real and see if it clicks.

When your prototype becomes a pipeline and your pipeline becomes production — that's when Pro makes sense. $19/month for the headroom, the retention, and the access control that serious projects need.

pip install surfacedocs

from surfacedocs import SurfaceDocs, DOCUMENT_SCHEMA, SYSTEM_PROMPT

docs = SurfaceDocs()
result = docs.save(your_llm_output)
print(result.url)  # That's it. That's the output layer.

Start free at app.surfacedocs.dev →

SurfaceDocs is the output layer for AI pipelines. We're building the place where AI work products live — so you can focus on building the AI that creates them.