Agentic workflows: a practical guide for developers

An agentic workflow is a process where a large language model loops through perceive, reason, act and observe until a multi-step job is done. No human driving each step.

For repo automation that looks like this. The agent reads a failing test log, plans a fix, applies it, re-runs the tests, then checks whether it worked. One run, no supervision. DeepLearning.AI's agentic AI course teaches the same loop.

This guide covers the patterns, the guardrails, the costs and a working example you can drop into a repo today. If you want to skip ahead, the minimal example is near the end.

---

Why do agentic workflows beat traditional automation?

A script follows fixed if-then rules. It breaks the moment a task falls outside the path someone wrote for it. An agentic workflow decides what to do at runtime instead. That is why it handles the messy, ambiguous work that eats a developer's day.

Typical benefits:

• Handle open-ended tasks (triage, diagnosis, doc generation) without pre-scripting every branch
• Reduce handoffs between tools and humans by keeping reasoning inside one loop
• Adapt to new inputs mid-run rather than failing on unexpected states
• Work across multiple tools and APIs in a single coordinated pass

Common trade-offs to know before you start:

• Inference cost adds up fast, especially with long loops or big context windows
• Latency is worse than a script. Agents think before they act
• Failure modes are harder to debug because the reasoning is probabilistic
• More work in testing, observability and rollback

GitHub Agentic Workflows and AWS agentic design patterns both treat these trade-offs as engineering work you plan for up front.

---

How does the agentic loop actually work?

Every agentic workflow runs the same cycle. Perceive an input, reason about what to do, act on that reasoning, observe the result, then decide whether to go round again.

Think of a chef mid-service. Read the ticket, taste the dish, adjust the seasoning, taste again, plate it when it is right. The tasting step is the whole trick. Without it you are just following a recipe with your eyes shut.

Here is how each stage maps to something a repo actually does:

1. Perceive: Read the trigger input (a GitHub issue body, a failed CI log, a pull request diff). This is an API call or a file read.
2. Reason: The LLM plans the next action based on the input and any tool schemas available (e.g. "run tests", "search codebase", "open PR").
3. Act: Invoke a tool or git action: run pytest, call a search API, write a file, or post a comment.
4. Observe: Read the tool output (test results, search hits, error messages) and feed it back into the model's context.
5. Repeat or stop: The agent decides whether the goal is met. If not, it loops. If yes, it exits.

Neo4j's agentic workflow guide sets out the same perceive, reason, act, observe cycle. Databricks adds the production view: chain the loop into a feedback model, and govern the stop condition.

Exit conditions matter as much as the loop. Without one, the agent runs forever and burns your budget doing it. Give every step a success test it can actually check.

Exit condition type	Example	When to use
Success predicate	All tests pass, PR approved	Primary stop condition for most workflows
Max iterations	Loop count reaches 10	Safety net against infinite loops
Human approval gate	Reviewer clicks "Approve" in UI	Required for write actions in production
Error threshold	Three consecutive tool failures	Fail-fast pattern for unreliable tools

---

What are the main agentic patterns and how do you pick one?

There are six patterns worth knowing: single-agent, manager/coordinator, sequential multi-agent, parallel multi-agent, loop/critic, and human-in-loop.

The selection rule is one line. Start with a single agent. Add complexity only when the task forces you to. Anthropic's engineering guide says exactly this, and it is the most ignored advice in the field.

AWS prescriptive guidance maps the patterns to cloud architectures and tells you to pick the orchestration pattern before you pick the model. DeepLearning.AI's course treats reflection, tool use, planning and multi-agent collaboration as the four base designs.

Pattern overview:

• Single-agent: One LLM with tools. Low complexity, low cost, easy to debug. Use for focused, single-domain tasks (e.g. summarise a PR, triage an issue).
• Manager/coordinator: One orchestrator delegates to specialist sub-agents. Adds latency and cost but handles tasks that span multiple domains.
• Sequential multi-agent: Agents pass outputs to the next in a chain. Good for pipelines where each step depends on the last (e.g. fetch data, analyse, write report).
• Parallel multi-agent: Agents run simultaneously and results are merged. Cuts wall-clock time but increases cost and coordination complexity.
• Loop/critic (reflection): An agent reviews its own output and iterates. Improves quality on creative or analytical tasks but can loop expensively without a tight exit condition.
• Human-in-loop: A human approval step is built into the workflow. Non-negotiable for write actions in production or regulated environments.

