Skip to main content
Back to path

Welcome to a Grasp lesson

Create a free account to keep studying and create your own study path.

Lesson 32

Understanding Capability Manifests

Recommended resources

Hello! Welcome back to our module on "Architecting Agentic Systems."

In our last lesson, we established why capability manifests are essential. We learned that they act as a bridge, allowing an AI's reasoning engine (the LLM) to discover and correctly use external tools, transforming it from a text generator into an action-taking agent.

Today, we're going to lift the hood and look at what's inside a manifest. This lesson will unpack the core components that give an agent its identity, its abilities, and its rules of engagement. For you as a designer, understanding these components is like learning the properties of a design component in Figma; it's the structured information that defines what an element is and how it behaves.

This lesson directly addresses the learning outcome: Describe the key components of a capability manifest (e.g., agent identity, functions, constraints).

A Conceptual Framework: The Agent's Job Description

Before diving into formal specifications, let's start with an intuitive framework. A capability manifest is essentially a very detailed, machine-readable "job description" for an AI agent. A great way to think about the contents of this job description comes from the world of agent prompting.

This video introduces a mnemonic, "ROCK TOCK," to structure a system prompt that defines an agent's behavior. These concepts map directly to the formal components of a manifest.

The Secret SYSTEM PROMPT for Building AI Agents in 2025

This video, 'The Secret SYSTEM PROMPT for Building AI Agents in 2025' by AI Alfie, provides a clear, memorable framework for defining an agent's role, objectives, tools, and rules. We'll use this as our conceptual starting point.

Please watch the following four short clips. As you watch, think about how each piece of information helps define the agent's identity, its functions, and its constraints: Role (10:21 - 11:05): This defines the agent's expertise and personality. Tools (12:30 - 13:52): This lists the agent's available actions and, crucially, the importance of describing them well. Operating Guidelines (14:45 - 15:47): These are detailed instructions on how to perform tasks. Constraints (15:47 - 17:00): These are the explicit 'do's and 'don'ts' for the agent.

The video gives us a great mental model. Now, let's formalize these concepts into the three key components of a manifest.

1. Agent Identity: Who is the Agent?

Just like a product has a name and a brand, an agent needs a clear identity. This allows other systems (and humans) to discover, understand, and trust it.

The Identity component typically includes:

  • Name / ID: A unique, machine-readable identifier (e.g., finance-report-agent).
  • DisplayName: A human-friendly name for display in user interfaces (e.g., "Finance Reporter").
  • Description: A clear, natural-language summary of the agent's purpose and what it's designed to do.
  • Publisher / Author: Information about who created and maintains the agent, which is vital for governance and trust.

To see how this looks in a formal specification, let's review a professional reference document.

Agent manifest - Microsoft Learn

The document 'Agent manifest - Microsoft Learn' provides a detailed, real-world specification. We'll look at the sections that define the agent's identity.

Scan the two tables under the headings 'Descriptor field summary' and 'AgentDefinitions field summary.' You don't need to memorize every field, but notice the kind of information captured, such as Name, DisplayName, Description, and Publisher. These fields collectively establish the agent's core identity.

2. Functions: What Can the Agent Do?

This is the heart of the manifest. It's the "toolkit" we discussed in the last lesson. This section doesn't just list the tools; it provides a detailed operational schema for each one so the LLM knows how to use it correctly.

Each Function (also called a "skill" or "tool") definition must include:

  • Function Name: A unique name for the action (e.g., get_current_weather).
  • Function Description: This is arguably the most critical part from a design perspective. It's a clear, unambiguous natural language description of what the function does and when it should be used. A poorly written description leads to agent errors.
Agent Ambiguity in Automation Selection
This image perfectly illustrates the need for clear function descriptions. The agent receives a request to 'Update a PR.' Without a clear description for each tool, it can't know if 'PR' means a 'Pull Request' (GitHub) or a 'Purchase Requisition' (SAP Ariba). A good manifest resolves this ambiguity.
  • Parameters / Inputs: A structured definition of the data the function needs. This is like defining the required fields in a form. For our get_current_weather function, the parameters might be location (string) and unit (enum: 'celsius' or 'fahrenheit').

This next video shows a concrete example of how function parameters are defined in code using JSON Schema.

How does OpenAI Function Calling work?

The video 'How does OpenAI Function Calling work?' by Learn Data with Mark gives a practical look at how a function's parameters are structured.

Watch the short clip from 2:27 to 2:51. Focus on how the get_current_weather function is defined with a name and a set of parameters (latitude and longitude). This is a tangible example of what the 'Functions' part of a manifest looks like.

3. Constraints: What Are the Rules?

An unconstrained agent is unpredictable and potentially dangerous. Constraints define the boundaries within which the agent must operate. They are the rules of the road that ensure safety, reliability, and predictability.

Constraints can include:

  • Behavioral Rules: Topics the agent must avoid, personality traits it should exhibit, or a specific tone of voice it must use. The "don't talk about politics" example from the first video is a classic behavioral constraint.
  • Operational Rules: Technical limits, such as rate limits (e.g., "can only call the weather API 5 times per minute") or deployment constraints (e.g., "only one instance of this agent can run in the entire organization").
  • Tool-Specific Constraints: Conditions attached to a specific function. For example, a book_flight function might have a constraint that it only works for specific airlines or requires a certain payment method.

This image provides an excellent visual metaphor for tool-specific constraints.

Agent Discovery based on a Constraints Model
This diagram shows a travel agent orchestrating several services. Each service (Function) has its own constraints. The flight booking service, for example, is constrained to fly only on certain days and requires credit card payment. The agent must understand these constraints to use the tool correctly.

Putting It All Together: An Example Manifest

Now that we've examined the three core components, let's see how they come together in a complete manifest file.

Agent Manifest - Agent Communication Protocol

The 'Agent Manifest - Agent Communication Protocol' documentation provides a clean, complete JSON example of a manifest. This will help you see how Identity, Functions, and Constraints fit together in a single structure.

Review the full JSON example provided in this resource. As you read through it, try to identify the different components we've discussed: Identity: Look for fields like name, description, author, and programming_language. Functions: Find the capabilities array. Each object in this array represents a function the agent can perform. Constraints: Notice the dependencies (e.g., requires the 'weather' tool) and recommended_models. These are forms of constraints that define the agent's operational requirements.

Conclusion

You've now dissected the capability manifest and understand its core anatomy. This is a critical step in moving from being a user of AI to an architect of AI systems. By defining these components with precision, you can design agents that are discoverable, capable, and, most importantly, reliable.

Key Takeaways:

  • A capability manifest is structured around three key components.
  • Identity (name, description, publisher) establishes who the agent is, enabling discovery and trust.
  • Functions (name, description, parameters) define what the agent can do, forming its "toolkit." The clarity of the description is paramount for correct tool selection.
  • Constraints (behavioral rules, operational limits, tool conditions) provide the necessary guardrails to ensure the agent operates predictably and safely.

Next Lesson Preview

You understand why we need manifests and what's inside them. In our next lesson, you'll start designing them. We'll move to the next learning outcome: Design a conceptual model for an agent's tool-use function (name, purpose, parameters, return values). This will be a hands-on exercise where you'll apply today's concepts to define a new capability for an agent.