Resource Reference

Resource Reference#

Warning

Project Neo is currently in Technical Preview. Features described in this section may change before general availability.

Configuration is made up of typed resources, and each kind has its own set of fields. This page is the field-by-field reference for every kind: which fields are required, their types, their allowed values and defaults, and a minimal working example for each. For the conceptual model behind resources and preferences, see the Overview page. For the authoring workflow and worked examples, see the Authoring Agents page.

Common Structure#

Every authored file begins with the same envelope:

kind

The resource kind, for example Model or Agent. Case-sensitive, and it must match the exact spelling used in this reference.
schema

The schema version of the kind. The current version is v1.
metadata.id

The identifier for the resource, such as claude-sonnet. Two resources of the same kind cannot share one. Whether you write it depends on the kind. A project can hold any number of Model, Agent, MCP, KnowledgeGraph, and TraitDimension resources, so each one needs an identifier to tell it apart from the rest. The remaining three kinds occur once at most, so they carry no identifier: every project has exactly one Project, and DocumentSourceSettings and CodeInterpreter are each written once or left out.

An identifier consists of letters, digits, underscores, and hyphens, and it starts with a letter. Letters can be upper or lower case. For example, claude-sonnet, deep_research, kg2, and Assistant are valid, while 2nd-model starts with a digit, deep research contains a space, company.kg contains a dot, and research! contains a symbol, so all four are rejected at deploy.

The resource kinds that surface in the Chat interface also accept two optional display fields, title and summary. Both are cosmetic labels shown in pickers and detail views, and neither affects how a request resolves. When title is omitted, the Chat interface falls back to the resource identifier.

The fields of each kind are a fixed set, and every resource forbids unknown fields. A misspelled field name, or a custom field of your own such as internalref: EDFGGA654, causes the deploy to fail rather than being silently ignored. To attach your own reference to a resource, add a YAML comment, which the parser ignores and which stays in your version-controlled files. To attach metadata to a whole deploy instead, use a deploy label, described on the CLI Reference page. For example, a comment records the internal reference without adding a field:

---
kind: Agent
schema: v1
metadata:
  id: research
# internalref: EDFGGA654
entrypoint: true
---

You are a research analyst...

Writing a Description#

Several kinds also accept a description, and on two of them it is not a display field. Where title and summary are written for people, these descriptions are written for the agents. A KnowledgeGraph description is advertised to an agent alongside the graph identifier and title, so it is what the agent goes on when deciding whether to query that graph rather than another. An Agent description is what a calling agent reads when choosing among the delegates available to it. In both cases a vague description does not merely read poorly, it leads the agent to the wrong choice or to no choice at all.

Write it as a selection rule rather than a label. Say what the resource covers and when to reach for it. This description gives an agent enough to act on:

description: Company product and organizational graph. Query it for team ownership, reporting lines, and product hierarchy.

Whereas this one names the resource without saying when it applies:

description: Company knowledge graph.

Three habits keep descriptions useful:

Name the boundary, not just the subject. What the resource does not cover is as informative as what it does, because it tells the agent when to look elsewhere.
Keep them distinct from each other. Two delegates with near-identical descriptions give a calling agent no basis to choose between them, and it will pick one more or less at random.
Describe, do not insist. Wording such as always use this first pushes an agent to reach for a resource in situations it does not fit. State the fit and let the agent judge.

A description is optional on most kinds, but it is required on any agent with delegate: true. A deploy fails without one, because a calling agent would have nothing to go on when choosing among delegates.

Predicate Syntax for Constraints#

Both the Project and an Agent accept a constrains block, which restricts the values a preference path allows. The block is keyed by preference path, and each entry is a predicate written in the small language below.

Predicate	Meaning
`in`	The value must be one of a list, for example `{in: [claude-sonnet, claude-opus]}`.
`not_in`	The value must not be one of a list.
`gt`, `ge`, `lt`, `le`	Numeric comparisons: greater than, greater than or equal, less than, less than or equal.
`matches`	The value must match an anchored regular expression, for example `{matches: "claude-.*"}`.

Three paths constrained at once:

constrains:
  inference.model:
    in: [claude-sonnet, claude-opus]
  source.documents.limit:
    le: 50
  trait.style:
    not_in: [verbose]

A predicate can carry several clauses, and a value has to satisfy all of them. This one admits a limit from 10 to 50:

constrains:
  source.documents.limit:
    ge: 10
    le: 50

