Agent Skills & Agent Card

Before an OPVS agent can do anything, it needs to define what it can do (its skills) and how other agents or clients can find out about these capabilities (its Agent Card).

We'll use the `helloworld` example located in `opvs-samples/samples/python/agents/helloworld/`.

An **Agent Skill** describes a specific capability or function the agent can perform. It's a building block that tells clients what kinds of tasks the agent is good for.

Attributes of an `AgentSkill` (defined in `opvs.types`):

• `id`: A unique identifier for the skill.
• `name`: A human-readable name.
• `description`: A more detailed explanation of what the skill does.
• `tags`: Keywords for categorization and discovery.
• `examples`: Sample prompts or use cases.
• `input_modes` / `output_modes`: Supported Media Types for input and output (e.g., "text/plain", "application/json").
• `security_requirements`: Security schemes necessary for this skill.

In `__main__.py`, you can see how a skill for the Helloworld agent is defined:

skill = AgentSkill(
    id='hello_world',
    name='Returns hello world',
    description='just returns hello world',
    tags=['hello world'],
    examples=['hi', 'hello world'],
)

This skill is very simple: it's named "Returns hello world" and primarily deals with text.

The **Agent Card** is a JSON document that an OPVS Server makes available, typically at a `.well-known/agent-card.json` endpoint. It's like a digital business card for the agent.

Key attributes of an `AgentCard` (defined in `opvs.types`):

• `name`, `description`, `version`: Basic identity information.
• `icon_url`: A URL to an icon representing the agent.
• `supported_interfaces`: Ordered list of endpoints and protocols where the OPVS service can be reached.
• `capabilities`: Supported OPVS features like `streaming` or `extended_agent_card`.
• `default_input_modes` / `default_output_modes`: Default Media Types for the agent.
• `skills`: A list of `AgentSkill` objects that the agent offers.

The `helloworld` example defines its Agent Card like this:

# This will be the public-facing agent card
public_agent_card = AgentCard(
    name='Hello World Agent',
    description='Just a hello world agent',
    icon_url='http://localhost:9999/',
    version='1.0.0',
    default_input_modes=['text'],
    default_output_modes=['text'],
    capabilities=AgentCapabilities(
        streaming=True, extended_agent_card=True
    ),
    supported_interfaces=[
        AgentInterface(
            protocol_binding='JSONRPC',
            url='http://localhost:9999',
        )
    ],
    skills=[skill], # Only the basic skill for the public card
)

This card tells us the agent is named "Hello World Agent", runs at `http://localhost:9999` using `JSONRPC`, supports text interactions, and has the `hello_world` skill. Its capabilities also indicate support for streaming and an extended authenticated configuration.

Understanding the Agent Card is crucial because it's how a client discovers an agent and learns how to interact with it.