---
title: "Definition"
description: "Definition, what an agent is, with SubAgent for agents declared inside it and Problem for what a definition gets wrong."
source: "Guardian Agent SDK"
---
A `Definition` records what an agent is: its models, instructions, tools, sub-agents and declared capabilities. It is checked the moment it is made. `SubAgent` declares an agent inside another, and `Problem` describes one way a definition is wrong.

## Definition

{/* generated api guardian_agent.Definition */}

What an agent is: its models, instructions, tools and capabilities.

It is checked when it's created, so a mistake fails at the line that made
it: data JSON can't carry, credentials, and the definition schema. Nothing
is sent until an agent uses it.

Example:

```python
definition = ga.Definition(
    description="Answers questions from the internal docs.",
    model=ga.Model("openai", "gpt-4.1", temperature=0),
    instructions="You research questions using the internal docs.",
    tools=[search_docs],
)
```

**Parameters:**

- **model** (`Model | BaseChatModel | Sequence[Model | BaseChatModel]`) – The model, or models in fallback order: a `Model`, or a
  LangChain chat model, described by its provider, name and the
  settings that change its answers (never its keys or headers).
- **instructions** (`Instruction | Sequence[Instruction] | None`) – Text for a system prompt, or a list of text,
  `System` and `Developer` prompts, in order.
- **description** (`str | None`) – What the agent is for.
- **version** (`str | None`) – Your own label for this version of the agent.
- **framework** (`Framework | None`) – What it's built with; `Framework("custom")` by default.
- **tools** (`Iterable[Tool | Callable[..., Any] | BaseTool]`) – Functions (marked with `tool` or not), `Tool` and
  LangChain tools, each as the model sees it.
- **subagents** (`Iterable[SubAgent]`) – Agents declared inside this one, which sign as it.
- **middleware** (`Iterable[Middleware]`) – Middleware, in the order it runs.
- **mcp_servers** (`Iterable[McpServer]`) – MCP servers the agent uses. Tools loaded with
  `langchain-mcp-adapters` add their own servers.
- **skills** (`Iterable[Skill]`) – Skills the agent has, each by its files' CID.
- **memory** (`Iterable[Memory]`) – Memory it loads into its prompt: instructions it can't change,
  and memory it learns.
- **permissions** (`Iterable[str]`) – Permissions it declares.
- **guardrails** (`Iterable[str]`) – Guardrails it declares.
- **graph** (`Graph | None`) – Its graph of nodes and edges.
- **sources** (`Iterable[Source]`) – Source files to fingerprint.
- **extensions** (`Mapping[str, Any] | None`) – Framework-specific data, keyed by framework name.
- **exclude** (`Iterable[str]`) – JSON Pointers to fields to leave out, recorded under
  `extensions.guardian.excluded`.

**Raises:**

- `DefinitionInvalid` – The definition breaks the schema; `problems`
  says where and how.
- `DefinitionContainsSecret` – It holds what looks like a credential;
  `problems` says where.
- `ValueError` – An `exclude` pointer names nothing, a list item or a
  field that can't be left out, `extensions` uses the reserved
  `guardian` key, or a LangChain chat model sends a setting no
  definition can record (named, never its value).
- `TypeError` – An argument isn't of a type the definition can hold, such
  as a LangChain model wrapped by `bind_tools()`, or made with
  `configurable_fields`.

**Functions:**

- [**document**](#definitiondocument) – The definition as the proxy receives it, for an agent named `name`.

### `Definition.document`

```python
document(name: str) -> dict[str, Any]
```

The definition as the proxy receives it, for an agent named `name`.

**Parameters:**

- **name** (`str`) – The agent's name, as enrolled with `viper agent add`.

**Returns:**

- `dict[str, Any]` – A new copy each call: JSON data with the schema's field names.

**Raises:**

- `ValueError` – `name` isn't a valid agent name.

{/* end generated */}

## SubAgent

{/* generated api guardian_agent.SubAgent */}

An agent declared inside another, which signs as its parent.

It takes the same arguments as `Definition`, plus its name, and
needs a `description`: the parent uses it to decide when to delegate.
Without a `framework` of its own, it inherits its parent's name (package
versions are recorded once, on the parent). Its `exclude` pointers are
relative to the sub-agent and recorded in its own extensions. Its tools
loaded with `langchain-mcp-adapters` add their servers to its own
`mcp_servers`, as for `Definition`.

Example:

```python
critic = ga.SubAgent(
    "critic",
    description="Reviews drafts for unsupported claims.",
    model=ga.Model("openai", "gpt-4.1-mini"),
    instructions="You review drafts.",
)
```

**Raises:**

- `ValueError` – The name isn't a valid agent name, or as for
  `Definition`.
- `DefinitionInvalid` – As for `Definition`.
- `DefinitionContainsSecret` – As for `Definition`.
- `TypeError` – As for `Definition`, or `description` isn't text.

**Attributes:**

- [**name**](#subagentname) (`str`) – The sub-agent's name, as requests name it.

### `SubAgent.name`

```python
name: str
```

The sub-agent's name, as requests name it.

{/* end generated */}

## Problem

{/* generated api guardian_agent.Problem */}

One way a definition is wrong.

**Attributes:**

- **path** (`str`) – A JSON Pointer to the offending value; `""` is the whole
  definition. A missing field (`required`) or one that isn't
  allowed (`additionalProperties`) is named by its own path, so
  `/framework/name` for a framework without a name. Map keys that
  are not field names read `<key>`.
- **rule** (`str`) – The rule broken, as the JSON Schema keyword that states it, such
  as `type`, `required`, `pattern` or `uniqueItems`; or
  `jsonValue`, `jsonKey`, `finite` or `cycle` (a container
  inside itself) for data JSON can't carry, and `nesting` for maps
  and lists nested deeper than the proxy reads (127 levels), or
  `maxSize` for a document too large to walk. A rule with no keyword keeps
  a short name of its own; treat any rule you don't recognise as
  informational. `secret` marks what looks like a credential.
  Rules of the agent-definition crate the schema can't state are
  `maxLength` (in UTF-8 bytes), `maxDepth` and `maxSubAgents`
  for sub-agents, `transport` for an MCP server field its
  transport doesn't use, `writable` for a memory field its
  `writable` doesn't allow (a CID on memory the agent changes, a
  scope on memory it can't), `scope` for a namespace hash on a
  shared scope, and `oneOf` for a prompt without exactly one of `content` and
  `contentCid`, `node` for a graph edge joining a node the graph
  doesn't list, and `safeInteger` for an integer beyond
  ±(2^53 - 1).
- **kind** (`str`) – For a `secret`, what it looks like, such as `API key`,
  `credential field` or `credential in a URL`; otherwise empty.

{/* end generated */}