Proposal: incubate portable Agent Profiles and Workflows #70
Replies: 1 comment
|
I took the Agent Profile half of this proposal through the Phase 1/2 work suggested above. Instead of starting with a schema, I built a candidate profile and tested its semantics across independent agent systems. The result suggests there may be enough portable semantics for an Agent Profile component, but the portable intersection is smaller than I expected. Code, fixtures, runtime traces, compatibility reports, and the full evidence write-up are here: https://github.com/hsperker/agent-composition-profile/ What I testedThe candidate started with:
I implemented runtime adapters for:
I also kept static lowering evidence for:
Why these runtimes?The runtime set was chosen to avoid testing only frameworks with similar abstractions. It combines widely used open-source agent frameworks with SDKs from major model/platform vendors, and deliberately covers different execution models:
The selection was based on ecosystem relevance and architectural diversity, not expected compatibility. The goal was to give each proposed semantic several different ways to fail. The runtime adapters construct native framework objects and exercise real framework code paths with deterministic models. The same portable fixture is used across targets. Separate probes test multi-agent relationships and Agent Plugin activation through real MCP handshake, discovery, and invocation over stdio and Streamable HTTP. A similarly named constructor argument does not count as preservation. Each mapping is graded as What survivedThe evidence points to this boundary:
That leaves a deliberately small profile: ---
name: technical-researcher
description: >
Investigates technical questions and produces evidence-backed conclusions.
skills:
- ./skills/source-evaluation
plugins:
- ./plugins/web-research
---
# Instructions
Prefer primary sources.
Verify material claims.For optional fields, I suggest one rule:
Agent composition and delegation are not the same thingThis was the clearest negative result. I started with a generic The frameworks exposed several different relationships:
These differ in observable behavior. They disagree about who keeps control, what context or state is shared, and how control returns. Treating a handoff or shared team as a fresh child function call is not lowering. It invents an orchestration policy. The experiment therefore rejects a generic behavioral It does not answer a weaker composition question:
There may be value in something like: agents:
- ./agents/researcher.agent.md
- ./agents/critic.agent.mdwith only one meaning:
That would be a composition relationship only. It would not imply an invocation mechanism. I have not tested that weaker relationship, and I am not proposing it as part of the first profile contract. It may belong on the Agent Profile, or it may belong in a separate package manifest. So I would sharpen the distinction this way:
Generic delegation, isolation, handoffs, teams, and workflows should stay outside the first Agent Profile contract. A future typed relationship such as Agent Skills compose wellAgent Skills mapped better than I expected. The metadata-first, on-demand activation model works even in frameworks without native Agent Skills support. An adapter can expose the skill catalog and a dedicated activation mechanism while preserving the published integration pattern. The experiment verified catalog disclosure and activation. It did not test context compaction or bundled resource access, so those remain This suggests that Agent Profiles should reference Agent Skills directly rather than define another skill representation. Agent Plugins compose too, but with important limitsI also tested real Agent Plugin activation, not just MCP configuration construction. A local deterministic plugin exposed echo tools over:
All eight runtimes completed MCP handshake, discovery, and invocation where their native MCP APIs could preserve the required configuration. Two findings stood out. Native MCP support is not automatically Agent Plugins support. Some MCP convenience APIs cannot preserve the Agent Plugins stdio working-directory contract. Hosts also need to implement Agent Plugins placeholder expansion and reserved variables themselves. Model-visible MCP tool names are not portable. Some hosts preserve the published tool name. Others prefix it with the server name or derive and hash another name. So an Agent Plugin reference can portably mean:
It cannot currently mean:
That seems like the right boundary for Agent Profiles: compose Agent Plugins, but do not redefine their lifecycle, naming, scoping, or MCP behavior. Model requirements make sense, but are not readyI still think this: model:
requires:
tool-use: trueis meaningfully different from this: model: some-provider/some-modelThe first expresses an agent requirement. The second selects a deployment. The clean ownership split is:
The problem is the vocabulary. There is no sufficiently standardized meaning for capabilities such as So I would keep Resulting boundaryRequired
Optional
Incubating
Outside the first Agent Profile contract
Open follow-up
Seven of eight runtime frameworks preserved the required fields. CrewAI was the exception. Its I think that failure is useful evidence. The profile should not grow merely to make every framework pass. Where I think this leaves the proposalI don't think this work establishes a new independent agent standard, and it does not establish implementer consensus. It does provide implementation evidence for the Agent Profile incubation proposed here. The portability problem seems concrete:
The evidence also suggests a boundary for what belongs in the portable layer and what does not. The next question therefore seems less about schema design and more about adoption: Would any Agent Plugins client implementers be interested in trialing a profile this small? If multiple independent clients are willing to trial it, the existing fixtures and compatibility suite could support the non-normative Phase 2 work proposed above. Repository: https://github.com/hsperker/agent-composition-profile/ I have not investigated the Workflow half of this proposal to comparable depth. These findings are limited to Agent Profiles. |
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Summary
I propose that the Agent Plugins roadmap explicitly incubate two additional portable component types:
This is not a request to add two large, Goose-specific schemas to the v1 conformance floor. The smaller request is to recognize distinct interoperability targets, collect implementations and fixtures, and standardize only the semantic intersection once multiple clients are ready to consume it.
Why these belong in a plugin package
Skills and MCP answer important questions:
Two common authoring intents remain non-portable:
These are not aliases for skills. An agent profile is selectable and may be delegated to an isolated context. A workflow is explicitly invoked and may accept inputs, select capabilities, compose other workflows, and define an output contract. Encoding either as a skill loses useful intent and makes hosts infer execution semantics.
A plugin should eventually be able to package capabilities (skills and MCP), lifecycle integration (hooks), specialists (agent profiles), and repeatable operations (workflows).
Existing implementation signal
There is already meaningful convergence for agent profiles:
Storage syntax differs, but author intent is close. A conservative first profile could standardize only a name, description, and Markdown instructions. Model selection, tool allowlists, delegation controls, permissions, and isolation policy should remain optional capabilities or host extensions until they converge.
There is also production evidence for workflows. goose recipes package instructions/prompts, typed parameters, model settings, MCP extensions, structured responses, retries, and subrecipes. Other clients expose parts of this intent through commands, prompt templates, automations, or orchestration, but formats are less converged. That makes workflows a candidate for evidence gathering and an interoperability profile—not for prematurely adopting the full goose format.
Proposed path
Phase 1: terminology and portability matrix
Add agent profiles and workflows to FUTURE_CONSIDERATIONS.md, clearly distinguishing them from skills and from each other. Gather examples from goose, Claude Code, Codex, and other interested clients. Classify each field or behavior as portable now, portable with capability negotiation, host extension, or intentionally out of scope.
Phase 2: non-normative profiles and fixtures
Publish example packages and round-trip fixtures for fully portable, partially portable, and unsupported cases. A possible package shape for discussion—not a schema proposal yet—is:
Phase 3: narrow normative component types
Only after multiple clients commit to consuming the profiles, define fixed discovery locations and versioned contracts. As with skills and MCP, this spec should preferably reference an independent format if one emerges rather than own every execution detail.
A first agent profile contract could be deliberately small: stable name, short discovery description, instruction body, and optional capability declarations whose unsupported values are reported and safely ignored.
A first workflow contract could focus on stable name and description, entry instructions or prompt, declared inputs, references to plugin-local components, optional composition, and capability/failure reporting.
Host responsibilities and non-goals
The package declares intent; the host remains responsible for execution. This proposal does not need to standardize process or conversation isolation, scheduling, model/provider availability, permission prompts, sandboxing, UI, concurrency, installation, dependency resolution, or a universal orchestration runtime.
A host may load an agent profile into the current context, delegate it to a child session, or report that delegation is unsupported. It may render a workflow as a form, CLI command, or chat action. Unsupported optional behavior should degrade explicitly rather than silently changing meaning.
Why neutral names?
I suggest agent profile rather than making “subagent” normative: the artifact describes a specialist, while the host decides whether it runs in-process or as a delegated session.
An agent profile defines who the specialist is and which skills it uses. A subagent defines how a task is executed in an isolated delegated session.
I suggest workflow as the component type and recipe as a recognized ecosystem term: “recipe” is clear in goose, while “workflow” is easier for other clients to adopt without inheriting Goose-specific semantics.
Relationship to existing discussions
This narrows the “packaged agent definitions” and subagent request raised in #35. It complements the hooks proposal: hooks react to lifecycle events, agent profiles define specialists, and workflows define explicitly launched orchestration. It differs from plugin-level orientation, which explains a package rather than defining an invocable specialist.
Disclosure: AI helped research existing discussions and edit this proposal.
Note: Agent profiles (custom agent) and subagents are related but distinct concepts. An agent profile is a reusable definition of a specialist; its role, instructions, and optional configuration. A subagent is an execution mechanism: an isolated delegated session that may run from an agent profile or from ad hoc instructions. Standardizing agent profiles therefore does not require standardizing subagent execution semantics.
All reactions