Agent and Role Guide

中文

Agent behavior is shaped by roles, Markdown sub-agents, Skills, tool visibility, and HITL policy.

Responsibility Boundaries

Resource	Purpose	Not for
Role	identity, tone, tool boundary, authorization rules	large reference material
Agent Markdown	multi-agent specialization, handoff format, local strategy	one-off facts
Skill	reusable procedures, checklists, templates, references	permission control

Authorization boundaries belong in roles and HITL first, not only in Skills.

Modes

Mode	Good for	Poor fit
eino_single	short tasks, interactive analysis	large multi-stage work
deep	dynamic task decomposition	strict sequential workflows
plan_execute	plan, execute, replan loops	frequent user interruption
supervisor	expert routing	vague or too many sub-agents

Start with eino_single; use plan_execute for structured projects; use deep or supervisor when specialist agents matter.

Markdown Sub-Agent

Example:

---
name: Vulnerability Triage
id: vulnerability-triage
description: Validate, classify, and summarize vulnerability evidence
tools:
  - nmap
  - nuclei
bind_role: 综合漏洞扫描
max_iterations: 200
---

The body should define scope, tool order, output format, and prohibited actions.

Tool Visibility

With tool_search, the model initially sees only a subset of tools:

• visible in UI does not mean visible in current model context;
• tool_search_always_visible_tools are easier to call;
• clear tool descriptions improve search hits;
• sub-agent tool constraints still matter.

When a tool is not used, check role tools, sub-agent tools, tool_search config, and description.

Output Format

Sub-agents should return structured results:

## Conclusion
## Evidence
- Tool:
- Key output:
- Confidence:
## Risks
## Suggested next step

This helps the orchestrator continue and supports reporting.

Source Anchors

• Markdown Agent parser: internal/agents/markdown.go
• Multi-agent preparation: internal/handler/multi_agent_prepare.go
• Orchestration: internal/multiagent/eino_orchestration.go
• Tool search middleware: internal/multiagent/eino_middleware.go