Autonomous AI Document Agent

An asynchronous multi-agent system built with FastAPI and OpenAI Agents SDK to autonomously generate, refine, validate, and render professional Microsoft Word (.docx) documents from natural language prompts.

---

Key Features

• Asynchronous Job Pipeline: Non-blocking API accepting natural language document generation requests, returning an async job identifier for polling and progress tracking.
• Multi-Agent Co-Authoring Architecture:
  • ImplementationAgent: Master orchestrator controlling execution pipeline steps.
  • DocCoAuthorAgent: Specialist drafting multi-stage structured markdown specifications.
  • AnswererAgent: Domain expert/stakeholder simulator answering clarifying questions during multi-turn drafting.
• Dynamic Context Enrichment: Integrates real-time web search via DuckDuckGo (ddgs) for fetching relevant domain knowledge.
• Automated Document Validation: Guardrails scoring markdown content quality, structural completeness, headings, and table presence.
• Professional .docx Engine: Converts raw Markdown into polished Word documents complete with custom headers/footers, callout boxes, colored table headers, and alternating row shading.
• Direct File Downloads: REST endpoint to download completed Word documents.

---

Architecture & System Overview

graph TD
    Client[Client / REST Consumer] -->|POST /agent| API[FastAPI Server]
    API -->|Create Job| JM[JobManager]
    API -->|Spawn Worker| Worker[Async Pipeline Worker]
    Worker -->|Execute| IA[ImplementationAgent]

    subgraph Agentic Pipeline
        IA -->|1. Plan| TP[generate_task_plan]
        IA -->|2. Co-author| Spec[draft_document_spec]
        IA -->|3. Search| Web[fetch_context_data]
        IA -->|4. Validate| Qual[validate_document_quality]
        IA -->|5. Render| Docx[render_docx_document]

        subgraph Multi-Turn Co-Authoring
            Spec -->|Draft / Question| CA[DocCoAuthorAgent]
            CA -->|Clarify| AA[AnswererAgent]
            AA -->|Refine| CA
        end

        Web -->|Query| DDG[DuckDuckGo Search]
    end

    Qual -->|Log Progress| JM
    Docx -->|Write File| Output[(output/*.docx)]
    Client -->|GET /agent/job/:id| API
    Client -->|GET /agent/job/:id/download| API

Loading

---

Execution Pipeline Flow

sequenceDiagram
    autonumber
    actor Client
    participant API as FastAPI (main.py)
    participant JM as JobManager
    participant IA as ImplementationAgent
    participant CA as DocCoAuthorAgent
    participant AA as AnswererAgent
    participant Formatter as docx_formatter

    Client->>API: POST /agent {"request": "Draft PRD..."}
    API->>JM: create_job(request)
    JM-->>API: Return Job (status: queued)
    API-->>Client: HTTP 202 Accepted {job_id}

    par Background Execution
        API->>IA: Runner.run(implementation_agent, job.request)
        IA->>JM: Step 1: TASK_PLANNING
        IA->>CA: Step 2: DOCUMENT_DRAFTING
        loop Multi-turn Co-Authoring
            CA->>AA: Clarifying questions & section outlines
            AA-->>CA: Stakeholder guidance & domain answers
        end
        CA-->>IA: Markdown Document Draft
        IA->>JM: Step 3: CONTEXT_ENRICHMENT (Web Search)
        IA->>JM: Step 4: VALIDATION (Quality Scoring)
        IA->>Formatter: Step 5: RENDERING (Markdown -> .docx)
        Formatter-->>IA: Save file to output/*.docx
        IA->>JM: update_job(status: completed, document_path)
    end

    Client->>API: GET /agent/job/{job_id}
    API-->>Client: Job status, logs & execution plan

    Client->>API: GET /agent/job/{job_id}/download
    API-->>Client: Binary .docx file download

Loading

---

Project Structure

Autonomous AI/
├── config.py                 # LLM model client initialization & environment setup
├── main.py                   # FastAPI server endpoints & async background worker
├── job_manager.py            # Async job lifecycle manager & SDK RunHooks tracker
├── test_runner.py            # End-to-end integration test runner
├── doc_agents/               # Multi-agent definitions
│   ├── __init__.py
│   ├── implementation_agent.py # Master orchestrator agent
│   ├── coauthor_agent.py     # 3-stage document co-authoring agent
│   └── answerer_agent.py     # Stakeholder answerer agent
├── tools/                    # Agent function tools
│   ├── __init__.py
│   └── mcp_tools.py          # Tools: task planning, co-authoring loop, search, validation, rendering
├── utils/                    # Utility modules
│   ├── __init__.py
│   └── docx_formatter.py     # Markdown-to-Docx conversion & styling engine
├── output/                   # Directory where generated .docx files are saved
├── .env.example              # Sample environment file configuration
├── .gitignore                # Git ignore configuration
└── requirements.txt          # Python package dependencies

---

Setup & Installation

Prerequisites

• Python 3.10+
• uv or standard Python venv

Environment Configuration

1. Clone the repository and navigate to the root directory.
2. Create a .env file based on .env.example:

   cp .env.example .env

3. Populate required credentials in .env:

   API_KEY=your_openai_or_portkey_api_key
   BASE_URL=https://api.portkey.ai/v1

Installation

Using uv:

uv venv
./.venv/Scripts/activate
uv pip install -r requirements.txt

Using standard pip:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r requirements.txt

---

Running the Application

1. Start the API Server

Start the FastAPI application on port 8000:

uv run main.py

Or directly with Uvicorn:

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

Interactive OpenAPI documentation will be accessible at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

---

API Endpoints

1. Submit Document Generation Request

• Method: POST
• Path: /agent
• Request Body:

  {
    "request": "Create a Product Requirements Document (PRD) for an AI Chatbot."
  }

• Response (HTTP 202 Accepted):

  {
    "job_id": "8da8e816-ce07-421b-a3f6-4d1f82ab05c8",
    "status": "queued"
  }

2. Poll Job Progress

• Method: GET
• Path: /agent/job/{job_id}
• Response (HTTP 200 OK):

  {
    "status": "completed",
    "job_id": "8da8e816-ce07-421b-a3f6-4d1f82ab05c8",
    "current_step": "rendering",
    "request": "Create a Product Requirements Document (PRD)...",
    "execution_plan": [
      {"step": 1, "description": "Analyze request...", "status": "completed"},
      {"step": 2, "description": "Co-author document...", "status": "completed"}
    ],
    "agent_logs": [
      "[INFO] Job created with ID: 8da8e816-ce07-421b-a3f6-4d1f82ab05c8",
      "[SUCCESS] Pipeline completed successfully."
    ],
    "document_path": "output/prd_chatbot.docx",
    "error": null,
    "created_at": "2026-07-25T15:00:00.000000"
  }

3. Download Generated Document

• Method: GET
• Path: /agent/job/{job_id}/download
• Response: Binary .docx stream attachment.

---

Running Integration Tests

Ensure the server is running on http://localhost:8000, then execute the test suite:

python test_runner.py

The test script submits test document requests, polls job status until completion, and verifies output generation.