Agent Genome & Versioning

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• services/api/scripts/seed_agents_and_datasets.py
• apps/web/src/app/(app)/agents/new/page.tsx
• services/api/flow/interfaces/http/routes/golden_sets.py
• apps/web/src/app/(app)/graph/page.tsx

The Agent Genome system in Flow provides a robust versioning and snapshotting architecture for agent configurations. Every agent in the platform is defined by its "genome"—a comprehensive snapshot of its instructions, model parameters, and enabled capabilities. This system ensures that every configuration change is tracked, allowing agents to evolve through an automated lifecycle of evaluation and promotion.

The primary purpose of the genome is to enable continuous improvement. By snapshotting versions as they change, the platform can run A/B tests, perform automated evaluations against Golden Sets, and roll back to known stable versions if performance degrades.
Sources: README.md:94-103, README.md:108-115

The Agent Genome Structure

A genome captures the complete state of an agent at a specific point in time. This includes structural templates, prompting logic, and the technical constraints of the Large Language Model (LLM) powering the agent.

Genome Components

The genome consists of several critical fields that define the agent's behavior:

Field	Description
template	The specific LangGraph graph template used (e.g., react-agent, deer_flow, tool-agent).
system_prompt	The primary instruction set and persona for the agent.
llm_config	Technical parameters including the provider (e.g., Anthropic), model name, and temperature.
tools	A JSON map of enabled functional tools (e.g., {"retrieve": true, "sandbox": false}).
skills	Specialized skill instructions embedded within the prompt.
state_schema	(Optional) Definition of the agent's internal state using TypedDict notation.
output_schema	(Optional) Pydantic-style definition for structured JSON outputs.

Sources: README.md:94-106, services/api/scripts/seed_agents_and_datasets.py:40-100

Version Lifecycle and Status

Agent versions follow a strict lifecycle managed by the system. This allows for safe testing of new prompt iterations or tool configurations without impacting the production "Active" version.

Status Transitions

Versions exist in one of three primary states:

1. CANDIDATE: A newly created or proposed version. This status is assigned to snapshots created by automatic prompt rewriting or manual configuration changes.
2. ACTIVE: The version currently utilized for live runs. Only one version can be ACTIVE at any given time per agent.
3. ARCHIVED: Previous active versions that have been replaced by a newer promoted candidate.

Sources: README.md:108-115, apps/web/src/app/(app)/graph/page.tsx:550-565

Automated Improvement Loop

The genome system is deeply integrated with an automated "Continuous Improvement Loop" that triggers nightly.

Evolution Process

The system uses the following logic to propose new genome versions:

1. Evaluation: Runs a Golden Set evaluation.
2. Failure Analysis: If the pass rate is below 0.7, failed items are extracted.
3. Prompt Rewriting: An LLM analyzes failures and proposes targeted edits to the system_prompt.
4. Candidate Creation: If changes meet a confidence threshold (≥ 0.3), a new CANDIDATE genome is snapshotted.
5. A/B Testing: The candidate is tested against the current ACTIVE baseline.
6. Proposal: If the candidate outperforms the baseline, a promotion proposal is created for human review.

Sources: README.md:118-132, services/api/flow/interfaces/http/routes/golden_sets.py:380-405

Golden Sets and Evaluation

Golden Sets are curated datasets of inputs and expected outputs used to benchmark the performance of different genome versions. These sets provide the ground truth needed to determine if a new version (Candidate) is superior to the current baseline (Active).

Golden Item Structure

Field	Type	Description
input_text	String	The user query or task sent to the agent.
expected_output	String	The target response or structured JSON the agent should produce.
scoring_criteria	String	Rubric used by the LLM judge to assign a score (0.0–1.0).

Sources: services/api/flow/interfaces/http/routes/golden_sets.py:30-70, services/api/flow/interfaces/http/routes/golden_sets.py:190-200

Configuration Management

When users create or edit agents via the UI, they are essentially modifying the template for the next genome version. The platform provides predefined templates to seed these genomes.

Predefined Genome Templates

• Second Brain: Optimizes for RAG with retrieve and long_term_memory enabled.
• Web Researcher: Configures the tool-agent template with tavily_search and fetch_webpage.
• Code Runner: Focuses on the sandbox tool for executing Python code.
• Paper Synthesizer: Specifically enables arxiv_search and hf_papers tools.

Sources: apps/web/src/app/(app)/agents/new/page.tsx:40-90, services/api/scripts/seed_agents_and_datasets.py:44-200

Conclusion

The Agent Genome and Versioning system provides a systematic approach to agent development. By treating configuration as a versioned "genome," Flow enables a scientific method of agent optimization—where prompts and tool configurations are treated as hypotheses to be tested, evaluated, and promoted only when they demonstrate measurable improvement over the current baseline.