Decision rules:

• Single task, one domain: use single-agent.
• Complex objective with distinct sub-tasks: consider manager/coordinator.
• Quality matters more than speed: add a reflection/critic pass.
• Write actions touch production systems: add a human approval gate.

A word on agent sprawl. Every extra agent adds a failure mode, a cost centre and a blind spot. Teams that start with five agents spend their time debugging the orchestration instead of the task. Keep a fixed backbone of ordinary CI steps and scripts. Add agentic behaviour only where the work is genuinely ambiguous. For a comparison of the orchestration frameworks, see CrewAI vs AutoGen vs LangChain.

---

How does this look in a real repository?

GitHub Agentic Workflows is the most concrete repo-level version of this available today. You write the instructions in plain English in a markdown file, add a YAML frontmatter block, and GitHub compiles it to a hardened .lock.yml before it runs. Agents run in firewalled containers with read-only tokens by default.

Repo artefacts you need:

• A .github/agents/ directory containing your .md workflow file
• A compiled .lock.yml (generated by the compile step, not hand-edited)
• A CI job or trigger event to kick off the workflow

Frontmatter fields (minimal example):

---
engine: copilot
triggers:
  - issue_comment
permissions:
  issues: read
  pull-requests: write
safe-outputs: true
---

Key implementation notes:

• safe-outputs: true restricts the agent to proposing changes rather than applying them directly. Start here.
• The .lock.yml compile step pins the workflow to a verified, tamper-resistant version. Never edit it manually.
• Permissions follow least-privilege: grant only what the task needs (read issues, write PRs, nothing else).
• Commit the .md workflow file to version control and treat it like code: review it in PRs, test it in a branch first.
• In org repos, restrict who can trigger agentic workflows using branch protection rules and required reviewers.

For the wider integration picture, how to connect AI systems to your existing tools covers doing this safely.

---

Which engines and tools should you use?

The engine is the reasoning and tool-calling model at the centre of the workflow. Pick on latency, cost, context window and your data policy. The frontmatter engine field in GitHub Agentic Workflows lets you swap engines without rewriting the instructions.

Commonly used engines:

• Anthropic Claude: Strong on long-context reasoning and following instructions properly. Our default for complex triage and multi-step analysis. API key required, billed per token.
• GitHub Copilot: Tied into GitHub's permission model. A good default for tasks that never leave the repo. Billing rides on your Copilot subscription.
• OpenAI Codex / GPT: Broad tool-call support and a big integration ecosystem. OpenAI's practical guide to building AI agents recommends prompt templates and policy variables to cut maintenance.
• Google Gemini: Competitive on multimodal work and long context. Runs through Google Cloud, billed via GCP.

Where we start, and why. For the businesses we build with, the answer is Claude Code. Not because the other engines are weak, but because Claude Code lets a non-technical founder build and change a real delivery system in days. The repo becomes the workspace, not a barrier. That matters more than a benchmark when the person who owns the IP is the one who needs to edit it. We have written up how that works for non-technical founders and what a custom AI delivery system looks like in practice.

Auth and secrets guidance:

• Never pass secrets (API keys, tokens, credentials) into the agent's runtime context. Use sealed vaults (GitHub Secrets, AWS Secrets Manager) and inject them as environment variables at the job level only.
• Use role-based tokens scoped to the minimum permissions the task needs.
• Rotate tokens regularly and audit access logs after each production run.

Billing and rate-limit caveats:

• Inference cost scales with context window size and loop depth. A workflow that reads a 10,000-token codebase and loops five times costs roughly 50,000 tokens per run.
• Test locally or in a sandbox environment with a cheaper model (e.g. a smaller GPT variant) before running against production with a large model.
• Set hard token budgets and rate-limit guards in your CI configuration to prevent runaway spend.

---

How do you keep agentic workflows safe?

Guardrails are the engineering core of an agentic system. Autonomy without limits is a liability, not a feature. Databricks treats human-in-loop checkpoints and governance as standard kit for production, not optional extras.

Guardrail checklist:

