# Components and Connection Rules

The three parts of a component, and the eight primitives with the rules for what each one connects to.

- Page: https://perceivo.ai/university/orch-04-components-and-connection-rules
- JSON: https://perceivo.ai/registry/film/orch-04-components-and-connection-rules.json
- Kind: film
- Revision: 4 (published 2026-10-18, produced 2026-10-15)
- Previous revision 1 (published 2026-10-07): https://perceivo.ai/registry/film/orch-04-components-and-connection-rules/r1.json
- Previous revision 2 (published 2026-10-11): https://perceivo.ai/registry/film/orch-04-components-and-connection-rules/r2.json
- Previous revision 3 (published 2026-10-12): https://perceivo.ai/registry/film/orch-04-components-and-connection-rules/r3.json
- SDK version: none

## Validation

- SDK: not applicable (UI walkthrough; no component or orchestration is offered for download)
- Platform: not applicable (UI walkthrough; no component or orchestration is offered for download)

## Transcript

[0:00] Introduction to Orchestrations, Episode 4: Components and Connection Rules
[0:06] Welcome back to our Introduction to Orchestrations series.
[0:10] Today: components, the parts every orchestration is built from.
[0:14] Every component plugs in through typed ports.
[0:17] Typed contracts guarantee your script gets the information it needs.
[0:21] And these rules create structure that forces desirable behaviors out of your coding agent.
[0:28] We go deep on them in our Introduction to Components series.
[0:32] A component has three parts.
[0:34] A contract, defined in its manifest.
[0:38] Every port, and the data it carries.
[0:41] A script, which inherits from one of Perceivo's primitive classes.
[0:46] This one is a tool.
[0:47] And metadata: a name, a description, and access controls.
[0:53] There are eight primitives, and each one has its own rules about what it connects to, and what it can do.
[0:59] Let's go through them.
[1:01] We'll start with tools, the most flexible primitive.
[1:04] A tool's script can do pretty much anything.
[1:08] Every component is written with the same SDK, so everything it can do is available to every component.
[1:15] The documentation walks through all of it.
[1:19] And the SDK, with its examples, is open source on GitHub.
[1:23] Call a tool, and it answers back.
[1:26] Give a tool its own tool ports, and tools can call tools.
[1:30] Tools are never on the main flow.
[1:33] An agent, a policy, a state machine, or another tool calls them.
[1:38] An adapter is a one-way translator.
[1:41] It takes data in, reshapes it, and passes it on.
[1:44] Unlike a tool, it gives nothing back.
[1:48] Adapters sit on the main flow, or serve as a state in a state machine.
[1:53] An agent can't call one like a tool, and an adapter never passes on to a policy.
[1:59] Agents hold the reasoning.
[2:01] Two things set an agent apart.
[2:04] Every agent output leaves a snapshot.
[2:06] And an agent is the only component that writes to the conversation log.
[2:12] An agent can call tools, up to fifty of them, and ask for a review.
[2:17] Then it passes on to another agent, or to a state machine.
[2:21] That's how agents stack into layers.
[2:25] A state machine and its policy work as a pair.
[2:28] A machine can hold up to fifty states, but aim for about five.
[2:33] Each state is a component, even another state machine.
[2:37] The policy decides the next state.
[2:39] It's stateless, it can read the conversation log, and the only thing it can call is a tool.
[2:45] Because the policy is separate, you can swap it out, and compare policies on the same machine.
[2:52] Start and End are a pair too.
[2:55] Start is the front door.
[2:56] It receives an artifact and request data, from the Start Run dialog, or from the API.
[3:03] End is the finish line.
[3:04] Its output is the run's result, and it can mark the run as failed.
[3:10] Start and End connect a run to the outside world.
[3:13] A review is the third way to reach it, from inside an orchestration.
[3:19] Mark a review required, and the run pauses until a person answers.
[3:23] That's how you get human input mid-run.
[3:27] Mark it not required, and the run keeps going.
[3:30] The review is there to evaluate the result later.
[3:34] In Perceivo, component ports are typed and validated.
[3:38] This ensures that if your script is looking for a variable with a particular name, the component that calls it passes a variable with that name.
[3:46] It creates structure, and discipline.
[3:50] You can define port contracts in a few ways.
[3:53] Let's use the UI to create one.
[3:55] Let's add a tool, call it intake, and add a couple of ports.
[4:00] Ports have a name, and a type.
[4:03] And they define four things.
[4:05] The input artifact type.
[4:07] The request data: an object of typed key-value pairs.
[4:12] An output artifact.
[4:14] And the response data object.
[4:17] This dialog defines the request and the response.
[4:20] The artifact types belong to the component itself, and we set those when we build one, next time.
[4:28] Intake's in port receives an array of files, and a note.
[4:32] And it returns a summary.
[4:35] Next, a tool port.
[4:36] It passes the array of files out, to the tool it calls.
[4:41] And it expects a string called summary back, in the response data.
[4:46] Now a second tool, called processing, with only an in port.
[4:50] It accepts an array of files, and a note.
[4:53] And it responds with just a summary.
[4:57] Let's connect them, and click Validate.
[5:00] Well, it appears we have a problem.
[5:03] Intake's tool port sends only the files, not the note.
[5:06] Processing wants both, so as configured, these ports aren't compatible.
[5:12] We can fix that by correcting either port contract.
[5:16] I don't want the second tool to have the note.
[5:19] The first tool filters it.
[5:21] So I open processing's port contract, and remove the note parameter.
[5:26] Now the contracts match, and Validate leaves the connection in place.
[5:31] Next time, we build a component of our own, step by step.
[5:35] See you there.