Definition

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

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:

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 – The definition as the proxy receives it, for an agent named name.

Definition.document

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.

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:

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 (str) – The sub-agent’s name, as requests name it.

SubAgent.name

name: str

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

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.