A real integration falls into a recognizable sequence. Create an agent together with its first run, subscribe to the event stream, show the user what is happening, collect the artifacts, clean up after yourself. There is a subtlety here that people trip over: an event stream is a connection, and connections break. An event that arrived over the stream is a hint rather than a ledger entry; the source of truth about a run's state is the endpoint that returns that state. So the stream always has a fallback path: reconnecting and polling the state rather than an interface silently hanging.

Three things are lacking most often in an integration. Cancellation - without it a long run cannot be stopped programmatically, and waiting remains the only option. Usage accounting - without it cost becomes clear at the end of the month, when influencing it is too late. And cleanup: archiving, restoring and deletion exist for a reason, otherwise durable agents accumulate the way branches accumulate in an old repository, and six months later nobody can say which of them are still needed.

The token endpoint stands apart. It mints a one-hour user-scoped token so that a self-hosted worker runs as an active member of the team; minting it requires an agent-scoped key of a team service account, and the token neither refreshes itself nor mints further tokens. The rule is the same as in any permission system: grant as much as the specific work requires and for the duration of that work.

The key information endpoint is worth remembering separately: it answers what the key is - its name, creation date and owner - and the presence of owner fields shows whether it is a user key or a service account key. That is cheap diagnostics for the case where an integration is refused and it is unclear which key it is even using. The model list has the same purpose: it answers what is available to your account now rather than what was available on the day the code was written, which is why a model name hard-coded into configuration is worth checking against it at startup.

The list of connected repositories stands apart because of its strict rate limit. That is a direct architectural hint: the list is cached. An integration that calls it on every user action is designed wrongly and will hit the limit at the first spike of load - and it will hit it not only for itself but for every consumer of the same key.

The engineering conclusion is simple: before writing an integration it helps to run your eyes over the groups and mark which endpoints you actually need. The set usually turns out small - creation, the event stream, cancellation, artifacts and cleanup. Everything else is added as a need appears rather than in advance: unused integration code ages faster than any other.

The typical failures are predictable. Not implementing cancellation and having no way to stop a run. Treating the event stream as the source of truth and hanging when the connection drops. Ignoring usage accounting. Accumulating agents without archiving or deleting them. Handing a self-hosted worker the full key instead of a one-hour user-scoped token. And fetching the repository list without a cache.