Clauses that contradict each other admit no value at all, so genai lint rejects them rather than letting you deploy a path nothing can satisfy. ge: 50 together with lt: 10 is reported as unsatisfiable.

A value that falls outside a predicate does not fail the request. The resolver passes over it and carries on to the next source, so an agent that constrains inference.model to two models simply ignores a user who asks for a third, and answers with whatever the agent or the project prefers instead.

Note

The pattern in a matches constraint is an anchored regular expression that must match the entire value. It is a different language from the shell-style wildcards used in conditional segments of agent instructions.

Authentication#

The Model and KnowledgeGraph kinds reach external services through an auth block that accepts any of the variants below. The CodeInterpreter kind authenticates the same way, but accepts only the bearer variant, nested under backend.auth. The block never contains credential material. Instead, a variant that needs a credential carries a secret handle, a name bound to a credential stored securely on the cluster. The platform resolves the handle at request time. For how to register a handle, see the Registering a Handle section.

When the auth block is omitted, the connection is unauthenticated. When it is present, type is required and selects one of the following variants.

`type`	Fields	Description
`bearer`	`secret`	Static bearer-token authentication. `secret` is the handle that resolves to the token.
`basic`	`secret`	HTTP basic authentication. `secret` resolves to the user name and password pair.
`aws_sigv4`	`secret`, `region`	AWS Signature Version 4 authentication, for example for Amazon Bedrock. `secret` resolves to the AWS credentials, and `region` is the signing region.
`oauth`	none	OAuth authentication, where each user authorizes the service themselves rather than sharing one credential. The platform stores each user token and uses the one belonging to the person making the request, so there is no `secret` handle to declare and nothing for an operator to register.

A minimal bearer block:

auth:
  type: bearer
  secret: anthropic_token

Registering a Handle#

A handle is a name, not a value. You author the name in the auth block, and the name travels in the deployed configuration. The credential itself is bound to the handle separately, on the cluster, and never appears in the project. This split means the person who authors the configuration does not need to hold the provider API key, and the key is never committed to version control.

Registering a handle is a two-part responsibility:

You (the configuration author) choose a handle name and reference it from the auth block of a Model, KnowledgeGraph, or CodeInterpreter resource.
An operator binds that handle to the real credential on the cluster, using the mechanism below. Binding is a deployment operation, so it is performed by whoever manages the GenAI service configuration, not from within the project.

During Technical Preview, the operator provides the credential to the GenAI service as an environment variable whose name is SQ_ followed by the handle name in uppercase. For the handle anthropic_token, the variable is SQ_ANTHROPIC_TOKEN. The variable set depends on the auth type:

`auth.type`	Environment variables for a handle named `<handle>`
`bearer`	`SQ_<HANDLE>` holds the token.
`basic`	`SQ_<HANDLE>_USERNAME` and `SQ_<HANDLE>_PASSWORD`.
`aws_sigv4`	`SQ_<HANDLE>_ACCESS_KEY_ID` and `SQ_<HANDLE>_SECRET_ACCESS_KEY`, with an optional `SQ_<HANDLE>_SESSION_TOKEN`.
`oauth`	None. Each user authorizes the service themselves, so there is no shared credential and no handle to bind.

Deploy verifies that every referenced handle resolves and that the resolved credential matches the auth type. A handle that is missing or unbound fails the deploy with a 422 response, and the previous snapshot stays in place. A handle that resolves at deploy time but is later removed causes the resource that references it to become unavailable at runtime.

Rotating or revoking a credential is done at the cluster, by replacing the bound value. The project is not affected and does not need to be redeployed, because it references the handle name, not the value.

Project#

The project manifest, introduced on the Overview page. Every configuration must have exactly one, so a deploy fails if it carries none and fails again if it carries two. A Project has no metadata.id, and by convention it is written in a file named project.yaml, although the platform reads the kind rather than the file name.

Field	Type	Requirement	Description
`prefers`	map of path to value	Optional, empty by default	Project-wide soft defaults, keyed by preference path.
`constrains`	map of path to predicate	Optional, empty by default	Project-wide restrictions on which values a path allows. See the Predicate Syntax for Constraints section.
`pins`	map of path to value	Optional, empty by default	Project-wide locked values that nothing can override.
`instructions`	string	Optional	A default chat body used when a request resolves without a selected agent.
`context_budget`	object	Optional, defaults listed below	Policy that keeps each turn within the model context window.
`hitl`	object	Optional, no rules by default	Operator approval policy for tool calls.
`title` / `summary`	string	Optional	Display label and description.

