> For the complete documentation index, see [llms.txt](https://docs.appmixer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appmixer.com/build-connectors-with-a-coding-agent/research.md). # Scope and Research Chapter 2 gave you one working component. Turning it into the connector you need takes the agent minutes; the quality of the result is decided by what you say first. ## What the agent needs from you Four things: * **Which operations**, named in your own words — not "the events API" but *list the events of an organization, get a single event by id, create a new event*. * **Which triggers**, and what should make them fire. * **The documentation URL.** * **Rate limits**, if you know them. If you do not, say so; a limit tighter than the service's own is worse than none. A brief that works: > Add these components: list the events of an organization, with an option to filter them by status, get a single event by id, create a new event, and a trigger that fires when a new event shows up. In the inspector I want to pick the organization from a dropdown, and wherever an event is needed I want to pick it from a dropdown too — but it should only offer events from the organization I selected. Also add the MakeApiCall component. Compare "Add support for events." Both are short, but the first names the operations, separates actions from a trigger, answers the validator's `MakeApiCall` rule from chapter 2, and — most usefully — says what the **inspector** should feel like. Everything the second leaves out is a guess you find out about in chapter 5. ### What to check in the result The agent turns a brief like that into decisions nobody wrote down. Expect, and check: * **One output schema, shared.** Components that emit the same object should take its shape from one place (such as `lib.js`), so they cannot drift apart. * **List becomes Find when it filters.** A component with a filter and a *not found* output must be named `Find…`; the validator rule `find-naming-by-shape` enforces it. * **A polling trigger skips the back catalogue.** Its first check should only record what already exists. * **Dropdowns cache their results**, so opening an inspector does not send a burst of requests. * **`MakeApiCall` sends the token only to the service's API host.** And one the agent can get wrong. "Only offer events from the organization I selected" means the event dropdown calls the list component with the chosen organization — and with none until one is picked. So that input **must not be required in the schema**: the engine validates required inputs before the behaviour runs, which turns an empty dropdown into a validation error. Assert it inside the behaviour instead. Nothing in chapter 5's first two layers notices when this is wrong; only the third does. ## Naming, and the decision hiding inside it Component names mirror the directory layout: ``` ... src///// ``` **`` is yours.** `appmixer` is only the scaffolder's default. If your company is `acme`, your components are `acme.eventbrite.core.FindEvents`. Check what you may publish under: ```bash appmixer user me # the vendors your account may publish under ``` and have the agent rename the connector now if they differ. Renaming after publishing renames every component and leaves the old ones on the instance. ## Declare the output properly Every output port gets typed fields with `example` values. It is the highest-leverage paperwork in the guide: * the Designer's variable picker shows your users something meaningful; * `appmixer connector verify` can compare what you declared with what the API returns (chapter 5); * E2E flows can map variables between components without running them first. See [outPorts](/building-connectors/manifest/outports.md) for the schema and [Manifest](/building-connectors/manifest.md) for every other key. {% hint style="info" %} **`aiDescription` is recommended, not required** — at most 1000 characters, written for AI Copilot's component discovery rather than for the Designer. A component without one works — Copilot falls back to `description` — but it is found less reliably. The agent does not add it unless asked, and nothing later checks for it. See [aiDescription](/building-connectors/manifest/aidescription.md). {% endhint %} ## Give it the real icon The scaffold's icon — in `service.json` and in every `component.json` — is a placeholder. Supplying the real one is your job: services rarely publish an SVG mark an agent can fetch cleanly, and whether you may use a company's logo is a question for its brand guidelines. The validator's `component-icon-svg` rule checks the format, not the rights. Do it before the first publish. Changing the icon later is a change to every component, and each then needs a version bump ([Shipping Changes](/build-connectors-with-a-coding-agent/shipping-changes.md)). ## Verify ```bash appmixer connector validate ``` This is **offline**: it checks the shape of your source and makes no API calls. It will pass a connector that describes a completely different API — which is why chapter 5 exists. A typical result: ``` - (warn) [makeapicall-standards] src/acme/eventbrite/core/MakeApiCall/component.json: auth.scope is empty — OAuth-based MakeApiCall should declare scopes (most-privileged or all) Connector "acme/eventbrite": 0 failure(s), 1 warning(s). ``` Eventbrite has no OAuth scopes, so this warning is read and set aside. * **Exit `0`** means clean or within thresholds; **`1`** means a regression or a strict failure. `--json` gives the report as data; `--show-warnings` prints every warning. * **The ratchet**: validators listed in the thresholds file fail only when their count rises above the recorded threshold. A new connector has nothing to ratchet, so treat any failure as a failure. The exit condition is a clean run with every warning read. The agent will offer to test the new components straight away; saying yes is fine — [Testing in Three Layers](/build-connectors-with-a-coding-agent/testing.md) explains what those tests prove. Next: [On the Instance](/build-connectors-with-a-coding-agent/on-the-instance.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.appmixer.com/build-connectors-with-a-coding-agent/research.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.