You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Declarative YAML agent systems with CEL routing for ADK Go
#2327
I'd like feedback on the shape of a declarative AgentSystem YAML document for ADK Go. Before opening a PR, I want to know whether this is a direction the maintainers would accept as an example, and what the document should look like if it later becomes a library under exp/.
The idea in one paragraph
One YAML document declares a root LlmAgent and its sub-agents. Those include Workflow agents with nodes and edges. All routing, loop control and state updates are CEL expressions in the document, so the Go host only registers models and calls loadSystem(doc, models). The loader validates everything before it builds anything: names, references, edges, routes, unconditional cycles, and type-checked CEL. It reports every problem with a field path, e.g. agents[1].nodes[5].vars[2].expr: vars.approvd is not declared before this expression. Then it builds plain llmagent / workflowagent / workflow.FunctionNode values. There is no new runtime.
The example system has a root agent studio that transfers to:
writer_critics: a writer, three critics in parallel, a join, and a CEL decide node that loops back with all the feedback or publishes after 3/3 approvals or 5 turns.
llm_router: an LLM classifies the message, and a CEL node routes to QUESTION / EXCLAMATION / DEFAULT branches. This is the YAML twin of examples/workflow/routing/llm.
Agents use Agent Config's field names: name, agent_class, model, instruction, sub_agents, output_key. Edges use adk-python's dict form from_node / to_node / route. The differences: model names a model the host registered, sub_agents and agent nodes refer to agents by in-document name rather than config_path, and only the explicit edge form is supported.
Open questions
Example vs. exp/ package. Should this land first as a self-contained examples/declarative, or go straight to exp/declarative with a public Load API?
The cel-go dependency. An example in the root module adds github.com/google/cel-go (pinned to v0.31.0, because v0.32 moves to cel.dev/cel-go) to the root go.mod. Is that acceptable, or should the example have its own go.mod?
Document envelope. Should it keep apiVersion: adk/v1alpha1 + kind: AgentSystem, or use a bare list of Agent Config entries?
Node identity. Nodes use id and agents use name. Should both use name?
Edge forms. Only explicit {from_node, to_node, route} maps are supported today. Should it also take adk-python's chain and routing-map shorthands?
CEL environment. Variables are state, session, user, invocation, input and earlier vars, plus the optional-types, strings, lists, math, sets, encoders and bindings extensions, with a cost limit. Is that too much or too little?
Per-request state. Session state outlives a request, so a loop counter has to be scoped to the invocation, as in turn_invocation above. Should the document have a first-class per-invocation scope instead?
Comments on any of these, or on the whole idea, are welcome.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
Tracking issue: #2326
I'd like feedback on the shape of a declarative AgentSystem YAML document for ADK Go. Before opening a PR, I want to know whether this is a direction the maintainers would accept as an example, and what the document should look like if it later becomes a library under
exp/.The idea in one paragraph
One YAML document declares a root
LlmAgentand its sub-agents. Those includeWorkflowagents with nodes and edges. All routing, loop control and state updates are CEL expressions in the document, so the Go host only registers models and callsloadSystem(doc, models). The loader validates everything before it builds anything: names, references, edges, routes, unconditional cycles, and type-checked CEL. It reports every problem with a field path, e.g.agents[1].nodes[5].vars[2].expr: vars.approvd is not declared before this expression. Then it builds plainllmagent/workflowagent/workflow.FunctionNodevalues. There is no new runtime.The example system has a root agent
studiothat transfers to:writer_critics: a writer, three critics in parallel, a join, and a CELdecidenode that loops back with all the feedback or publishes after 3/3 approvals or 5 turns.llm_router: an LLM classifies the message, and a CEL node routes toQUESTION/EXCLAMATION/DEFAULTbranches. This is the YAML twin ofexamples/workflow/routing/llm.The full document and the rationale are in #2326.
Where it follows adk-python
Agents use Agent Config's field names:
name,agent_class,model,instruction,sub_agents,output_key. Edges use adk-python's dict formfrom_node/to_node/route. The differences:modelnames a model the host registered,sub_agentsand agent nodes refer to agents by in-document name rather thanconfig_path, and only the explicit edge form is supported.Open questions
exp/package. Should this land first as a self-containedexamples/declarative, or go straight toexp/declarativewith a publicLoadAPI?github.com/google/cel-go(pinned to v0.31.0, because v0.32 moves tocel.dev/cel-go) to the rootgo.mod. Is that acceptable, or should the example have its owngo.mod?apiVersion: adk/v1alpha1+kind: AgentSystem, or use a bare list of Agent Config entries?idand agents usename. Should both usename?{from_node, to_node, route}maps are supported today. Should it also take adk-python's chain and routing-map shorthands?state,session,user,invocation,inputand earliervars, plus the optional-types, strings, lists, math, sets, encoders and bindings extensions, with a cost limit. Is that too much or too little?turn_invocationabove. Should the document have a first-class per-invocation scope instead?Comments on any of these, or on the whole idea, are welcome.
All reactions