The context_budget object controls two independent safety behaviors. It is policy, not a preference, so a user or a request cannot turn it off.

Field	Type	Default	Description
`tool_output_pruning`	boolean	`true`	Clear older tool results once their token count crosses the trigger.
`tool_output_pruning_trigger_tokens`	integer	`100000`	Token count above which older tool results are cleared. Match it to the window of the models you run.
`keep_recent_tool_results`	integer	`4`	Number of most-recent tool results never cleared by pruning.
`turn_truncation`	boolean	`true`	Drop the oldest whole turns when the input approaches the model context window.
`turn_truncation_trigger_fraction`	number	`0.9`	Fraction of the context window that turn truncation aims to stay below.
`keep_recent_turns`	integer	`4`	Number of most-recent turns that turn truncation always preserves.

The hitl object holds an ordered list of approval rules. Each rule matches a tool by name and assigns a disposition. The last matching rule wins. For what the dispositions mean and how these rules combine with the rules on a scheduled task, see the Scheduled Tasks and Approvals page.

Field	Type	Requirement	Description
`pattern`	string	Required	A glob matched against the tool name visible to the model.
`disposition`	string	Required	One of `approve` (let the call run without asking anyone), `reject` (refuse the call), `interactive` (ask the person in the conversation to approve the call), `defer` (park the run and wait for someone to approve the call later), or `hide` (take the tool away from the agent).

Example, the manifest authored as project.yaml:

kind: Project
schema: v1
title: Research workspace

prefers:
  inference.model: claude-sonnet

context_budget:
  turn_truncation: true
  tool_output_pruning: true

hitl:
  rules:
    - pattern: "delete_*"
      disposition: reject
    - pattern: "send_email"
      disposition: approve

Model#

An agent, a user, or a request selects a model through the inference.model preference, whose value is the metadata.id of a Model resource.

Field	Type	Requirement	Description
`provider`	string	Required	The model provider, for example `anthropic` or `openai`.
`model_name`	string	Required	The model identifier as the provider publishes it, for example `claude-sonnet-5`. For where to find it, see the Model Providers section.
`auth`	object	Optional	The authentication block used to reach the provider. See the Authentication section.
`description`	string	Optional	Prose describing the model, recorded in the configuration for your own reference.
`group`	string	Optional	A label for grouping models in the Chat interface.
`backend_kwargs`	map	Optional, empty by default	Additional provider parameters passed through to the model backend.
`enable_reasoning`	boolean	Optional, default `false`	Authorizes the platform to send reasoning parameters to this model. Leave off unless the model supports reasoning at the provider and version you have configured.
`enable_image_input`	boolean	Optional, default `false`	Authorizes this model to receive image content. Leave off unless the model accepts images at the provider and version you have configured.
`context_window`	integer	Optional, the provider profile by default	Maximum input tokens the model accepts, used by the context budget. Set it to the real window for smaller-window models so truncation engages before the provider rejects the request.
`title` / `summary`	string	Optional	Display label and description.

Example, a model authored as models/claude-sonnet.yaml:

kind: Model
schema: v1
metadata:
  id: claude-sonnet

provider: anthropic
model_name: claude-sonnet-5
auth:
  type: bearer
  secret: anthropic_token

Model Providers#

On a Model resource, provider selects which backend the platform routes to. The platform supports the following providers. A provider value outside this set is not rejected at deploy time. Instead, the model fails when a request first tries to use it, so check the spelling against the table below.

`provider`	Example `model_name`	Notes
`anthropic`	`claude-sonnet-5`	Anthropic Claude models.
`openai`	the OpenAI model ID	OpenAI models.
`google`	the Gemini model ID	Google Gemini models.
`azure`	the Azure deployment name	Azure OpenAI. Supply the endpoint, API version, and deployment name through `backend_kwargs`.
`cerebras`	the Cerebras model ID	Cerebras-hosted models.

Write model_name exactly as the provider spells it. The platform does not check the name at deploy, so a typo surfaces only when a request first tries to use the model. Take the value from the model list in the API documentation of the provider rather than from memory or from another tool, because providers rename and retire models over time.

Each supported provider authenticates with a bearer token. Set auth.type to bearer and reference a secret handle bound to the provider API key. For the full authentication reference, see the Authentication section.

Provider-specific parameters, such as sampling options or the Azure endpoint, API version, and deployment name, are passed through backend_kwargs. The platform forwards these to the provider as written, and a user or a request cannot override them.

Example, an OpenAI model authored as models/gpt-5.yaml:

kind: Model
schema: v1
metadata:
  id: gpt-5

provider: openai
model_name: gpt-5.2
auth:
  type: bearer
  secret: openai_token

Example, a Google Gemini model with a provider-specific parameter, authored as models/gemini-flash.yaml:

kind: Model
schema: v1
metadata:
  id: gemini-flash

provider: google
model_name: gemini-3.5-flash
auth:
  type: bearer
  secret: google_token
backend_kwargs:
  temperature: 0.2

Agent#

An agent is authored in one of two file formats. A .md agent carries its instructions as the markdown body after the frontmatter. A .yaml agent carries configuration only and is typically used as a shared template through extends.

Field	Type	Requirement	Description
`prefers`	map of path to value	Optional, empty by default	Soft defaults the user can override.
`constrains`	map of path to predicate	Optional, empty by default	Restrictions on which values a path allows for this agent. See the Predicate Syntax for Constraints section.
`pins`	map of path to value	Optional, empty by default	Locked values that nothing can override.
`extends`	list of identifiers	Optional, empty by default	Parent agents whose configuration folds into this one. Configuration composes through `extends`, instructions do not.
`description`	string	Required with `delegate: true`	Prose that a calling agent reads to decide whether to call this agent.
`entrypoint`	boolean	Optional, default `false`	Whether the agent appears in the conversation picker for users to select.
`delegate`	boolean	Optional, default `false`	Whether another agent can call this agent as a subagent.
`entrypoint_order`	integer	Optional	Display order in the picker for entrypoints, ascending, starting at zero.
`opening`	string	Optional	A static first message the agent speaks before the user does. When absent, the user starts the conversation.
`pin_to_conversation`	boolean	Optional, default `false`	When set, selecting this agent fixes it for the conversation, and later turns ignore attempts to switch agents.
`title` / `summary`	string	Optional	Display label and description.

Example, an agent authored as a markdown file named agents/assistant.md. The --- lines fence the frontmatter, which is YAML and holds the fields listed above. Everything after the closing fence is markdown, and it becomes the agent instructions:

---
kind: Agent
schema: v1
metadata:
  id: assistant
entrypoint: true
prefers:
  inference.model: claude-sonnet
---

You are a helpful assistant. Answer questions clearly and concisely.

Example, a template authored as agents/house-style.yaml. A .yaml agent has no fences and no instructions, so the whole file is the field block. Because entrypoint and delegate both default to false, a template never appears in the picker and no agent can call it as a subagent:

kind: Agent
schema: v1
metadata:
  id: house-style

prefers:
  trait.style: concise
pins:
  capability.code_interpreter.enabled: false

Another agent, agents/research.md, folds that template in through extends and adds its own instructions:

---
kind: Agent
schema: v1
metadata:
  id: research
entrypoint: true
extends:
  - house-style
---

You are a research analyst. Cite a source for every claim.

TraitDimension#

A TraitDimension resource groups reusable prompt fragments under one name. The metadata.id is the dimension name, and it appears in preference paths as trait.<id>. Agents and the project activate a trait through the trait.<dimension> preference.

Field	Type	Requirement	Description
`traits`	map of identifier to trait	Required	The trait entries in the dimension, each keyed by a unique identifier.

Each trait entry carries the following fields:

Field	Type	Requirement	Description
`prompt_fragment`	string	Required	The prose appended to the agent instructions when this trait is active.
`title` / `summary`	string	Optional	Display label and description.

Example, a dimension authored as trait-dimensions/style.yaml. Markdown is only for agents, so every other kind, including this one, is written as YAML with no frontmatter fences:

kind: TraitDimension
schema: v1
metadata:
  id: style

traits:
  concise:
    prompt_fragment: |
      Keep your responses tight. No preamble, no recap.
  detailed:
    prompt_fragment: |
      Be exhaustive. Walk through your reasoning and cite each step.

KnowledgeGraph#

A KnowledgeGraph resource points at a SPARQL endpoint the agents can query. Retrieval is active only when source.knowledge_graph.enabled resolves to true, at which point every KnowledgeGraph resource the project publishes becomes reachable.

Field	Type	Requirement	Description
`endpoint.sparql`	URL	Required	The SPARQL query endpoint URL.
`auth`	object	Optional	The authentication block used to reach the endpoint. See the Authentication section.
`timeout_s`	integer	Optional, default `5`	Query timeout in seconds.
`lang`	string	Optional, default `en`	Language code used for the query.
`format`	string	Optional, default `table`	Result format returned to the agent.
`variant`	string	Optional, default `agent`	Query variant used against the endpoint.
`prefixes`	map of string to string	Optional, empty by default	Namespace prefixes made available to queries.
`description`	string	Optional	Prose describing the graph, advertised to the agents that can query it.
`title` / `summary`	string	Optional	Display label and description.