• Least privilege: Grant only the permissions the task requires. Read-only by default.
• Safe-outputs: Enable safe-outputs: true so the agent proposes changes rather than applying them.
• Sandboxed execution: Run agents in firewalled containers with no access to production databases or external networks unless explicitly required.
• Input validation: Validate and sanitise all inputs before they reach the agent's context. Prompt injection is a real attack vector.
• Typed tool schemas: Define tools with typed inputs and strict validation so agents cannot issue malformed or unsafe calls.
• Threat detection: Log all tool invocations and flag anomalous patterns (unexpected file writes, unusual API calls) for review.

Human checkpoints without bottlenecks. Put approval gates only where the risk is real. Before a write action in production. Before merging an agent's PR. Before anything touching customer data. Make the approval async, a Slack message with an approve or reject button, so the pipeline does not sit and wait on someone's inbox.

Audit and logging checklist:

• Log every tool call with its inputs, outputs, and timestamp
• Record the full reasoning trace (model output at each step) for post-mortem analysis
• Store logs in an immutable, append-only store
• Set retention policies that meet your compliance requirements

Pro Tip: Run a red-team exercise on your agent before production. Give it a malicious issue body designed to trigger a prompt injection and check whether your input validation catches it. Most teams skip this step and regret it.

---

What drives cost and how do you monitor it?

Compute and inference are what you pay for. Measure both from the first prototype run, not after you ship. Databricks warns that agentic AI projects come off the rails on cost when nobody set a business value metric or a risk control at the start.

Cost drivers:

• Model API calls (billed per token, scales with context size and loop depth)
• Loop iterations and retries (each loop adds a full inference pass)
• Tool invocations (some APIs charge per call; Actions minutes add up)
• Large context windows (reading entire codebases per run is expensive)

Metrics to collect from day one:

• Turns per run (how many loop iterations the agent takes)
• Token count per run (input + output tokens)
• Tool latency (time per tool call)
• Task success rate (did the agent complete the goal?)
• False positive rate (did the agent take an action it should not have?)

Testing matrix:

• Unit test each tool in isolation with mocked inputs and expected outputs
• Run sandbox tests for any side-effecting action (file writes, API calls, git pushes) before enabling in CI
• Staged rollout: run on a low-traffic repo branch first, then expand to main after a week of clean runs

Metric	Suggested alert threshold
Turns per run	Alert on high count
Token count per run	Alert if greater than 50,000
Task success rate	Alert on low success rate
False positive rate	Alert if above 5%

---

When should you use an agentic workflow and when should you not?

Agentic workflows fit open-ended, multi-step problems where nobody knows the path to the answer in advance. They are the wrong tool when the logic is fixed and the inputs are predictable. Use a script for that and save yourself the bill.

Good use cases for developers:

• CI triage: read a failing build log, identify the root cause, suggest or apply a fix
• Incident diagnosis: correlate logs, metrics, and alerts to produce a structured incident report
• Documentation updates: detect code changes and regenerate affected docs automatically
• Complex data fixes: identify malformed records, propose corrections, and queue them for review
• Code review assistance: flag patterns, suggest improvements, and summarise PR changes

The same loop works outside the repo. Devwiz has written up agentic workflows for operations, which covers the ops-side version of this: same perceive, reason, act, observe cycle, applied to business process instead of build pipelines.

When to stay deterministic:

• Real-time control systems where latency or reliability guarantees are required
• Simple, well-defined transformations (format a file, rename a variable, bump a version number)
• Tasks where auditability requires a fixed, reproducible execution path
• Regulatory or safety-sensitive workflows that mandate human sign-off at every step

A note on regulated work. If your codebase touches financial data, health records or personal information, treat every agentic action as a compliance event. Log everything. Require human approval on writes. Check your data residency rules before you pick an engine, not after. For the wider picture of how agents join up across a business, see connecting AI agents across business operations.

---

Practical checklist to ship a production-ready agentic workflow

Follow this in order. Skip a step and you will come back to it later, under pressure, at the worst possible time.

