Views & Skills
Two LLM-facing concerns:
- Views decide what each participant sees of a channel — the projection of the WAL that becomes the LLM's history when its handler runs
Agent.ask(...). - Skills decide what each agent advertises about itself — the markdown describing its capabilities, surfaced to other agents during peer lookup.
ViewPolicy#
ViewPolicy is a Protocol:
It takes the WAL up to the current envelope and returns a list of BaseEvents that the framework feeds into the LLM turn as pre-populated stream history. Each adapter picks a default view per participant; to use a different one, override the adapter's default_view_policy (see Custom Views).
Two callables are supplied per call so view policies stay adapter-neutral and identity-aware without depending on hub internals:
render_envelope: Callable[[Envelope], Sequence[Input] | None]— comes from the channel'sChannelAdapter.render_envelope. Lets a view ask "what does the LLM see for this envelope?" without knowing the channel type's envelope shape. The answer is a list ofInputparts (TextInput, images, and so on), orNone(or no parts) to skip the envelope. An envelope can carry several parts — a workflow packet gives its handoff signal and its body as separate ones — and a view should keep them apart rather than join them into one string. The adapter itself may return a plain string, anInputor a sequence of either; the handler converts it withInput.ensure_input, the same conversionAgent.askapplies, before a view sees it. A custom adapter can annotate what it returns asRendered, andensure_partsis the conversion itself — both import fromag2.network.name_for: Callable[[str], str]— comes fromHub.name_for. Lets a view resolve anagent_idto its registeredPassport.namefor projection lines that need a speaker label. Falls back to the raw id when the sender is unknown so projection never fails.
Built-in Views#
| View | Behaviour | Default for |
|---|---|---|
FullTranscript() | Every visible envelope, in order, no filtering beyond audience. Non-self envelopes become bare ModelRequests. | consulting (2-party) |
WindowedSummary(recent_n=N) | The last N visible envelopes. If the WAL is longer, prepends a CompactionSummary placeholder with a count of the elided turns. Non-self envelopes become bare ModelRequests. | conversation (2-party) |
NamedTranscript() | Like FullTranscript, but each non-self envelope is prefixed with [<sender name>]: so the LLM can tell its peers apart. Resolves names via the supplied NameResolver. | — |
NamedWindowedSummary(recent_n=N) | Like WindowedSummary, but with the same [<sender name>]: labelling on non-self lines and on the head CompactionSummary's speakers list. | discussion, workflow (N-party) |
All four views honour audience: an envelope addressed only to [bob] doesn't appear in carol's projection.
Why two flavours?
In a 2-party channel, the assistant/user role bit already disambiguates speakers — the LLM sees its own past as role: "assistant" and the only other party as role: "user". Labels would be redundant.
In a 3+ party channel (discussion, workflow), every non-self envelope collapses into the same role: "user" stream. Without a sender label the LLM can't tell which peer said which message. The Named* variants put [<sender name>]: on each non-self line so the orchestrator / next speaker can route accurately. This is the default for N-party adapters precisely because the role bit alone isn't enough.
You can also call a view directly, for example to inspect what a participant would see. Supply the same inputs the default handler does: the channel's WAL and metadata from the hub, the adapter's render_envelope normalised with ensure_parts, and Hub.name_for. Here hub is your Hub, channel_id an existing channel and carol the AgentClient of one of its participants:
projected is the list of events carol's LLM would receive as history: at most 12 visible envelopes, plus a leading CompactionSummary when older ones were elided.
Resolving the Default#
client is the participant's AgentClient (what hub.register(...) returns). resolve_view_policy asks the channel's adapter for that participant's view by calling ChannelAdapter.default_view_policy(metadata, client.agent_id), so the adapter can size the view for the channel. For example, discussion and workflow channels use NamedWindowedSummary(recent_n=max(2 * participant_count, 4)). The default handler calls this once per turn. Custom handlers should too, unless they're deliberately bypassing the standard projection model.
Custom Views#
Implement the protocol and give the view a unique name. For example, a view that shows only one sender's messages:
There is no separate view registry. To make the default handler use your view, subclass the channel type's adapter, return the view from default_view_policy, and register the subclass on the hub. Registering an adapter with the same type and version replaces the built-in one for channels opened afterwards. Here alice is the AgentClient whose messages everyone should see:
The BaseEvent types you emit determine how the LLM sees the history: ModelRequest for messages "from the user," ModelMessage for messages "from the assistant," and so on. Look at ag2.events for the full taxonomy.
CompactionSummary#
When WindowedSummary (or NamedWindowedSummary) elides envelopes outside its window, it prepends a CompactionSummary event from ag2.compact, for example CompactionSummary(summary="Earlier in this channel: 8 messages from alice, bob.", event_count=8). The summary is a static count of messages and speakers, with no LLM call. NamedWindowedSummary lists speakers by Passport.name; WindowedSummary lists their raw agent ids. Provider clients send it to the LLM as a user turn prefixed with [Summary of earlier conversation], so the model knows earlier history exists without seeing it. This keeps the LLM's behaviour grounded in long-running discussions without exploding the token budget.
Skills (Markdown Frontmatter)#
Skills are how an agent describes itself to other agents — markdown-with-frontmatter that's parsed by the hub and surfaced to LLM tools during peer lookup. Pass at registration:
The hub stores the markdown verbatim and parses the frontmatter via parse_skill_frontmatter:
Fallback Skills#
When no skill_md is provided, the hub generates one from the resume so peer lookup doesn't return empty handles:
Use this if you're constructing skills programmatically — for example, when a tenant uploads a resume but no markdown.
Updating a Skill After Registration#
Emits AUDIT_KIND_SKILL_SET. Same audit shape as set_resume; tenant code can replace skills at any time.
Picking a View#
Some heuristics for choosing or building a view:
- Short, focused exchanges —
FullTranscript(). Token budget isn't the bottleneck; coherence is. - Long-running discussions —
WindowedSummary(recent_n=N)withNtuned to your participant count and turn density. - Specialist agents that should ignore unrelated chatter — a custom view that filters by audience or tags.
- Privacy-sensitive workflows — a custom view that strips fields or redacts before projection.
Switching the view doesn't affect the WAL — every envelope is still there, every operator can still inspect it. Only the LLM's perception of history is shaped by the view.