Example, a graph authored as knowledge-graphs/company_kg.yaml:

kind: KnowledgeGraph
schema: v1
metadata:
  id: company_kg

endpoint:
  sparql: https://kg.example.com/sparql
auth:
  type: bearer
  secret: kg_token
description: Company organizational and product knowledge graph.

MCP#

An MCP resource points at an external Model Context Protocol server. Its tools are active only when capability.mcp.enabled resolves to true, at which point every MCP resource the project publishes becomes reachable.

Field	Type	Requirement	Description
`url`	URL	Required	The server URL.
`transport`	string	Optional, default `sse`	The transport used to reach the server, either `sse` or `streamable_http`.
`auth_mode`	string	Optional, default `anonymous`	How the platform authenticates to the server. One of `anonymous`, `static_bearer`, or `per_user_oauth`.
`bearer_handle`	string	Required with `static_bearer`	The secret handle resolving to the shared bearer token. Not accepted for the other two modes.
`requires_approval`	boolean	Optional, default `true`	Whether tool calls on this server require human approval before they run.
`tool_approval_overrides`	map of string to boolean	Optional, empty by default	Per-tool approval overrides, keyed by the upstream tool name. A value of `false` runs the named tool without approval, and `true` requires it.
`description`	string	Optional	Prose describing the server, recorded in the configuration for your own reference. The tools the server exposes carry their own descriptions, which is what an agent reads when it decides to call one.
`title` / `summary`	string	Optional	Display label and description.

The three auth_mode values are:

anonymous

The server is open or trusts the cluster network. No handle is declared.
static_bearer

A single shared bearer token, named by bearer_handle.
per_user_oauth

Each user authorizes the server individually. The platform looks up the per-user token at runtime, so no handle is declared.

Example, a server authored as mcp/tickets.yaml:

kind: MCP
schema: v1
metadata:
  id: tickets

url: https://mcp.example.com/
transport: streamable_http
auth_mode: static_bearer
bearer_handle: tickets_token
requires_approval: true

DocumentSourceSettings#

A DocumentSourceSettings resource sets how the agents search and read documents. A project has one at most, and it carries no metadata.id. The implementation field selects the retrieval engine for the whole deployment, which changes the tools an agent sees and the citation contract, so it is a deployment-wide decision rather than a per-turn setting.

Field	Type	Requirement	Description
`implementation`	string	Optional, default `split`	The retrieval engine. `split` gives the agent a two-step search-then-fetch retriever that controls read depth. `legacy` gives the earlier single-step retriever.
`default_search_count`	integer	Optional, default `10`	Number of results a search returns. Applies to the `split` engine.
`split_fetch_budget_tokens`	integer	Optional, default `128000`	Token budget for a single fetch. Applies to the `split` engine.
`fetch_timeout_s`	integer	Optional, default `120`	Per-request retrieval timeout in seconds. Applies to both engines.

The legacy engine accepts additional advanced tuning fields: retrieval_mode, fetch_top_n_search, fetch_top_n_summarize, context_expansion, intent_filters, semantic_profile_config, phrase_filter, and retrieval_budget_tokens. These fields have no effect under the split engine, and genai lint warns when a split deployment sets them. Squirro recommends the split engine for new projects.

Example, the settings authored as document-source-settings.yaml:

kind: DocumentSourceSettings
schema: v1

implementation: split
default_search_count: 10

CodeInterpreter#

A CodeInterpreter resource sets up the sandbox the agents run code in. A project has one at most, and it carries no metadata.id. Code execution is active only when capability.code_interpreter.enabled resolves to true.

The backend object selects the execution provider through its type field. The supported backend is openai.

Field	Type	Requirement	Description
`backend.type`	string	Required	The execution provider. The supported value is `openai`.
`backend.model_name`	string	Required	The model identifier as the provider publishes it, used for code execution. As with a `Model` resource, the name is not checked at deploy.
`backend.auth`	object	Required	A `bearer` authentication block whose `secret` handle resolves to the provider token.

Example, the sandbox configuration authored as code-interpreter.yaml:

kind: CodeInterpreter
schema: v1

backend:
  type: openai
  model_name: gpt-5.2
  auth:
    type: bearer
    secret: openai_token