1. Define the goal precisely. Write a one-sentence success condition before you write any code. Vague goals produce looping agents.
2. Choose a pattern. Start with single-agent. Add orchestration only when the task genuinely requires multiple domains. Anthropic's guide is clear: start simple.
3. Select your tools. List every tool the agent needs. Define typed inputs and strict validation for each one.
4. Set permissions to least privilege. Grant read-only access by default. Add write permissions only for the specific resources the task requires.
5. Build in a sandbox first. Run the workflow against a test repo or a branch with no production access. Confirm exit conditions work before touching main.
6. Write unit tests for every tool. Each tool should have a test with a mocked input and an expected output. This is not optional.
7. Instrument from the start. Add logging for turns, token count, tool latency, and success rate on the first run, not after something breaks.
8. Set a token budget and a max-iteration cap. Hard limits prevent runaway cost. Set them before the first production run.
9. Run a staged rollout. Deploy to a low-traffic repo or branch for one week. Review logs. Expand only after a clean run period.
10. Plan a rollback path. Know how to disable the workflow in under five minutes if something goes wrong. A feature flag or a single config change is the target.

Pro Tip: Prototype the core loop in 90 days, then spend the next sprint on production hardening: tighter tool schemas, better exit conditions, and a proper observability stack. Shipping a prototype fast is good. Shipping a prototype to production without hardening is how incidents happen.

---

Minimal agentic workflow you can run in a repo today

This is the smallest useful agentic workflow there is. It reads a GitHub issue, works out what kind of issue it is, and proposes a response. It writes nothing until you have read the output and approved it.

Create a file at .github/agents/triage.md and paste the following:

---
engine: copilot
triggers:
  - issues.opened
permissions:
  issues: read
  pull-requests: read
safe-outputs: true
---

You are a triage assistant for this repository.

When a new issue is opened:
1. Read the issue title and body.
2. Identify whether it is a bug report, a feature request, or a question.
3. Suggest one or two relevant labels from the existing label list.
4. Draft a short, polite first response acknowledging the issue and asking for any missing information.

Do not apply labels or post comments directly. Output your suggestions as a structured proposal for human review.

To run it:

• Commit the file to a branch and open a pull request to review the workflow definition itself
• Once merged, open a test issue in the repo to trigger the workflow
• Review the proposed output in the Actions log before any write permissions are enabled
• Check the run log for turns, token count, and the reasoning trace

Safety note. Keep safe-outputs: true until you have reviewed at least five clean runs. Only then consider enabling write permissions for low-risk actions like adding labels. Never enable write access to code files without a human approval gate in place.

For full frontmatter field reference, see the GitHub Agentic Workflows docs.

---

Three things most teams get wrong when building agentic systems

Most teams over-engineer version one. Five agents, a custom orchestration layer and a memory store, all before a single loop has run end to end. What they get is a system that is expensive to debug and slow to change.

Three things worth fixing early:

Start smaller than feels right. A single-agent loop with two tools teaches you more in a week than a multi-agent architecture teaches you in a month. Get the loop working. Instrument it. Then decide whether you need more agents. Usually you do not.

Instrument before you scale. Turns per run, token count and success rate are not nice-to-haves. They are how you find out whether the thing works or is quietly burning money. Add them on day one, because nobody ever goes back and adds them on day thirty.

Put the human checkpoint where the risk is. Not everywhere. One approval gate before a write action beats ten guardrails on reads. Keep it async so it does not become the bottleneck that kills adoption.

---

The AI Orchestrators: from prototype to production in 90 days

Most teams can get an agentic prototype running in a week. Getting it into production with real guardrails, observability and a rollback path takes longer, and it takes a different kind of thinking.

That gap is the whole job. A prototype proves the loop works. A system proves it keeps working when you are not watching.

The AI Orchestrators run a 90-day done-with-you program for founder-led businesses turning over $1M or more. We map your existing workflows and your IP, then build the agents that encode them: content, operations, delivery, support. Not scattered automations. One AI Operating System where each agent carries a piece of how you already make decisions, so output scales without you sitting in every loop. You get a diagnostic, a working prototype, hands-on buildout, a handoff to your team, and platform access to keep iterating.

It is built for educators and consultants who already have a proven program and are the bottleneck on every decision inside it.

The next step is the diagnostic. Take the IP monetisation assessment to see whether your workflows are ready to become an agent network. Or read the AI consulting program overview for exactly what the 90 days covers.

---

Sources

• What are agentic workflows? | Neo4j
• About GitHub Agentic Workflows | GitHub Docs
• Agentic workflows | Databricks blog
• Agentic AI patterns | AWS prescriptive guidance
• Agentic AI course | DeepLearning.AI
• Building effective agents | Anthropic engineering

---