Limits

The proxy reports its limits in guardian.capabilities().limits, a ga.Limits (Capabilities), so code can check against the proxy it’s talking to rather than a copy of these numbers. The values below are Viper’s.

The SDK checks the counts, the nesting and a skill’s or memory’s files when they’re made, before anything is sent. The proxy checks sizes when a definition is registered, and has the last word: a definition can pass every local check and still be refused as too large.

The definition

• definition_bytes: 1,048,576 (1 MiB). The whole definition’s canonical size, sub-agents included. A prompt over inline_prompt_bytes doesn’t count here, since the proxy stores it apart and the definition refers to it by content ID. Over it: ga.DefinitionTooLarge at registration.

• registration_bytes: 4,194,304 (4 MiB). A registration request’s body, prompts held apart included. Over it: ga.DefinitionTooLarge at registration.

• name_length: 64. In bytes, for two kinds of name:

  • An agent’s or sub-agent’s name, which must also be lowercase letters, digits, ., _ and -, starting with a letter or digit. A name that breaks either rule raises ValueError, not a ga.GuardianAgentError, from guardian.agent(), ga.SubAgent(), definition.document() and the framework integrations. The proxy answers 422 definition_invalid.
  • A version, a framework’s name, an MCP server’s name, a memory backend and a model’s beta feature. Over it: ga.DefinitionInvalid when the definition is made. The proxy answers 413 definition_too_large.

  A tool’s name isn’t bounded by it.

• Labels signed together: 983,040 bytes, 64 KiB less than the 1 MiB the proxy uploads as one blob (collection_file_bytes). An agent’s or sub-agent’s permissions, tool names and skills (each name and CID), measured as JSON, which its state copies into the credential signed with each of its requests. Over it: ga.DefinitionTooLarge at registration. Capabilities don’t report it, since it follows from the upload limit. Only an agent with very many, or very long, permissions or tool names comes near it.

With Deep Agents, each sub-agent adds about 14.8 KB, since Deep Agents’ tools are described in full. With no tools of your own and short prompts, 63 sub-agents of your own, beside general-purpose, come to about 960 KB, so sub_agents is reached first. Tools of your own, and sub-agents’ descriptions and prompts, add to each sub-agent that has them; a prompt over inline_prompt_bytes is stored apart and doesn’t count (Deep Agents).

The proxy’s limits can’t be raised. Over one, make the definition smaller (shorter prompts, fewer tools or sub-agents), or split it into agents of their own (Multiple agents). Call register() at start-up, so a definition over a limit fails there rather than on the first request.

Prompts

• inline_prompt_bytes: 16,384 (16 KiB). One prompt’s text, held inline in the definition. A longer prompt is fine: the proxy stores it apart, by its own content ID.
• prompt_bytes: 1,048,576 (1 MiB). All of one agent’s prompt text together, counting a blank line between prompts, and the same again for each sub-agent’s. Over it: ga.DefinitionTooLarge at registration.

Counts

Each is checked when the definition is made, and raises ga.DefinitionInvalid over the limit. What the proxy answers differs: a count over its limit is too large, but nesting too deep is invalid.

• tools: 256. Tools on any one agent or sub-agent. The proxy answers 413 definition_too_large.
• sub_agents: 64. Sub-agents at every depth, together. The proxy answers 413 definition_too_large.
• sub_agent_depth: 3. How deeply sub-agents may nest: a sub-agent’s sub-agent’s sub-agent, and no deeper. The proxy answers 422 definition_invalid.
• mcp_servers: 64. MCP servers on any one agent or sub-agent. The proxy answers 413 definition_too_large.
• skills: 256. Skills on any one agent or sub-agent. The proxy answers 413 definition_too_large.
• memory: 64. Memory sources on any one agent or sub-agent. The proxy answers 413 definition_too_large.

Skill and memory files

One skill, or one source of memory the agent can’t change, is stored as a collection of files (Skills and instructions). The SDK checks these before reading or sending the files, naming the file where it can.

• collection_files: 1,024. Files in one skill or memory source.
• collection_file_bytes: 1,048,576 (1 MiB). One file.
• collection_bytes: 8,388,608 (8 MiB). One skill’s or memory source’s files, together. Their paths, together, must also stay under 1 MiB.

Over any of them: ga.CollectionTooLarge, and nothing is stored.

Other bounds

These aren’t reported in capabilities(), but a definition meets them:

• JSON nesting: a definition nested more than 127 levels deep is refused, as the proxy’s parser refuses it.
• A skill’s or memory’s directory: a file more than 16 levels deep is refused (ga.CollectionInvalid). Symlinks inside it are skipped.
• The framework integrations’ search for a model a tool or middleware holds stops at 100,000 values or 16 levels, and refuses what it can’t finish searching (How far the search goes).