Published Gist: https://gist.github.com/oruenboi/b8b01fb8c3da28d8c6e7cf323fa91b1e
Use this workflow when an existing application must become safely operable by agents. It covers both starting conditions: the application has no supported API, or it has APIs that are insufficient for agentic use.
API availability and agent readiness are separate questions. An endpoint can exist yet still be unsuitable because it lacks workflow context, stable resource identity, delegated authorization, previews, idempotency, readback, or auditability.
| Guide | Responsibility | Primary output |
|---|---|---|
| This workflow | Selects the correct path for each required capability and coordinates the handoffs | Capability classification and end-to-end delivery sequence |
| Repository Agent Brief: Plan How to Open an API | Inspects the repository and plans a supported contract, architecture, security boundary, lifecycle, and rollout | Evidence-backed API planning pack |
| Agentify Any App | Defines what makes an application and its action surfaces usable and trustworthy for agents | Agent-readiness gaps, action contracts, skills, adapters, tests, and evaluations |
The API brief is planning-only. The Agentify guide may lead to implementation artifacts, but implementation still requires separate authorization.
flowchart TD
A["Select target consumer and workflow"] --> B["Inspect repository and business operations"]
B --> C["Inventory existing APIs and machine interfaces"]
C --> D["Assess each required capability for agent readiness"]
D --> E{"Classify capability"}
E -->|Reuse| F["Document contract and expose through an agent tool"]
E -->|Harden| G["Add trust, security, and operational controls"]
E -->|Extend| H["Add missing context or workflow coverage"]
E -->|Build| I["Plan a supported API boundary and contract"]
E -->|Block| J["Retain human control or exclude the capability"]
G --> K["Architecture and contract plan"]
H --> K
I --> K
K --> L{"Decision gate"}
L -->|Revise| D
L -->|Approve| M["Separately authorized implementation"]
F --> N["Define skills and runtime adapters"]
M --> N
N --> O["Validate permissions, safety, readback, and audit"]
O --> P["Restricted release and monitored expansion"]
J --> Q["Record rationale, owner, and reconsideration trigger"]
| Observed condition | Default response |
|---|---|
| No supported machine interface exists | Use the repository API brief, then apply Agentify requirements to the proposed contract |
| An API exists but omits required workflows | Extend the supported API rather than creating parallel agent-only business logic |
| An API exposes low-level CRUD but not business actions | Design task-level commands around the application's existing domain logic |
| Reads lack stable identity or sufficient context | Add resource resolution and context surfaces before allowing actions |
| Writes lack preview, approval, idempotency, readback, or audit | Harden the action surface before agent execution |
| The API already meets agent-readiness requirements | Reuse it and add only the skill or runtime adapter needed by the agent framework |
| A capability is unsafe, prohibited, or cannot be reliably authorized | Block agent access and preserve a human-controlled workflow |
Classify each required business capability independently. Do not classify the application or API as a whole when different operations have different maturity and risk.
| Outcome | Use when | Required next step |
|---|---|---|
| Reuse | A supported API already provides the operation with adequate context, controls, and verification | Document the contract and map it into an agent tool or skill |
| Harden | The operation exists but lacks security, safety, reliability, or operational controls | Add the missing controls without duplicating domain logic |
| Extend | The API is sound but lacks required context, resources, business actions, or workflow coverage | Extend the supported contract and its compatibility policy |
| Build | No suitable supported machine interface exists | Produce and approve an API architecture and delivery plan |
| Block | The operation should not be exposed, or required controls cannot be enforced | Keep it human-controlled and record the rationale and owner |
Score every target capability as ready, partial, missing, or blocked for each dimension.
| Dimension | Evidence to seek |
|---|---|
| Supported contract | Documented, versioned interface with an owner and compatibility policy |
| Resource identity | Stable, external-safe identifiers and resolvable resource URIs |
| Context | Sufficient state, relationships, constraints, and allowed next actions |
| Actor and delegation | Human, service, and delegated agent identities remain attributable |
| Authorization | Least-privilege, tenant-aware checks occur at the true business boundary |
| Business action | Task-level operation invokes existing domain rules rather than bypassing them |
| Schemas | Bounded, machine-readable inputs, outputs, and error responses |
| Preview and approval | Consequences can be inspected and high-risk actions can require approval |
| Idempotency | Retried commands cannot unintentionally duplicate effects |
| Concurrency | Stale state and conflicting updates are detected |
| Async outcomes | Long-running and unknown outcomes can be polled or reconciled |
| Readback | The resulting authoritative state can be retrieved and verified |
| Audit | Requester, delegated actor, action, target, outcome, and approval are recorded |
| Interface blockers | CAPTCHAs, UI-only state, browser sessions, and manual steps are identified |
| Operations | Observability, quotas, support, incident response, and retirement are owned |
Name the intended consumer, business outcome, risk level, system of record, and authoritative owner. Start with one narrow end-to-end workflow, not a general mandate to "make the app agentic."
Use Repository Agent Brief: Plan How to Open an API to trace domain logic, authorization, transactions, data boundaries, deployment constraints, and all current machine interfaces. Record repository evidence rather than inferring architecture from route names alone.
Apply the assessment above and the detailed guidance in Agentify Any App to each read and action needed by the workflow. Existing APIs must pass this review; their existence is not evidence of readiness.
Assign reuse, harden, extend, build, or block. Record evidence, gaps, risk, proposed owner, dependencies, and acceptance criteria for each classification.
For harden, extend, and build, turn Agentify gaps into explicit API requirements. The plan must preserve the application as the system of record and domain-logic authority. It must not create an agent-only API that reimplements business rules.
Architecture, product, security, legal or compliance, and operations owners approve, revise, or block the proposal. Approval of a plan does not itself authorize implementation or external exposure.
Implement the approved API changes using repository conventions. Then define the smallest skills, tools, or runtime adapters needed to call the supported interfaces.
Test service maturity and action trust separately. Validate permissions, tenant isolation, schemas, retries, concurrency, dry-runs, approvals, readback, audit, failure recovery, and sanitized end-to-end evidence. Start with a restricted audience and expand only when monitored results meet the acceptance criteria.
- Target workflow and consumer statement
- Repository and existing-interface inventory
- Capability matrix with
reuse,harden,extend,build, orblock - Agent-readiness assessment with evidence and gaps
- Proposed API boundary and contract changes
- Security, delegation, approval, audit, and operational requirements
- Staged delivery plan with owners, dependencies, tests, and decision gates
- Agent skill or adapter plan for approved, supported interfaces
- Validation evidence and release recommendation
| Decision | Accountable owner |
|---|---|
| Current implementation facts and technical feasibility | Engineering or architecture |
| Target workflows and acceptable user experience | Product or business owner |
| Identity, delegated authority, tenant isolation, and abuse controls | Security and engineering |
| Data rights, regulated actions, and retention | Legal, compliance, or data governance |
| Reliability, support, incident handling, and retirement | Service or operations owner |
| Whether a high-risk capability remains human-controlled | Product, risk, and accountable business owner |
- Keep the public
403ea8afcd3a68c7495e86f410306692Gist as the canonical Agentify source; preserve the older private copy only as history. - Do not modify raw source files while maintaining this workflow.
- Keep planning agents distinct from runtime agents that exercise production authority.
- Reuse supported application services and business rules; do not expose database tables, ORM methods, or unstable internals as the external contract.
- Use stable external-safe identifiers rather than leaking database primary keys when those keys are not part of a supported contract.
- Treat preview, approval, execution, and readback as distinct stages for consequential actions.
- Record blocked capabilities explicitly. Absence from the plan is not a security control.
The workflow is complete for a target use case when every required capability has a classification, evidence, owner, and acceptance criteria; all harden, extend, and build work has an approved architecture path; blocked work is explicit; agent artifacts use only supported interfaces; and end-to-end tests demonstrate attributable, authorized, recoverable, and auditable behavior.
- Repository Agent Brief: Plan How to Open an API
- Agentify Any App
- Opening an API - Decision Framework and Best Practices
- Open API Strategy - Research Sources