First AI Call in a Nimi App
Use the App's host-bound SDK client to make one real text-generation request. Nimi Home establishes the App session; Runtime reads that App's saved AI configuration and chooses the implementation when execution starts.
This guide continues the --features studio-create example in Create a Nimi App, using public App Tools 0.2.7. Keep the generated SDK/Kit binding. The App renderer does not need a gRPC endpoint, account ID, session token, or a caller-selected App identity.
Before the Call
- Start the project with
pnpm devin a compatible Nimi Home development environment. Use its supervised Electron window, not the renderer URL in a browser. - Confirm that the generated
nimi.app.yamlincludesruntime.consume, then establish the App's required access through the host. Thestudio-createselection supplies the declaration; it does not grant access by itself. - Configure
text.generatefor this App through its AI settings or Nimi Home's App settings. A local route uses the machine's current model selection; a cloud route needs the appropriate configured connector and target. Saving configuration does not prove that generation will succeed.
Use development setup for prerequisites and Use Kit in an App for shared settings and host integration.
If the generated manifest has app_access: [], the project was created without the feature required by this example. Follow the creation guide's AI example in an empty directory rather than hand-editing the managed manifest or its lock. sync maintains the original feature selection; it does not add this permission.
Generate Text
The default starter already exports getNimiLocalAppClient() from src/shell/auth/local-app-client.ts. Reuse it. In an existing App with a different file layout, use that App's equivalent host-bound client.
// src/first-ai-call.ts in the default App Tools 0.2.7 starter
import { getNimiLocalAppClient } from './shell/auth/local-app-client.js';
export async function generateText(prompt: string) {
const client = getNimiLocalAppClient();
return await client.ai.text.generateCandidate({
messages: [{ role: 'user', text: prompt }],
});
}Call generateText() from an App action and present the returned text. Show a loading state while the promise is pending; on rejection, show the actual error and an appropriate recovery action. Do not render a sample response as though it came from Runtime.
The request carries conversation content. It does not select a model, connector, execution endpoint, fallback, or machine binding. Runtime obtains the App identity from the protected host session and applies its current Local or Cloud intent. Provider credentials remain in Runtime-owned configuration.
Diagnose the First Failure
| Failure | Next step |
|---|---|
| No bound App session or an access error | Return to the supervised App launch and its host access flow. Do not replace the binding with a direct Node/gRPC client or supply your own identity. |
AI_CONFIG_NOT_FOUND or missing text.generate intent | Save the capability intent for this App in its AI settings, then retry the actual call. |
| Local model or cloud configuration is unavailable | Inspect that App's current settings and the Runtime-selected model or connector state. Preserve the actual error; a configured route is not a successful execution. |
| Runtime disconnected | Restore the existing Nimi Home/Runtime development instance, reopen the supervised App if needed, and retry the same action. |
| Execution fails after dispatch | Inspect the typed error and its available reason/action fields. Do not synthesize a client-side fallback or switch providers silently. |
For setup debugging, the same client exposes auth.status() and aiConfig.get(). These are current state reads, not substitutes for an actual generation request. More setup errors are covered in Troubleshooting.
Confirm the Result
Run the App repository's existing checks, then make one request in its actual supervised window using its own client. Confirm pending, success, and any observed failure separately. A returned greeting can verify the first capability call; it does not establish that the App's full product journey or public distribution is ready.
Do not copy Nimi's repository-wide SDK/Lab test commands into a third-party App as a prerequisite. Follow the scripts declared by that project.