Agent metadata
Every Pipelogic component ships a machine-readable agent brief alongside its component.yml and README.md. The brief tells an agent or an operator what task the component fits, which shapes it accepts, which surprises a caller would otherwise hit, and which setup it needs before it can run. README.md carries the human-facing narrative and component.yml the typed catalog contract; the agent brief is the structured spec a model consumes when deciding whether to pick a component for a graph, how to wire it, and what runtime quirks to anticipate.
The brief is authored as AGENT.yml — the canonical format — or supplied as AGENT.json, the same schema serialized for tools that emit machine-generated payloads. A component carries one or the other; if both are present the upload is refused. The manifest is parsed against a fixed schema, so catalog facts that already live in component.yml — parameter keys, port types, tags, neighbors, alternatives — stay there and are never duplicated in the brief.
A manifest declares a schema_version, a one-sentence summary shaped input → transformation → output, a pick_when list, classified behavior_notes, and optional required_setup and outputs blocks. The pick_when list phrases each entry as a caller-facing decision (ship binary image frames to a webhook) rather than as the component's mechanics, paired with a data_shape describing the typed flow and an optional constraint describing the precondition. behavior_notes classifies each note as a hard_constraint, silent_fallback, parameter_interaction, edge_case, state_lifetime, or ordering rule so agents can scan the right ones for the question they are answering. Templates of the form {{type:Foo}}, {{component:bar}}, and {{param:baz}} resolve at render time to keep the surface consistent across renames.
The full field reference, the behavior_notes taxonomy, the upload flag, and the rules around what NOT to write live in the CLI:
ppl docs get component-api/agent-metadata
ppl docs get component-api/component-contract
ppl docs get file-api/file-types
ppl docs get concepts/solutions