A team (a crew in the code) is a set of agents, each with a role, that cooperate to accomplish a mission.
Key points
A team is described, checked without a model, then run
A team’s description declares the agents, their tools, their tasks and the folders they may touch. The --validate option loads it without calling a model, orkeon run runs it, and orkeon forge generates one from a sentence.
The runtime is the engine that executes the team and enforces the rules.
name: "sales-report-crew"goal: "Produce weekly sales analysis report"process: "sequential"verbose: truememory: trueplanning: trueagents:
data_analyst:
role: "Sales Data Analyst"goal: "Extract and analyze sales metrics from the database"backstory: |
Senior data analyst with 10 years of retail experience. Expert in SQL and statistical analysis.tools:
- "relational_database_query"
- "csv_reader"maxIter: 10maxRpm: 15report_writer:
role: "Report Writer"goal: "Transform analysis results into a clear executive report"backstory: |
Business communications specialist who turns data insights into actionable executive summaries.tools:
- "file_write"maxIter: 5tasks:
analyze_sales:
description: |
Query the sales database for the last 7 days. Calculate: total revenue, top 5 products by units sold, week-over-week growth rate. Return structured JSON. The database is the SQLite file sales.db: provider_name 'Microsoft.Data.Sqlite', connection_string 'Data Source=sales.db'. Table sales(id, sale_date 'YYYY-MM-DD', product, units, unit_price). The data ends on 2026-11-14.expectedOutput: "JSON object with revenue, top_products array, and growth_rate"agent: "data_analyst"write_report:
description: |
Using the sales analysis data, write an executive report in Markdown format. Include an executive summary, key metrics table, and 3 actionable recommendations.expectedOutput: "Markdown report saved to /output/weekly-report.md"agent: "report_writer"dependencies:
- "analyze_sales"deliverable:
path: "/output/weekly-report.md" # default source: tool_call — the agent writes it with file_write # source: final_message # or structured_output: the framework writes the file itself
/// <reference orkeon-script="1.0" />const analyst = agentBuilder()
.name("data_analyst")
.role("Sales Data Analyst")
.goal("Extract and analyze sales metrics from the database")
.backstory("Senior data analyst with 10 years of retail experience. Expert in SQL and statistical analysis.")
.tools(["relational_database_query", "csv_reader"])
.maxIterations(10)
.maxRpm(15)
.build();
const writer = agentBuilder()
.name("report_writer")
.role("Report Writer")
.goal("Transform analysis results into a clear executive report")
.backstory("Business communications specialist who turns data insights into actionable executive summaries.")
.tools(["file_write"])
.maxIterations(5)
.build();
const analyzeSales = taskBuilder()
.name("analyze_sales")
.description("Query the sales database for the last 7 days. Calculate: total revenue, top 5 products by units sold, week-over-week growth rate. Return structured JSON. The database is the SQLite file sales.db: provider_name 'Microsoft.Data.Sqlite', connection_string 'Data Source=sales.db'. Table sales(id, sale_date 'YYYY-MM-DD', product, units, unit_price). The data ends on 2026-11-14.")
.expectedOutput("JSON object with revenue, top_products array, and growth_rate")
.agent(analyst)
.build();
const writeReport = taskBuilder()
.name("write_report")
.description("Using the sales analysis data, write an executive report in Markdown format. Include an executive summary, key metrics table, and 3 actionable recommendations.")
.expectedOutput("Markdown report saved to /output/weekly-report.md")
.agent(writer)
.withContext(analyzeSales)
.deliverable({ path: "/output/weekly-report.md", source: "tool_call" })
.build();
const crew = crewBuilder()
.name("sales-report-crew")
.goal("Produce weekly sales analysis report")
.process("sequential")
.withAgents([analyst, writer])
.withTasks([analyzeSales, writeReport])
.planning(true)
.memory(true)
.verbose(true)
.build();
globalThis.crew = crew;
This file is not in the repository: it transcribes the YAML, and orkeon run crew.ork.ts --validate accepts it in version 1.0.0. Write a crew in TypeScript (new tab)
Program.csfrom docs/getting-started/overview
// Create the agentsvar analyst = newAgentBuilder()
.Role("Sales Data Analyst")
.Goal("Extract and analyze sales metrics from the database")
.Backstory("Senior data analyst with 10 years of retail experience. Expert in SQL and statistical analysis.")
.WithTool(relationalDatabaseQueryTool)
.WithTool(csvReaderTool)
.MaxIterations(10)
.MaxRpm(15)
.Build();
var writer = newAgentBuilder()
.Role("Report Writer")
.Goal("Transform analysis results into a clear executive report")
.Backstory("Business communications specialist who turns data insights into actionable executive summaries.")
.WithTool(fileWriteTool)
.MaxIterations(5)
.Build();
// Create the tasksvar analyzeTask = newCrewTaskBuilder()
.Description("Query the sales database for the last 7 days. Calculate: total revenue, top 5 products by units sold, week-over-week growth rate. Return structured JSON. The database is the SQLite file sales.db: provider_name 'Microsoft.Data.Sqlite', connection_string 'Data Source=sales.db'. Table sales(id, sale_date 'YYYY-MM-DD', product, units, unit_price). The data ends on 2026-11-14.")
.ExpectedOutput("JSON object with revenue, top_products array, and growth_rate")
.AssignTo(analyst)
.Build();
var reportTask = newCrewTaskBuilder()
.Description("Using the sales analysis data, write an executive report in Markdown format. Include an executive summary, key metrics table, and 3 actionable recommendations.")
.ExpectedOutput("Markdown report saved to /output/weekly-report.md")
.AssignTo(writer)
.DependsOn(analyzeTask)
.Build();
// Create the Crewvar crew = newCrewBuilder()
.Goal("Produce weekly sales analysis report")
.Sequential()
.WithAgent(analyst)
.WithAgent(writer)
.WithTask(analyzeTask)
.WithTask(reportTask)
.Planning(true)
.EnableMemory(true)
.Verbose(true)
.Build();
All three notations describe two agents, two tasks and a report written to /output; the same runtime executes them.
To run it, put the sample database (SQLite, two weeks of fictitious sales, 8 KB) next to crew.yaml, then run mkdir out && orkeon run crew.yaml --mount ./out:/output:rw. The accuracy of the report’s figures depends on the model.
YAML is declarative, without code; TypeScript (.ork.ts) is transpiled on the fly; C# integrates into a .NET application. You choose according to the complexity the team must handle, not the stage of the project.
An optional mounts: block names the team’s virtual folders; their rights, read-only or read-write, come from the configuration or from --mount. A folder that nothing provides gets the run refused.
Sequential, hierarchical, consensual and graph follow the declared dependencies, then the order of the file; in parallel mode, tasks with no dependency between them start together. In autonomous mode, the model dispatches them under the budget the team declares, with five dimensions: tool calls, delegation depth, duration, tokens, spawned agents.
Limits
An agent can be wrong: human review remains necessary where the stakes call for it.
The web tools reach the whole public web until the domain list is declared.
Without a declared budget, an autonomous run caps neither tokens nor duration; in the other modes, there is no token cap and no cost cap by default (Security).
Use cases
Three examples
Briefing
A weekly briefing, sent to a closed list
Four agents read the web and write a sourced report. The report goes to the drive, then only to the addresses on the list.
process: "sequential"maxRpm: 20mounts: ["/output"]
# appsettings, per account: Send.AllowedRecipients (mail), Rights (drive)
Open by default
The web tools reach the whole public web until the domain list is declared (Security).
This team has not yet been run in public, and the drive tools have yet to be proven on real accounts.Drive tools (new tab)
Mail
Mail sorted, replies left as drafts
An agent files unread mail and prepares replies as drafts. A person reviews them: the agent sends nothing.
A team generated from a sentence, adopted on your decision
orkeon forge composes the team, tries it in a sandbox and judges it against your criteria. By default, a generated team is adopted only after a person’s verdict.
$ orkeon forge "summarize my supplier's new offers
every morning"
Forging requires a configured model: orkeon init sets one up.