菜单
Enable safe and efficient AI agent interactions with websites via declarative HTML extensions—define agent-executable tools and context using <tool> and <context> tags instead of relying on brittle UI inference.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/ADu2021/skillXiv --skill web-agent-declarative-framework命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
| name | web-agent-declarative-framework |
| title | Building the Web for Agents: A Declarative Framework for Agentic Web Interactions |
| version | 0.0.2 |
| engine | skillxiv-v0.0.2-claude-opus-4.6 |
| license | MIT |
| url | https://arxiv.org/abs/2511.11287 |
| keywords | ["Web Agents","Declarative APIs","Tool Specification","Machine-Readable Contracts","Agent Integration"] |
| description | Enable safe and efficient AI agent interactions with websites via declarative HTML extensions—define agent-executable tools and context using <tool> and <context> tags instead of relying on brittle UI inference. |
Web agents typically infer capabilities by analyzing human UI—button labels, form structures, navigation patterns. This approach is fragile: agents misinterpret intent, trigger unintended actions, and fail gracefully on novel UI layouts. The Agentic Web framework (VOIX) shifts responsibility to developers: specify what agents can do explicitly via declarative HTML extensions.
Rather than agents guessing "what this button does," developers declare tools through <tool> and <context> tags. This creates a machine-readable contract for agent behavior, enabling safe, predictable, and auditable agent interactions while preserving user privacy and control.
Current agent-web integration suffers from two problems:
VOIX solves this with two declarative mechanisms:
<tool> tags: Developers explicitly declare actions agents can invoke, specifying inputs, outputs, and side effects<context> tags: Specify relevant state information agents need to make decisions (user preferences, session state, current form data)Developers build the website normally; agents see enhanced, machine-readable augmentations. A hackathon study showed participants regardless of experience could rapidly build functional agent applications.
<tool> Element: Declarative action specification with name, description, parameters (type, required, validation), output format<context> Element: State declaration with visibility scope (user-visible, agent-only, public); prevents oversharing sensitive dataStep 1: Define Tools. Markup website actions with declarative tool specifications.
<!-- Simple search tool -->
<tool name="search_products"
description="Search product catalog by keyword"
parameters="query:string(required), category:string(optional), limit:number(default=10)">
<!-- Tool definition embedded; framework routes agent requests here -->
<action method="POST" endpoint="/api/search">
<param name="q" source="query"/>
<param name="cat" source="category"/>
<param name="limit" source="limit"/>
</action>
<output format="json" schema="product_list"/>
</tool>
<!-- Complex tool with validation -->
<tool name="add_to_cart"
description="Add item to shopping cart"
parameters="product_id:string(required,pattern='p_[0-9]+'), quantity:number(required,min=1,max=100)">
<permission scope="user"/> <!-- Requires user confirmation -->
<action method="POST" endpoint="/cart/add">
<param name="pid" source="product_id"/>
<param name="qty" source="quantity"/>
</action>
<output format="json" schema="cart_status"/>
<side_effect type="user_notification">Cart updated</side_effect>
</tool>
Step 2: Declare Context. Specify application state relevant to agent decision-making.
<!-- User context: agent needs to know user's preferences -->
<context name="user_prefs" scope="agent">
<field name="preferred_category">electronics</field>
<field name="budget_max">500</field>
<field name="shipping_address">123 Main St, City</field>
</context>
<!-- Session context: agent state for conversation continuity -->
<context name="session" scope="agent">
<field name="conversation_id">sess_12345</field>
<field name="previous_queries">last 5 user queries</field>
<field name="current_task">help_choose_laptop</field>
</context>
<!-- Public context: information agents can expose to humans -->
<context name="product_listing" scope="public">
<field name="featured_products">list of top 10 products</field>
<field name="sale_items">current promotions</field>
</context>
Step 3: Build Tool Registry. Parse declarative specs and index tools for agent access.
class ToolRegistry:
def __init__(self, html_content):
self.tools = {}
self.context = {}
self.parse_html(html_content)
def parse_html(self, html):
"""Extract <tool> and <context> declarations from HTML."""
soup = BeautifulSoup(html, 'html.parser')
# Parse tools
for tool_elem in soup.find_all('tool'):
tool_name = tool_elem.get('name')
description = tool_elem.get('description')
param_spec = tool_elem.get('parameters')
self.tools[tool_name] = {
'description': description,
'params': self.parse_parameters(param_spec),
'endpoint': tool_elem.find('action').get('endpoint'),
'method': tool_elem.find('action').get('method'),
'requires_permission': bool(tool_elem.find('permission')),
'output_schema': tool_elem.find('output').get('schema')
}
# Parse context
for ctx_elem in soup.find_all('context'):
ctx_name = ctx_elem.get('name')
scope = ctx_elem.get('scope')
fields = {}
for field in ctx_elem.find_all('field'):
fields[field.get('name')] = field.text
self.context[ctx_name] = {
'scope': scope,
'fields': fields
}
def parse_parameters(self, param_spec):
"""Parse parameter string: 'name:type(constraints), ...'"""
params = {}
for param_str in param_spec.split(','):
# Parse: "query:string(required)" or "limit:number(default=10)"
parts = param_str.strip().split(':')
name = parts[0]
type_and_constraints = parts[1] if len(parts) > 1 else "string"
params[name] = self.parse_type_spec(type_and_constraints)
return params
def get_available_tools(self):
"""Return list of tools available to agents."""
return list(self.tools.keys())
def get_tool_spec(self, tool_name):
"""Retrieve full specification for a tool."""
return self.tools.get(tool_name)
def validate_tool_call(self, tool_name, args):
"""Validate agent tool call against declared spec."""
tool_spec = self.get_tool_spec(tool_name)
if not tool_spec:
raise ValueError(f"Unknown tool: {tool_name}")
# Validate each parameter
for param_name, param_spec in tool_spec['params'].items():
if param_spec['required'] and param_name not in args:
raise ValueError(f"Missing required parameter: {param_name}")
if param_name in args:
# Type and constraint checking
self.validate_parameter(args[param_name], param_spec)
return True
Step 4: Agent-Server Integration. Agents query registry and execute validated tool calls.
@app.route('/agent/tools', methods=['GET'])
def list_tools():
"""Agent queries available tools."""
return {
'tools': registry.get_available_tools(),
'context': registry.context
}
@app.route('/agent/execute', methods=['POST'])
def execute_tool():
"""Execute agent tool call with validation."""
data = request.json
tool_name = data['tool']
args = data['args']
# Validate against spec
try:
registry.validate_tool_call(tool_name, args)
except ValueError as e:
return {'error': str(e)}, 400
# Execute
tool_spec = registry.get_tool_spec(tool_name)
response = requests.request(
method=tool_spec['method'],
url=tool_spec['endpoint'],
json=args
)
return response.json()
When to Use: Web applications requiring agent integration (customer service bots, shopping assistants, workflow automation). Use whenever you want agents to interact with your site predictably.
Declarative Best Practices:
<tool> descriptions: be explicit about side effects (e.g., "Permanently deletes user account")<permission>Pitfalls:
When NOT to Use: Static websites with no agent interaction needs; internal tools not exposed to agents.
Integration: Pairs naturally with any agent framework (ReAct, LangChain, custom). Can be layered atop existing websites without major refactoring.
Reference: https://arxiv.org/abs/2511.11287
基于 SOC 职业分类
