Agent Workflows

Experimental development surface

This analysis, provider or Studio surface is outside the stable backend contract. Review its outputs and application integration before use. It is not required for REST, synchronous MCP or Durable Operations. See stability labels.

Agent Workflows transform a free-text goal into a structured, step-by-step execution plan that combines diagnostics, search, inspectors, and playbooks into a single ordered timeline. Nothing is auto-mutated — the workflow is a plan the developer (or an LLM) can review, approve, and execute incrementally.

---

Concepts

Term	Description
Workflow	An ordered list of steps derived from a goal
Step	A single actionable item with kind, title, commands, risk, and effort
Step Kind	One of: inspect, search, edit_file, run_migration, run_query, run_test, environment, config, diagnostics, doc_reading
Source	Where the steps came from: doctor (diagnostics only), search, manual, or mixed

How It Differs from Other Features

Feature	Purpose
Doctor Fix-Plan	Diagnose and suggest fixes for known issues
Playbooks	Step-by-step recipes for a single task category
Agent Context	Gather project context for an LLM prompt
Workflows	Combine all of the above into one ordered plan

---

Quick Start

Studio UI

1. Open the Agent panel (press 8 in Studio).
2. Type a goal in the text area (e.g. "Fix slow queries on /api/posts/").
3. Toggle Include diagnostics / Include search checkboxes as needed.
4. Click Generate Workflow.
5. Switch to the Workflow tab to see the plan.

Each step shows its kind, risk level, estimated effort, suggested commands (with copy buttons), and notes.

CLI

# Basic workflow
aksara agent workflow "Fix slow queries on /api/posts/"

# With a playbook
aksara agent workflow "Add email to User model" --playbook add_field_to_model

# Skip diagnostics
aksara agent workflow "Refactor auth" --no-diagnostics

# JSON output (for piping to LLMs)
aksara agent workflow "Fix login" --format json

Python API

from aksara.ai.workflows import (
    build_agent_workflow,
    summarize_agent_workflow,
    workflow_stats,
)

wf = build_agent_workflow(
    "Fix slow queries on /api/posts/",
    include_diagnostics=False,
    include_search=False,
)

print(summarize_agent_workflow(wf))
print(workflow_stats(wf))

for step in wf.steps:
    print(f"[{step.order}] {step.kind}: {step.title}")
    for cmd in step.commands:
        print(f"  $ {cmd}")

The direct workflow import and the aggregate aksara.studio re-export are both order-independent. Diagnostic set_env actions keep the variable name and example value separately, so rendered workflow commands contain one export assignment. Workflow commands are display-only suggestions: review them before execution.

---

Step Kinds Reference

Kind	Emoji	Description
inspect	🔍	Model or query inspection
search	🔎	Semantic search across project artifacts
edit_file	✏️	Edit a source file
run_migration	🗃️	Generate or run a migration
run_query	📊	Execute or analyse a query
run_test	🧪	Run the test suite
environment	⚙️	Environment or dependency setup
config	🔧	Configuration change
diagnostics	🩺	Run diagnostic checks
doc_reading	📖	Read documentation

---

Workflow Builder Pipeline

The builder assembles steps in a deterministic order:

1. Diagnostics (order 1–49) — Runs aksara doctor checks and converts issues + auto-remediation actions into steps.
2. Inspectors (order 50–99) — Always adds model inspection; conditionally adds query inspection if the goal mentions queries.
3. Search (order 100–199) — Builds the semantic index and searches for relevant artifacts, generating kind-specific commands.
4. Playbook (order 200–299) — If a playbook key is provided, converts playbook steps into workflow steps.
5. Test (order 300) — Always appends a final "run tests" step.

Risk & Effort

• Risk is derived from diagnostic severity (error → high, warning → medium, info → low) or playbook risk level.
• Effort is inferred from step kind (run_migration and edit_file → high; run_query and config → medium; everything else → low).

---

Studio API

POST /studio/agent/workflow

Generate a workflow from a goal.

Request body (AgentWorkflowRequest):

{
  "goal": "Fix slow queries on /api/posts/",
  "playbook": null,
  "include_diagnostics": false,
  "include_search": false,
  "search_query": null,
  "limit_search_results": 10,
  "limit_diagnostics": 10
}

Response (AgentWorkflowResponse):

{
  "workflow": {
    "id": "wf-abc123",
    "goal": "Fix slow queries on /api/posts/",
    "playbook": null,
    "source": "manual",
    "steps": [
      {
        "id": "step-inspect-9143c828",
        "kind": "inspect",
        "title": "Inspect registered models",
        "description": "Review model schemas, fields, relationships, and constraints to understand the data layer relevant to your goal.",
        "references": {
          "target": "models",
          "goal": "Fix slow queries on /api/posts/"
        },
        "estimated_effort": "low",
        "risk": "low",
        "commands": [
          "aksara inspect models",
          "aksara inspect models --format json"
        ],
        "notes": ["Check field types, relationships, and constraints."],
        "order": 50
      },
      {
        "id": "step-inspect-f89863f9",
        "kind": "inspect",
        "title": "Inspect slow queries",
        "description": "Analyse the slowest queries for potential optimisation.",
        "references": {
          "target": "queries",
          "goal": "Fix slow queries on /api/posts/"
        },
        "estimated_effort": "medium",
        "risk": "low",
        "commands": [
          "aksara inspect queries --top 10",
          "aksara inspect queries --format table"
        ],
        "notes": ["Look for missing indexes, full table scans, and N+1 patterns."],
        "order": 51
      },
      {
        "id": "step-run_test-c549b243",
        "kind": "run_test",
        "title": "Run test suite",
        "description": "Verify changes by running the project test suite.",
        "references": {"goal": "Fix slow queries on /api/posts/"},
        "estimated_effort": "medium",
        "risk": "low",
        "commands": ["python -m pytest -x -q", "aksara test"],
        "notes": ["Run after applying any changes to ensure nothing is broken."],
        "order": 300
      }
    ],
    "metadata": {
      "goal": "Fix slow queries on /api/posts/",
      "ai_hub": {
        "active_provider": null,
        "chat_model": null,
        "code_model": null,
        "embeddings_model": null
      }
    }
  },
  "summary": "Workflow for \"Fix slow queries on /api/posts/\" with 3 steps (2 inspect, 1 run_test).",
  "stats": {
    "total_steps": 3,
    "by_kind": {"inspect": 2, "run_test": 1},
    "by_risk": {"low": 3},
    "by_effort": {"low": 1, "medium": 2},
    "has_high_risk": false,
    "playbook": null,
    "source": "manual"
  }
}

GET /studio/agent/workflow/sample

Returns a sample workflow for demonstration purposes.

---

CLI Reference

aksara agent workflow GOAL [OPTIONS]

Arguments:
  GOAL  The goal to build a workflow for

Options:
  --playbook TEXT           Playbook key to include
  --no-diagnostics          Skip diagnostic checks
  --no-search               Skip semantic search
  --search-query TEXT       Override the search query
  --limit-search INT        Max search results (default: 10)
  --limit-diagnostics INT   Max diagnostic issues (default: 10)
  --format [text|json]      Output format (default: text)

---

Models

All models are Pydantic v2 dataclasses exported from aksara.studio.models:

• AgentWorkflowStep — A single step in the plan
• AgentWorkflow — The complete workflow with steps and metadata
• AgentWorkflowRequest — Request body for the API endpoint
• AgentWorkflowResponse — Response with workflow, summary, and stats
• AgentWorkflowStepKind — Literal type for valid step kinds