π«π· Version franΓ§aise
See also: Full example Β· Tool inventory Β· Back to index
Porting guide β 5-step methodology
This guide details the methodology for porting an existing .NET application to an Orkeon agent-team architecture.
Overview
Porting consists of decomposing the responsibilities of a monolithic or modular application into specialized agent roles, equipped with tools, and orchestrated by one or more Crews.
Source application β Responsibility analysis β Mapping to agents
β Tool identification β Task definition β Porting plan
Choosing the approach: YAML-first or Code-first
Orkeon supports two approaches for defining a crew. The choice impacts the porting workflow.
| Criterion | YAML-first | Code-first (Fluent Builder) |
|---|---|---|
| Modification without recompilation | Yes β editing the YAML is enough | No β recompilation needed |
| Type safety | Runtime validation (CrewFactory) | Compile-time validation |
| Iterative prompt engineering | Fast β edit descriptions/backstories | Slower |
| Custom tools with dependencies | Requires separate DI registration | Direct instantiation possible |
| Sharing configurations | Portable YAML file | C# code to integrate |
| Reference examples | Over 100 runnable examples in examples/, most of them YAML (see the generated examples/INDEX.md) |
Builders documented in the docs |
Recommendation: favor the YAML-first approach for porting. YAML lets you iterate quickly on the prompts (descriptions, backstories) without touching the code. Custom tools remain in C# and are registered via DI.
YAML-first workflow
1. Write config.yaml (agents, tasks, process type β see the YAML schema)
2. Identify the missing tools
3. Code the custom tools (ToolBase<TReq, TRes>)
4. Register via DI (AddSingleton<IBaseTool, MyTool>()) β the default tool
registry of AddOrkeonInfrastructure() reads it, so YAML names resolve
5. Load and run β the YAML path is a virtual path, read through the VFS:
var crew = await crewFactory.CreateFromFileAsync("/crews/config.yaml");
var output = await orchestrator.KickoffAsync(crew.Id, input);
6. Iterate on the prompts in the YAML
While the crew only uses built-in tools, no host code is needed at all: orkeon run config.yaml --validate loads it with strict tool resolution (no LLM call), and orkeon run config.yaml runs it β the runner reads the Llm section, mounts the folders and registers the DI-backed tool registry itself (see the CLI reference). The host of section 5.5 becomes necessary once custom C# tools enter the port. The YAML keys are listed in the YAML schema.
Step 1 β Analyze the source application's responsibilities
1.1 Inventory the components
List all the application's services, controllers, handlers and modules. For each component, note its main responsibility, its incoming and outgoing dependencies, and the type of data it handles.
1.2 Identify the data flows
Trace the journey of the data through the application: where it comes from (files, API, database), which transformations it undergoes, where it ends up (storage, API, UI).
1.3 Classify the responsibilities
Categorize each responsibility according to this grid:
| Category | Description | Examples |
|---|---|---|
| Collection | Acquiring data from external sources | API calls, file reads, web scraping, DB queries |
| Analysis | Processing, transforming, enriching data | Parsing, computations, aggregations, pattern detection |
| Decision | Business logic, rules, conditional routing | Validation, scoring, classification, prioritization |
| Production | Generating output artifacts | Reports, emails, files, API responses |
| Coordination | Orchestrating sub-processes | Workflow management, sequencing, parallelization |
1.4 Identify human interactions
Spot the points where the application requires human intervention (validation, input, approval). These points will become tasks with HumanInput = true in Orkeon (humanInput: true in YAML). The flag hands the agent the human_input tool for that task, so the host must register one: orkeon run surfaces the question on its run event bus, and a hand-built host calls AddOrkeonHumanInput<TProvider>() with its own IHumanInputProvider (the parameterless AddOrkeonHumanInput() auto-approves). Without a registered human_input tool the flag is a no-op (TaskToolbelt.Compose adds the tool to the task's belt only when the host registered one).
Step 2 β Map the responsibilities to agent roles
2.1 Decomposition principles
A good Orkeon agent follows these principles:
- Single responsibility: each agent has a clear, specialized role (defined by
AgentRole) - Measurable objective: the goal (
AgentGoal) describes a concrete, verifiable result - Autonomy: the agent must be able to accomplish its tasks with its tools without depending on another agent for every operation
- Appropriate granularity: neither too broad (a "does everything" agent) nor too narrow (an agent that performs a single trivial operation)
2.2 Mapping template
For each responsibility identified in Step 1, fill in this template:
Source responsibility : [description]
β Agent role : [AgentRole β concise specialist name]
β Agent goal : [AgentGoal β expected result]
β Backstory : [AgentBackstory β context and expertise]
β Required tools : [list of tools]
β Constraints : [MaxIterations, MaxRpm, AllowDelegation]
2.3 Common mapping patterns
| Source pattern | Orkeon mapping |
|---|---|
| Service that reads and transforms data | "Data Analyst" agent with file/DB tools |
| Service that calls external APIs | "API Integrator" agent with HttpApiTool |
| Service that generates reports | "Report Writer" agent with FileWriteTool |
| Controller that orchestrates a workflow | Crew with ProcessType.Sequential |
| Validation / review service | "Quality Reviewer" agent with JSON output validation |
| Scheduler / batch processor | Crew with KickoffForEachAsync (batch) |
| Service that routes work to specialists at runtime | Hierarchical crew with LlmBasedManager |
| Service with explicit branching or retry loops | Graph crew (StateGraph<TState>, conditional edges, controlled cycles) |
| Open-ended job whose steps are not known in advance | Autonomous crew (a manager LLM assigns each task; a failed task goes to a peer agent within a crew-wide delegation depth; extra agents only through a host-registered SpawnAgentTool; all bounded by AgentExecutionBudget) |
2.4 When to create an agent vs. a tool
| Create an agent when... | Create a tool when... |
|---|---|
| The responsibility requires reasoning, analysis or creativity | The operation is deterministic and mechanical |
| The result varies with the context and the data | The operation always follows the same algorithm |
| Several reflection steps are needed | It is an atomic operation (input β output) |
| Interacting with an LLM adds value | An LLM would add nothing over an algorithm |
Step 3 β Identify the required tools
3.1 Inventory the tool needs
For each agent defined in Step 2, list the concrete operations it must perform. For each operation, check whether an existing tool covers it (see Tool inventory).
3.2 Decision matrix: reuse vs. create
| Criterion | Reuse the existing | Create a new tool |
|---|---|---|
| The operation is covered by an Orkeon tool | Yes | β |
| The existing operation is almost suitable but lacks a parameter | Consider a contribution/extension | β |
| The operation requires a call to a specific business API | β | Yes β inherit from HttpToolBase<> |
| The operation handles an unsupported file format | β | Yes β inherit from FileToolBase<> |
| The operation is a pure business computation | β | Yes β inherit from ToolBase<> |
3.3 Existing tools by common need
The YAML name is what a crew lists under an agent's tools:.
| Need | Existing tool | YAML name | Package / registration |
|---|---|---|---|
| Read a text/JSON/XML file | FileReadTool |
file_read |
Orkeon.Tools.FileSystem β AddOrkeonFileSystemTools() |
| Write a file | FileWriteTool |
file_write |
Orkeon.Tools.FileSystem β AddOrkeonFileSystemTools() |
| List a directory | DirectoryReadTool |
directory_read |
Orkeon.Tools.FileSystem β AddOrkeonFileSystemTools() |
| Search within files | DirectorySearchTool |
directory_search |
Orkeon.Tools.FileSystem β AddOrkeonFileSystemTools() |
| Read a CSV | CsvReaderTool |
csv_reader |
Orkeon.Tools.Data β AddOrkeonDataTools() |
| Read a PDF | PdfReaderTool |
pdf_reader |
Orkeon.Tools.Data β AddOrkeonDataTools() |
| Read a DOCX | DocxReadTool |
docx_reader |
Orkeon.Tools.Data β AddOrkeonDataTools() |
| Read / write an Excel (.xlsx) | XlsxReadTool / XlsxWriteTool |
xlsx_reader / xlsx_writer |
Orkeon.Tools.Data β AddOrkeonDataTools() |
| Manipulate JSON | JsonTool |
json_tool |
Orkeon.Tools.Data β AddOrkeonDataTools() |
| SQL query | RelationalDatabaseTool |
relational_database_query |
Orkeon.Tools.Data β AddOrkeonDataTools() |
| MongoDB query | MongoDbTool |
mongodb_query |
Orkeon.Tools.Data β AddOrkeonDataTools() |
| Web search | WebSearchTool / BraveSearchTool |
web_search / brave_search |
Orkeon.Tools.Web β opt-in AddOrkeonWebSearchTool() / AddOrkeonBraveSearchTool(apiKey) |
| Web scraping | WebScrapeTool |
web_scrape |
Orkeon.Tools.Web β AddOrkeonWebTools() |
| REST API call | HttpApiTool |
http_api |
Orkeon.Tools.Web β AddOrkeonWebTools() |
| Run a shell command | ShellCommandTool |
shell_command |
Orkeon.Tools.Code β AddOrkeonCodeTools() |
| Execute C# code | SecureCodeInterpreterTool |
code_interpreter |
Orkeon.Infrastructure β registered as a concrete type only: add services.AddSingleton<IBaseTool>(sp => sp.GetRequiredService<SecureCodeInterpreterTool>()) for a YAML crew to resolve it by name |
| Read, draft or send e-mail | the 13 email_* tools |
email_read, email_draft, email_send, β¦ |
Orkeon.Tools.Email β AddOrkeonEmailTools(configuration) (see E-mail tools) |
| Ask a colleague | AskQuestionTool |
ask_question_to_coworker |
Orkeon.Infrastructure β given per agent when AllowDelegation is on |
| Delegate a task | DelegateWorkTool |
delegate_work_to_coworker |
Orkeon.Infrastructure β given per agent when AllowDelegation is on |
| Semantic search | SearchTool |
semantic_search |
Orkeon.Infrastructure β opt-in AddSemanticSearchTool() (Orkeon.Hosting; orkeon run calls it) |
| RAG over documents | RagSearchTool |
rag_search |
Orkeon.Tools.Rag (opt-in: AddOrkeonRag + AddOrkeonRagTools) |
Step 4 β Define the tasks and the orchestration flow
4.1 Decompose into tasks
Each expected output of the crew becomes a CrewTask. A task is defined by its TaskDescription (what the agent must do) and its ExpectedOutput (format and content of the expected result).
4.2 Choose the ProcessType
| Situation | Recommended ProcessType |
|---|---|
| The steps must chain, each output feeding the next input | Sequential |
| A manager must dynamically route tasks to the most competent agents | Hierarchical |
| Several independent tasks can run simultaneously | Parallel |
| The agents must vote and reach a consensus | Consensual |
| The flow branches on conditions or loops until a check passes | Graph |
| A manager LLM routes each task, a failed task gets a second chance with a peer, all within a budget | Autonomous |
In YAML the mode is the crew's process: key (sequential, hierarchical, parallel, consensual, graph, autonomous); with the builder, .Sequential(), .Hierarchical(), .Parallel(), .Consensual() or .Process(ProcessType.Graph) / .Process(ProcessType.Autonomous). See the Graph and Autonomous orchestration guides for the last two.
4.3 Define the dependencies
Use CrewTaskBuilder.DependsOn() (YAML: dependencies:) to express prerequisites between tasks. In Sequential mode the declaration order is enough, and declared dependencies reorder it when they disagree. In Parallel mode the dependencies split the tasks into waves: the tasks whose prerequisites are met run together, and the next wave starts when they are done, with their outputs in context.
4.4 Configure the execution options
For each task, decide on: the priority (TaskPriority), human intervention (HumanInput, see 1.4), the output validation schema (OutputJson), and the output file (the YAML deliverable: block β path, source, format, optional schema: with the default source: tool_call the agent writes it and needs a tool that writes it, such as file_write; final_message or structured_output make the framework write it β see deliverables checked at load). AsyncExecution (asyncExecution:, CrewAI's async_execution) is honoured by process: sequential β the task runs alongside the tasks after it, and a task that depends on it waits for it β and accepted without an effect of its own by process: parallel; the four other modes refuse it at load (see Asynchronous tasks).
Step 5 β Produce the porting plan
5.1 Plan template
| Source component | Responsibility | Target agent | Role | Required tool(s) | Status | Effort |
|---|---|---|---|---|---|---|
OrderService |
Order validation | Order Validator | "Order Validation Specialist" | RelationalDatabaseTool, custom tool ValidateOrderTool |
To create (custom tool) | M |
PricingEngine |
Price computation | Pricing Analyst | "Pricing Specialist" | CsvReaderTool, JsonTool |
Ready (existing tools) | S |
| ... | ... | ... | ... | ... | ... | ... |
5.2 Effort legend
| Code | Meaning | Estimated duration |
|---|---|---|
| XS | Direct mapping to an existing tool, no code | < 1h |
| S | Simple agent with existing tools | 1-4h |
| M | Agent + 1 simple custom tool | 0.5-1 day |
| L | Agent + complex custom tool or external integration | 1-3 days |
| XL | Significant refactoring, multiple custom tools | > 3 days |
5.3 Status columns
| Status | Meaning |
|---|---|
| Ready | All tools exist, configuration only |
| To create (tool) | One or more custom tools must be developed |
| To create (agent) | The agent requires specific backstory/prompt engineering |
| Blocked | Unresolved external dependency |
5.4 Plan validation checklist
Before starting the implementation, verify that:
- Every responsibility of the source application is covered by at least one agent
- Every agent has at least one assigned task
- All dependencies between tasks are explicit
- Missing tools are identified with an estimated effort
- The
ProcessTypeis justified by the nature of the workflow - Human intervention points are identified (
HumanInput = true) - Memory is enabled if the crew should remember its earlier runs (
EnableMemory(true),memory: true) β not for the context between the tasks of one run, which the previous outputs already carry into each prompt - The rate-limiting constraints (
MaxRpm) are compatible with the external APIs used
5.5 Minimal DI setup for the port
A port that brings its own C# tools runs in its own host. Every such host needs this dependency-injection setup:
using Microsoft.Extensions.Configuration;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.Logging;
using Orkeon.Application.DependencyInjection;
using Orkeon.Domain.SharedKernel.ValueObjects;
using Orkeon.Domain.Tools;
using Orkeon.Hosting;
using Orkeon.Infrastructure.DependencyInjection;
using Orkeon.Infrastructure.FileSystem;
using Orkeon.Infrastructure.LLMs;
using Orkeon.Tools.Code.DependencyInjection;
using Orkeon.Tools.Data.DependencyInjection;
using Orkeon.Tools.FileSystem.DependencyInjection;
using Orkeon.Tools.Web.DependencyInjection;
var host = Host.CreateDefaultBuilder(args)
// Same environment overlay as the runners: ORKEON_Llm__ApiKey β Llm:ApiKey
.ConfigureAppConfiguration(config => config.AddEnvironmentVariables("ORKEON_"))
.ConfigureServices((context, services) =>
{
// Required β Application and Infrastructure layers
services.AddOrkeonApplication();
services.AddOrkeonInfrastructure(context.Configuration);
// Required β the virtual file system every tool and the YAML loader go through
// (mounts declared under Orkeon:FileSystem:Mounts, e.g. "/srv/app/crews:/crews:ro")
services.AddOrkeonFileSystem(context.Configuration);
// Tool suites β add only the ones you need
services.AddOrkeonFileSystemTools(); // If agents read/write files
services.AddOrkeonDataTools(); // If agents handle CSV, PDF, JSON, SQL, MongoDB
services.AddOrkeonWebTools(); // If agents scrape pages or call HTTP APIs
services.AddOrkeonCodeTools(); // If agents execute shell commands
// Custom tools identified in Step 3
services.AddSingleton<IBaseTool, MyCustomTool1>();
services.AddSingleton<IBaseTool, MyCustomTool2>();
// YAML tool names resolve against these IBaseTool registrations: the default
// ToolRegistry of AddOrkeonInfrastructure() reads them β nothing more to register.
// LLM β a hand-built host reads no Llm section by itself: build the provider here.
// Use the provider class of your vendor (OpenAILlmProvider, AnthropicLlmProvider, ...).
var llm = LlmConfig.Create(
context.Configuration["Llm:Model"] ?? "gpt-5.6-sol",
context.Configuration["Llm:ApiKey"]);
services.AddOrkeonLlmProvider(
sp => new OpenAILlmProvider(llm,
sp.GetRequiredService<IHttpClientFactory>(),
sp.GetRequiredService<ILogger<OpenAILlmProvider>>()),
llm);
})
.Build();
AddOrkeonLlmProvider comes after AddOrkeonInfrastructure: it registers the provider on the three surfaces the runtime consumes (ILlmProvider, IBasicLlmProvider, IChatClient), metered, and the last registration wins. A mount whose folder lies outside the working directory must also be listed under PathSecurity:AdditionalAllowedDirectories. orkeon run does all of the above from the settings file (see Configuration).
5.6 Execution pattern
// ICrewFactory is scoped: resolve it from a scope
using var scope = host.Services.CreateScope();
var services = scope.ServiceProvider;
// Load the crew from the YAML (a virtual path, under a declared mount)
var crewFactory = services.GetRequiredService<ICrewFactory>();
var crew = await crewFactory.CreateFromFileAsync("/crews/config.yaml");
// Prepare the input with execution variables (task templates {date}, {environment})
var input = CrewInput.WithStringVariables(
"Initial context for the execution",
new Dictionary<string, string>
{
["date"] = DateTime.Today.ToString("yyyy-MM-dd"),
["environment"] = "production"
});
// Run and retrieve the results β KickoffAsync never throws: a failure comes back
// as Succeeded = false with its reason in Error
var orchestrator = services.GetRequiredService<ICrewOrchestrationService>();
var output = await orchestrator.KickoffAsync(crew.Id, input);
// Use the results
if (output.Succeeded)
{
// Success β process the final result
Console.WriteLine(output.FinalOutput);
}
else
{
// Failure β the reason, then the failed tasks
Console.Error.WriteLine($"Crew failed: {output.Error}");
foreach (var failed in output.TaskOutputs.Where(t => !t.Success))
Console.Error.WriteLine($"Task {failed.TaskId} failed: {failed.Content}");
}