AntflyAntfly

Tree and Graph Navigation

How the retrieval agent explores a hierarchy or follows a graph path from a seed query, and how its budgets, permissions, and instructions apply

Navigation lets the retrieval agent move from a search hit through a table's structure instead of stopping at the hit. Configure it on steps.retrieval.navigation. strategy: "tree" explores branches of a hierarchy and can return to unvisited siblings; strategy: "graph" follows one path along graph edges. The main decision is which of the two matches your data.

curl -X POST http://127.0.0.1:8080/db/v1/agents/retrieval \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "Compare recovery options across the deployment runbook",
    "stream": false,
    "max_internal_iterations": 12,
    "generator": {"provider": "antfly", "model": "ggml-org/gemma-4-E4B-it-GGUF"},
    "queries": [{
      "table": "runbooks",
      "full_text_search": {"match": "deployment", "field": "title"},
      "filter_query": {"term": "published", "field": "status"},
      "fields": ["title", "body"]
    }],
    "steps": {
      "retrieval": {
        "navigation": {
          "query_index": 0,
          "strategy": "tree",
          "selection": "agentic",
          "index": "section_hierarchy",
          "start_key": "deployment-guide",
          "max_depth": 5,
          "beam_width": 3
        }
      },
      "generation": {}
    }
  }'

Tree Exploration#

index names the graph index whose edges form the hierarchy, such as parent and child sections, and query_index picks which entry in queries seeds the walk. With start_key, navigation starts at that document; without it, at the first search hit.

The agent calls search once to start, then navigate to choose one of the offered, unvisited keys. Siblings stay in the frontier while the agent explores another branch, so it can come back to them. max_depth counts from the start at depth zero, and beam_width bounds how many children each expansion offers.

Graph Paths#

For a workflow or any ordered path, use a graph index:

{
  "query_index": 0,
  "strategy": "graph",
  "selection": "agentic",
  "index": "workflow",
  "direction": "out",
  "edge_types": ["next"],
  "max_steps": 8,
  "neighbor_limit": 8
}

direction and edge_types apply at every hop. max_steps limits moves after the start node, and neighbor_limit bounds the candidates offered at each step.

Budgets#

Both agentic strategies share the request's model, conversation, iteration budget (max_internal_iterations), 20-tool-call cap, and context budget. Candidate lists are pruned to fit the context, and only offered keys can be selected. When the model or context budget runs out, the response has status: "incomplete" with the evidence and steps collected so far. Narrow fields when documents are large, so more candidates fit.

Permissions and Instructions#

The start document and every later read enforce the seed query's filters, authenticated row filters, and fields projection. Navigation never leaves the configured table. Tree navigation needs the tree_search tool permission and graph navigation needs graph_search, in addition to the seed query's permissions.

instruction adds a workflow rule for the model. instruction_field also reads a top-level string field from each visited document as an instruction; include that field in fields. Instructions accumulate alongside earlier evidence and cannot change permissions or budgets. Other fields and unvisited candidates are treated as untrusted evidence.

Ranked Trees Without a Model#

strategy: "tree" with selection: "ranked" walks the hierarchy deterministically, with no model call for navigation. Start from a literal start_key, from the seed results by omitting it, or from start_nodes: $roots, comma-separated keys, or a selector over a prior result. start_nodes is only available for ranked selection.

Reading the Result#

Visited documents are in hits, and the answer, when generation is set, is in generation. Agentic runs record steps named tree_navigation or graph_navigation; tree steps include the depth and the actual branch parent. With stream: true, the run emits the standard retrieval events. The query builder returns its query and retrieval_navigation separately; copy retrieval_navigation into this step.

Use Agent Skills#

Everything above is also encoded in the Antfly skill, so a coding agent can configure navigation for you:

npx skills add antflydb/antfly-skills

Then prompt it with the outcome, for example "answer questions over my runbooks by walking their section hierarchy from the best search hit", and use this page to judge the result.

Next Steps#