# Open-source Kortix builds an agentic workflow from one row and one command > A first agentic workflow is a row in kortix.yaml and one command: write the trigger, ship it, fire it once by hand, then read the change request it opens. The open-source AI Operating System, Kortix, keeps the schedule, the machine and the prompt in one repo you own, so the whole thing is reviewable before it runs. URL: https://agenticworkflowguide.com/build-an-agentic-workflow ## Start to a landed change request Each trigger names its agent, its schedule or its secret, and the prompt template that becomes the session's first message. ### Add and ship `terminal` ```sh $ kortix triggers add daily-digest --type cron \ --cron "0 0 9 * * 1-5" \ --timezone America/Los_Angeles \ --prompt "Summarize yesterday. Open a CR." $ kortix ship → kortix.yaml pushed. daily-digest is scheduled. ``` Source: https://kortix.com/automations ### The row `kortix.yaml` ```yaml # fires on the clock triggers: - slug: daily-digest type: cron agent: kortix cron: "0 0 9 * * 1-5" timezone: America/Los_Angeles session_mode: fresh prompt: | Summarize yesterday's commits. Open a change request against main. ``` Source: https://kortix.com/automations ## Before you start: a project, an agent and a repo An agentic workflow is a goal, an agent that decides the steps, and a place to work. [The definition](/what-is-an-agentic-workflow) covers the loop, and [four finished examples](/examples) show what the end of a run looks like. A first build needs less reading than that. It starts with four things you can check in a few minutes. A Kortix project with `kortix.yaml` in a git repo. At least one agent named under `agents:`, pointed at a sandbox image the project declares. A connector, if the job has to reach another system. A repo the session can clone, because the machine clones the project repo into `/workspace` before the first message. The repo deserves the first look. Every run starts from it, and the work a run commits goes back to it. If your first step is dragging boxes inside a product you log into, the workflow already lives in that product's database. The schedule leaves when the subscription does. A row in a file you own has a diff, a history and a reviewer, and it still explains itself after the person who wrote it changes teams. ## Step 1: put the schedule in a trigger row The trigger goes in `kortix.yaml`, next to your agents and sandbox images. Each one names its agent, its schedule or its secret, and the prompt template that becomes the session's first message. A trigger has exactly two types: `cron` and `webhook`. The weekday digest is the smallest useful one, and its comments are worth keeping: ```yaml # fires on the clock triggers: - slug: daily-digest type: cron agent: kortix cron: "0 0 9 * * 1-5" timezone: America/Los_Angeles session_mode: fresh prompt: | Summarize yesterday's commits. Open a change request against main. ``` Read the row out loud and the schedule is plain. 09:00 on weekdays, Los Angeles time, running as the `kortix` agent, in a fresh session, with that prompt as the first thing the agent reads. The cron expression carries six fields, second through weekday. It runs in any IANA timezone. A single `run_at` timestamp covers the job that should happen once and then stay quiet. `session_mode` decides which session the fire lands in. `session_mode` has four values: `fresh`, `reuse`, `pinned`, `keyed`. The default is `fresh`. A digest wants a clean slate, so this row says `fresh` where a reader can see it. Naming it costs one line, and nobody has to go and check a default. ## Step 2: ship the file `kortix ship` pushes `kortix.yaml` and answers `→ kortix.yaml pushed. daily-digest is scheduled.` That output is the whole install. The file is now the record of the schedule, and the record was reviewable before it went anywhere. Keep the change in a change request like any other config edit. A trigger added in a commit carries its reason with it. The next person can see who asked for the 09:00 slot and what the prompt said that day. ## Step 3: fire it once by hand `kortix triggers fire daily-digest` starts the session the clock would have started, and answers `→ session started`. Fire it the same hour you write it. Wait for 09:00 and the first thing you learn is whether the prompt renders. That answer arrives a day later, with nobody watching. A hand fire costs one session. It shows you the machine boot, the first tool call and the first wrong assumption while the row is still open in your editor. `kortix triggers ls` lists the triggers and when each one last fired, so you can confirm the hand fire registered before you trust the clock with it. ## Step 4: read what came back A triggered session works on a branch of its own, and a session that only answers, or stops on a question, ends there. One isolated sandbox per session. Each session has its own isolated machine and branch. The machine boots from the sandbox image your project declares. It clones the repo into `/workspace` and cuts a branch named after the session. Every edit, commit and stray file the session produces lives on that branch and nowhere else, and the rest of the machine goes with the run. Then `kortix cr` opens the way back, and answers `→ change request opened toward main`. A person opens it and reads changed lines against a base, the way they read a colleague's work. Session work reaches `main` through a change request. Merge is default-deny for agents. A run cannot finish by putting its own work into `main` on its own authority. Two things are worth checking on the first one. Whether the branch holds only the files the task needed, and whether the prompt asked for something the run could actually reach. ## Step 5: make it a webhook when the clock is the wrong trigger A schedule covers the work that belongs at a known time. Some work belongs to an event instead, and that is a `webhook` trigger: an external service POSTs to the trigger URL, and the payload renders into the prompt. Change `type` to `webhook`, name the project secret, and the rest of the row stays where it is. Every webhook trigger names a project secret that signs it, and a trigger without one is rejected at validation. The caller sends `X-Kortix-Signature: sha256=`, an HMAC-SHA256 over the raw request body compared in constant time, and the GitHub-compatible `X-Hub-Signature-256` header works too. ## What breaks first Three failures account for most of a first week, and none of them is subtle once you know the shape. The prompt asks for a tool the agent does not have. The row names an agent whose project has not connected the app. The run stops where it cannot reach. An automation gets no privileges a person would not get. The fix is a connector or a grant, and a longer prompt will not find one. A webhook ships without its secret. A trigger without one is rejected at validation, which is the better version of this failure: the row never fires, and no unauthenticated endpoint sits open while somebody remembers to lock it down. The run opens a change request nobody merges. Merge is default-deny for agents, unless an admin granted the merge capability. A week of unmerged change requests leaves the work on branches. Every new fire starts from the same base, and Monday's digest reports on a repo nobody moved forward. ## The file is the workflow The whole definition fits on one screen. That is the argument for writing it in a file instead of drawing it in a canvas. [The tools comparison](/agentic-workflow-tools) puts a similar question to other platforms: where the workflow is defined, and who reads what comes back. Run yours on Kortix Cloud, in your VPC, or on your own on-prem network. Self-host is free. ## Building your first workflow ### How do I build an agentic workflow from scratch? Start with one row in `kortix.yaml`: a trigger with a type, an agent and a prompt. Run `kortix ship`, fire it once by hand, then read the change request it opens against `main`. ### Do I need to write code to build an agentic workflow? No. The first workflow is YAML and two commands. The trigger, the agent name, the schedule and the prompt are plain text in `kortix.yaml`, and the agent does the work on its own cloud computer. ### How do you schedule an agentic workflow? With a `cron` trigger. The expression has six fields, second through weekday, and it runs in any IANA timezone. `kortix ship` registers it, and `kortix triggers ls` shows what is scheduled. ### How do you secure a webhook that triggers an agent? Sign it with a project secret. Every webhook trigger names one, a trigger without it is rejected at validation, and the caller sends `X-Kortix-Signature: sha256=`, an HMAC-SHA256 over the raw body compared in constant time. ### Can you run an agentic workflow on your own servers? Yes. Kortix runs on Kortix Cloud, in your VPC, or on your own on-prem network, and self-host is free. The trigger row sits in the repo with the sandbox image, so the workflow moves with the code. ## Write the row, ship it, and the schedule is yours. One file holds the agent, the trigger and the prompt, and a person merges what the run commits. [Try Kortix](https://kortix.com) · [See four finished runs](https://agenticworkflowguide.com/examples)