Examples

Each example compiles against Platform SDK v1.2.0. Helpers they call (FindNotes, PickModel, ReplyText, toolText) are defined on the Search and Models pages.

A grounded answer from project notes

Find notes in one project folder, read the files that matched, ask the organization's model to answer only from them, and record the call.

// AnswerFromProject finds notes in one project folder, reads the files
// that matched, asks the organization's model to answer only from them,
// and records the call in the audit chain.
func AnswerFromProject(ctx context.Context, c *platformsdk.Client, userID, project, term, question string) (string, error) {
	hits, _, err := FindNotes(ctx, c, project, term)
	if err != nil {
		return "", err
	}
	seen := map[string]bool{}
	var sources strings.Builder
	for _, h := range hits {
		if seen[h.Path] || len(seen) == 5 {
			continue
		}
		seen[h.Path] = true
		body, err := c.Vault().ReadBytes(ctx, h.Path)
		if err != nil {
			return "", fmt.Errorf("read %s: %w", h.Path, err)
		}
		fmt.Fprintf(&sources, "### %s\n%s\n\n", h.Path, body)
	}
	if len(seen) == 0 {
		return "No notes in this project mention that term.", nil
	}

	model, err := PickModel(ctx, c)
	if err != nil {
		return "", err
	}
	out, err := c.LLM().Call(ctx, platformsdk.LLMCall{
		ProviderID: model,
		System:     "Answer only from the sources. Cite the source path for every claim. Say so if the sources do not answer the question.",
		Prompt:     sources.String() + "Question: " + question,
	})
	if err != nil {
		return "", err
	}
	answer, err := ReplyText(out)
	if err != nil {
		return "", err
	}
	if err := c.Audit().Append(ctx, platformsdk.AuditEvent{
		Actor:  "ext:hello-notes",
		Action: "llm.call",
		Object: "projects/" + project,
		Result: "ok",
		Extras: map[string]any{"on_behalf_of": userID, "model_id": model, "sources": len(seen)},
	}); err != nil {
		return "", fmt.Errorf("answered but audit append failed: %w", err)
	}
	return answer, nil
}

Before calling it for a user, check that the user may read that project (see Governance). In production, also verify that the paths the model cites are among the sources you sent.

Listing the integration catalog

Integrations().List is read-only and makes a good start-up canary as well as a picker.

func ListIntegrations(ctx context.Context, c *platformsdk.Client) ([]string, error) {
	cat, err := c.Integrations().List(ctx)
	if err != nil {
		return nil, err
	}
	names := make([]string, 0, len(cat))
	for _, d := range cat {
		names = append(names, fmt.Sprintf("%s (%s, %d events)", d.Name, d.Slug, len(d.Events)))
	}
	return names, nil
}

Get(ctx, slug) returns one descriptor (404 when absent), PayloadSchema and AllPayloadSchemas describe event payloads, and Subscribe runs the platform's webhook-subscribe playbook for an integration, with the platform making the vendor-side calls.

Calling a vendor API with the organization's OAuth connection

Resolve the bearer at call time; never cache or log it.

func CallVendor(ctx context.Context, c *platformsdk.Client, hc *http.Client, url string) (*http.Response, error) {
	b, err := c.OAuth().ResolveBearer(ctx, platformsdk.OAuthBearerRequest{
		IntegrationSlug: "github",
	})
	if err != nil {
		return nil, err
	}
	if !b.Resolved {
		return nil, fmt.Errorf("no github connection for this org: %s", b.Reason)
	}
	req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
	if err != nil {
		return nil, err
	}
	req.Header.Set("Authorization", b.BearerHeader) // never log this value
	return hc.Do(req)
}

Resolved: false is the normal state before anyone connects the vendor: show "Connect GitHub in settings". Pass ConnectionID when the user picked a specific connection.

Reading a vendor API key from Operator ENV

func VendorAPIKey(ctx context.Context, c *platformsdk.Client, slug string) (string, error) {
	rec, err := c.OperatorEnv().Get(ctx, slug)
	var apiErr *platformsdk.APIError
	if errors.As(err, &apiErr) && apiErr.StatusCode == http.StatusNotFound {
		return "", fmt.Errorf("operator has not configured %q", slug)
	}
	if err != nil {
		return "", err
	}
	if rec.APIKey == "" {
		return "", fmt.Errorf("%q is recognized but has no API key yet", slug)
	}
	return rec.APIKey, nil
}

"Not configured" (404) and "configured but empty" are different messages for an administrator. Use the key for one outbound call and drop it.

Querying a connected system through Data Pipe

When the organization has the Data Pipe extension installed, its tools are available through MCP().Tool. Discover sources with list_sources, then query one:

func LaneRows(ctx context.Context, c *platformsdk.Client) (string, error) {
	text, _, err := toolText(ctx, c, "datapipe", "query", map[string]any{
		"connector_id": "tms-warehouse",
		"locator":      "lane_exceptions",
		"limit":        50,
	})
	return text, err
}

tms-warehouse and lane_exceptions stand in for whatever list_sources returns in your organization. An APIError 502 whose body includes status=501 means the server or tool is not installed on this pod.

A complete extension

The bRRAIn Certified SDK Developer course builds a full governed extension, from manifest and packaging through tests and marketplace submission.