Authoring Workflow

Developer Reference

This page covers internal implementation details. It is not included in the User Guide.

The Authoring Agent (v4-authoring-agent-java) guides domain experts through building an agent.yaml package via structured conversation. Source: v4-authoring-agent-java/README.md.

Source

Stack: Java 21 / Quarkus 3.35.1 / LangChain4j (Anthropic). Single endpoint POST /api/v1/author (SSE) on port 8085. Stateless — the frontend stores the in-progress draft_package and replays it each turn. Five conversation modes, one per tab, each scoped to a single CE collection.

Five modes

Mode	Tab	Scope	Flow
CHAT	Chat (default)	All CE collections	Read-only queries — no create/update/delete
AGENT_BUILD	Agent	Agents	Full CRUD — 8-stage interview → per-stage code generation → review → register
PLAYBOOK	Playbook	Playbooks	Full CRUD — cloud-scoped (AWS/Azure)
SKILL	Skill	Skills	Full CRUD — short interview
DOMAIN_LENS	Domain Lens	Domain lens documents	Full CRUD — reference docs, frameworks, policies

Mode = tab selection = scope boundary. There is no cross-mode operation and no separate intent classifier — the active tab tells the service which agent (AgentBuildAgent, PlaybookAgent, SkillAgent, DomainLensAgent, ChatAgent) to dispatch to. Mode agents share builder utilities (skills, tools, guardrails, lenses) and use search-first before creating — existing CE assets are reused where possible.

Stateless contract

Frontend → POST /api/v1/author { prompt, draft_package, mode }
Service  → SSE stream:
            event: thinking-state
            event: file (zero or more — generated YAML/code files)
            event: text  (assistant explanation)
            event: state (updated draft_package)
            event: done

Frontend stores `state` and replays it on the next turn.

The service holds nothing between turns. The frontend owns storage, local file writes, and tab/mode selection. The service owns all draft_package mutations, including stage transitions in the 8-stage AGENT_BUILD interview.

Build → register handoff

When the user is satisfied with a built agent, the Authoring Agent hands off to the Playbook Agent via a hard route. From there the assembled package can be registered through the ADK CLI:

python -m adk register PATH [--dry-run]

See ADK Reference for CLI details.

---

Below this line — illustrative interview content

The walkthrough that follows is illustrative of the kind of conversation a domain expert has with the Authoring Agent. It is not the literal prompt sequence in code — that lives in v4-authoring-agent-java/src/main/resources/prompts/. Treat the example as flavour for what the experience feels like, not as a contract.

---

Starting the Author Agent

The Author Agent is a platform agent accessible through the standard Escher Gateway interface:

> I want to build a new security agent that detects unencrypted EBS volumes

The Author Agent identifies this as an authoring request and initiates the interview.

---

The interview sequence

The Author Agent collects the following through conversation:

1. Domain and purpose

Author: Which domain does this agent belong to?
        (security / finops / compliance / iam / infra / devops / data-ops / new domain)

Expert: security

Author: Describe in one sentence what this agent does.

Expert: Detects EBS volumes without encryption at rest across all AWS accounts.

2. Skills — what questions it can answer

Author: What specific questions should this agent be able to answer?
        List them as natural-language prompts your users might type.

Expert: "Which EBS volumes are not encrypted?"
        "Are any of my production volumes unencrypted?"
        "How many unencrypted volumes do I have per account?"

3. Data needed — what cloud data each skill requires

Author: For 'Which EBS volumes are not encrypted?' — what data do you need to answer it?

Expert: A list of all EBS volumes with their encryption status, account, region, size.

4. Tool resolution — matching to existing tools

Author: I found this tool in the Tool collection:
        aws.ec2.describe_volumes — returns volume ID, state, encryption, size, region

        Does this cover your data need?

Expert: Yes.

5. Output type

Author: What should the output look like?
        (finding — one actionable item | report — multi-item analysis | triage — rapid summary)

Expert: Finding — one finding per unencrypted volume, or a report grouping them.

Author: I'll use 'finding' for individual volumes and generate a summary report.
        Shall I also generate a remediation Playbook to enable encryption?

Expert: Yes — but only for volumes not attached to running instances.

6. Safety and policy

Author: For the remediation Playbook — what safety constraints apply?
        - Do not encrypt volumes attached to running instances? (too risky without snapshot)

Expert: Correct. Playbook should only target detached volumes or stopped instances.

---

Package assembly

After the interview, the Author Agent produces a draft package:

ebs-encryption-agent/
  agent.yaml
  skills/
    security.detect_unencrypted_ebs.yaml
  playbooks/
    security.encrypt_detached_ebs.yaml
  tools/
    aws.ec2.describe_volumes.yaml          (stub if not yet in CE Tool collection)
  context_builders/
    security.ebs_inventory_context.yaml

The Code Agent generates the tool YAML stubs for any tools not already in the CE Tool collection.

---

Finalising and registering

Review the assembled package:

adk validate ./ebs-encryption-agent/
# ✓ agent.yaml: valid
# ✓ skills: 1 skill validated
# ✓ playbooks: 1 playbook validated
# ✓ tools: all tool_ids resolvable
# Validation passed.

adk register ./ebs-encryption-agent/
# Registering skill: security.detect_unencrypted_ebs
# Registering playbook: security.encrypt_detached_ebs
# Registering tool: aws.ec2.describe_volumes
# Registering agent: domain.security.ebs_encryption
# Registration complete.

---

Next steps

• agent.yaml Reference — Full spec for every field
• ADK Reference — CLI commands
• Writing Playbooks — The playbook.yaml schema