Documents

Documents are the outputs created by your agents and actions. They're the reports, summaries, analyses, and insights that your automated workflows generate for you.

What are Documents?

Documents are formatted content created by actions when they run. Each document contains structured information (reports, summaries, analyses), uses markdown formatting, can include visualizations (charts and graphs), has an automatic summary, and is linked to its source action and agent.

How Documents are Created

Documents are created by actions using the app.doc() function. When an action runs, it calls app.doc() with markdown content. The markdown is automatically formatted and stored as a document. Each document gets an automatic summary generated from its content.

def run(app):
    markdown = """
# Weekly Sales Report
- Total sales: $50,000
- New customers: 25
"""
    app.doc(markdown)

Viewing Documents

You can access documents from action pages (list of documents organized by date), log pages (links to documents created during that run), or the document list (browse all documents filtered by agent or action).

Document Features

Documents support standard markdown formatting: headings, lists, emphasis, links, tables, and code blocks. They can also include interactive charts using fenced code blocks with the language set to chart. Chart content must be compact JSON (single line) containing an array of dataset objects.

Each dataset object must have: type ("line" or "bar"), name (series name), color (optional hex color), and data (array of data points with x and y values). The x value can be an ISO date (YYYY-MM-DD), week (YYYY-Www), month (YYYY-MM), year (YYYY), or category string.

chart_json = '[{"type":"line","name":"Sales","color":"#3B82F6","data":[{"x":"2025-01-01","y":120}]}]'
markdown = f"""
# Sales Report
\`\`\`chart
{chart_json}
\`\`\`
"""
app.doc(markdown)

Bar charts automatically stack when x values overlap. Line charts never stack. Multiple series can be combined in a single chart.

Automatic Summaries

Every document automatically gets a summary that provides a brief overview, helps you quickly understand what the document contains, and makes it easier to scan through multiple documents. Summaries are generated automatically—you don't need to create them manually.

Document Organization

Documents are organized by agent, action, date, and workspace. This makes it easy to find documents related to specific agents or actions.

Common Document Types

Regular Reports: Daily, weekly, or monthly reports that keep you informed about metrics and trends.

Data Analysis: Analyses of data from various sources helping you understand patterns.

Summaries and Insights: Summaries of large amounts of information extracting key points.

Best Practices

Use clear headings to organize content. Let the automatic summary help, but structure your content clearly. Add charts to visualize data when it helps understanding. Keep it scannable using lists, tables, and formatting. Review documents from your active agents regularly.

Document Lifecycle

An action creates a document when it calls app.doc(). The document is stored and associated with the action and agent. An automatic summary is generated. You can view the document at any time. If an action runs again, it creates new documents (doesn't update existing ones).

Next Steps

Now that you understand documents, view recent documents, review action outputs, learn about actions, and set up document-generating actions.

Documents are how your agents communicate their findings and insights to you. They transform raw data and automated processes into readable, actionable information.