Skip to main content

Design Principles

The Fundamental Rule​

The .agf.yaml file declares WHAT the agent needs. The runtime environment provides HOW those needs are met.

This single sentence governs every field placement decision. It has three direct consequences:

Portability​

An agent definition must produce identical semantic behavior on any compliant runtime. If a field's meaning changes depending on which Runtime Owner deploys the agent, it does not belong in the schema.

  • Portable: max_token_usage: 50000 — 50,000 tokens means the same thing everywhere.
  • Not portable: max_cost_usd: 5.00 — $5 buys radically different compute depending on model and provider.

Authoring-Time Knowledge​

The Agent Owner writes the YAML before knowing which runtime will execute it. If a field requires deployment-specific knowledge (network topology, identity provider, model pricing), the Agent Owner cannot set a meaningful value.

  • Known at authoring time: data_classification: confidential
  • Not known at authoring time: auth.type: oauth2 (depends on the Runtime Owner's identity provider)

WHAT vs. HOW Separation​

WHAT (Schema)HOW (Runtime)
"I need a tool called search"Which search implementation is bound
"Budget: 50k tokens"Which model consumes those tokens
"Execute with ReAct policy"How ReAct is implemented internally
"I depend on MCP server market_tools"Credentials, auth type, network routing
"Max delegation depth: 3"How depth is enforced in the call stack
"Prefer model gemini-2.5-pro"Which model is actually used (may differ based on availability)

Within the WHAT column, schema fields further divide into constraints (hard limits the runtime MUST honor, e.g., max_steps, max_token_usage) and preferences (intent the runtime SHOULD honor but MAY override, e.g., provider, model, temperature). This mirrors Kubernetes limits vs. requests — the scheduler guarantees limits but treats requests as best-effort. See Execution Policies for how this applies to ReactConfig.

The Three-Question Litmus Test​

Before any proposed field is accepted into the schema, it must pass all three questions. If any answer is "no," the field does NOT belong in the .agf.yaml schema.

Question 1: Authoring-Time Knowledge. Can the Agent Owner meaningfully set this value at YAML-authoring time, without knowledge of which Runtime Owner will execute the agent?

Question 2: Portability. Is the value portable — does it mean the same thing across different runtimes, SDKs, and model providers?

Question 3: WHAT vs. HOW. Does it declare WHAT the agent needs, not HOW the runtime should behave?

Worked Examples​

approval: true on a tool — ACCEPTED.

  • Q1 YES: The Agent Owner knows execute_trade is dangerous regardless of runtime.
  • Q2 YES: "Requires human approval" has the same meaning everywhere.
  • Q3 YES: Declares a safety property of the tool, not how approval is delivered.

endpoint: https://... on a remote agent — REJECTED.

  • Q2 NO: URLs differ between staging and production.
  • Q3 NO: Describes WHERE to connect, not WHAT the agent is.
  • Verdict: Runtime Configuration. The runtime maps the agent's alias to connection details.

data_classification: confidential — ACCEPTED.

  • Q1 YES: The Agent Owner knows their agent handles sensitive data.
  • Q2 YES: Standard vocabulary understood by all runtimes.
  • Q3 YES: Describes what data the agent handles, not how to protect it.

Four Placement Categories​

Every proposed field falls into exactly one of four categories:

CategoryIn .agf.yaml?Standardized?Example
Schema FieldYesYes (JSON Schema)metadata.name, constraints.budget.max_token_usage
Runtime SpecificationNoYes (standard shape)Usage object, AgentError, streaming protocol
Runtime ConfigurationNoNoMCP credentials, retry policies, model endpoint/deployment configuration
Out of ScopeNoNoKubernetes pod specs, CI/CD pipelines
Model fields

The provider and model fields in agf.react config are preferences, not runtime configuration. They express the Agent Owner's portable hint ("I'd like Gemini 2.5 Pro") that the runtime SHOULD honor but MAY override based on deployment policy, availability, or cost. This is distinct from runtime configuration such as model endpoint URLs, API keys, or deployment-specific routing — which are never in the schema.