1. How do I use AI Agent Studio?
  2. Build an Agentic Application with a Code Assistant

Build an Agentic Application with a Code Assistant

Scenario: Build a My Pipeline app for a salesperson.

Use the `aistudio` skill to build a local-only agentic app named “My Pipeline” in the current AI Studio project. Do not publish or save remote artifacts.

First, read the AI Studio skill instructions and all app/workflow/BO references needed for this work. Inspect the existing project layout and local artifacts. Do not run `init`.

Important: before creating or editing any AI Studio artifact, present the structured pre-build checkpoint requested below and wait for my explicit confirmation. This request is not itself authorization to create artifacts.

Goal
Build an agentic app for an individual sales representative. It must show only that rep’s own open leads and opportunities, help them prioritize those records, and support the confirmed write actions.

Data sources
Create exactly these two Business Objects and two app-backed workflows unless I explicitly approve additional artifacts:

1. Leads BO and Leads workflow
- Describe contract: `leads-describe.json` in the project root; if absent, retrieve the contract using the project’s configured Fusion authentication.
- REST resource: `leads`.
- Use the `MyLeadsFinder` finder, titled “My Open Leads,” for the open-leads scope.
- Relevant fields:
  - `LeadId`
  - `Name`
  - `PrimaryContactPartyName`
  - `DealAmount` — deal-size ranking value
  - `EstimatedCloseDate`
  - `Score`
  - `Rank`
  - `OwnerId`, `OwnerPartyName`, `OwnerPartyNumber`
  - `StatusCode`
- Supported operations:
  - collection read: `GET`
  - item read/update: `GET` / `PATCH`
  - `POST acceptLead(leadId)` — this is the closest available operation to “qualify,” but it is not named qualify.
  - `POST convertLeadAndGetOpty(leadId, opportunityName, opportunityOwnerNumber, enableCreateContact, enableCreateAccount, attributeMap)` — preferred conversion operation because it returns an object.
  - `POST convertLeadToOpty(...)` is also available.

2. Opportunities BO and Opportunities workflow
- Describe contract: `opportunities-describe.json` in the project root; if absent, retrieve it using the project’s configured Fusion authentication.
- REST resource: `opportunities`.
- Use the `MyOpportunitiesFinder` finder, titled “My Open Opportunities,” for the open-opportunities scope.
- Relevant fields:
  - `OptyId`
  - `Name`
  - `TargetPartyName` — account
  - `PrimaryContactPartyName`
  - `Revenue` — amount
  - `WinProb` — writable integer win probability
  - `StatusCode`, `LookupCategory`, `StageStatusCd`
  - `EffectiveDate` — close date
  - `OwnerResourcePartyId`, `OwnerPartyNumber`, `PartyName1`
- Supported operations:
  - collection read: `GET`
  - item read/update: `GET` / `PATCH`
  - Change probability by PATCHing only `WinProb`.

Identity and record scope
- Scope every read to the current logged-in sales rep and open records only.
- Prefer the two “My Open …” finders.
- Do not assume the service-account identity or `aistudio.fa-user` is the current rep.
- Determine how runtime user context maps to Fusion’s resource/party identifier. If launch context already provides the resource party ID, use it. If not, identify a supported source for resolving it; if the contracts do not provide one, flag that as a dependency in the pre-build checkpoint and wait for my decision.
- Do not implement a hard-coded owner ID or a broad unfiltered query.

Ranking
- Leads: rank descending by `DealAmount`; default top N is 8.
- Opportunities: rank descending by calculated expected value:
  `Revenue * (WinProb / 100)`.
- Perform ranking after retrieval if the API cannot sort by the calculated expression.
- Handle null amounts/probabilities safely and display a clear fallback label.

App experience
Create a “My Pipeline” agentic app with:
- A short text summary at the top: open lead count and total deal amount, open opportunity count and total revenue/expected value, plus the single highest-priority lead and opportunity.
- Panel 1: “Sales Lead Summary”
  - Default top 8 leads by `DealAmount`.
  - A ranked horizontal bar chart using lead name and `DealAmount`.
- Panel 2: “Opportunity Summary”
  - Default top 8 opportunities by expected value.
  - A bubble/scatter chart: x = `WinProb`, y = `Revenue`, bubble size = `Revenue`.
- Expanded Leads list columns:
  `Name`, `Primary Contact`, `Amount`, `Close Date`, `Score`, `Rank`.
- Expanded Opportunities list columns:
  `Name`, `Account`, `Primary Contact`, `Amount`, `Win Probability`, `Status`, `Close Date`.

Use the AI Studio-supported widget and layout contracts. Inspect the relevant app/widget references rather than inventing widget IDs or output payload shapes.

App-backed workflow design
- Implement real app-stage routing using `$context.$app.$OraMessageHint`.
- Provide separate, routable terminal paths for at least `InitDisplay` and normal query behavior. Do not implement multiple app stages in one shared terminal prompt.
- Fetch shared record data before the stage router where appropriate.
- Clarify in the checkpoint how the top summary will combine lead and opportunity facts while preserving the requested two-workflow scope. Do not silently create a third summary workflow.
- Add useful read-only free-form questions, such as “What should I focus on first?” and “Why is this opportunity ranked highly?”
- Do not add communications unless I explicitly approve them in the checkpoint.

Actions and side effects
1. Lead “Qualify”
- The qualify lead is  PATCH operation on the lead where you set the  `StatusCode` to `QUALIFIED`;
- Refresh the Leads list after the successful PATCH and verify that the persisted value remains after refresh.

2. Lead conversion
- Use `convertLeadAndGetOpty` after confirmation.
- Before execution, show the lead name and conversion inputs, explain that it creates an opportunity, and clearly state that the describe contract does not specify the source lead’s resulting status or lifecycle.
- After conversion, inspect the returned object and refresh the source lead and opportunity lists. Report the actual observed result rather than claiming that the lead was deleted, closed, or otherwise changed without evidence.

3. Opportunity probability
- Offer +10% and −10% actions.
- Calculate `newWinProb = min(100, max(0, currentWinProb ± 10))`.
- Require confirmation before PATCHing the item with only `WinProb`.
- Refresh the opportunity list after the successful PATCH and verify that the persisted value remains after refresh.

Pre-build checkpoint
Before creating artifacts, present this concise structured checkpoint and wait:

Data source
- Confirm the two Fusion REST contracts, the My Open finder for each source, and the user-to-resource-party resolution approach.

App goal and user
- Individual sales representative; own open leads and opportunities.

First-load experience
- Top summary, lead panel, opportunity panel, top-N default of 8, ranking calculations, and chart plan.

Query behavior
- Read-only natural-language questions and which workflow handles them.

Priority actions
- `acceptLead` mapping decision, `convertLeadAndGetOpty`, and `PATCH WinProb`.

Communications
- Omit for now unless I request them.

Side effects
- Confirmation requirements, refresh behavior, source-lead post-conversion uncertainty, and error handling.

Launch context
- Exact current-user/resource-party fields required, or the unresolved dependency.

Validation
- Demonstrate: on load, the rep sees the top 8 open opportunities ranked by expected value; changing one opportunity from 40% to 50% persists after refresh; the approved lead action changes the observed status; and converting a lead creates and returns an opportunity while the app reports the source lead’s actual post-conversion state.

Implementation and verification
After I approve the checkpoint:
- Create the two BOs, two app-backed workflows, and app artifacts through the bundled AI Studio CLI—not by hand-editing supported artifact structures.
- Validate every BO, workflow, and app.
- Run the required workflow/app test-sync process specified by the AI Studio skill.
- Do not claim validation passed unless command output proves it.
- End with a concise implementation summary, validation evidence, known limitations, and the exact unresolved behavior if the user-to-resource identity mapping or the Qualify-to-acceptLead mapping remains unapproved.
Note: You must provide a schema for the 2 business objects: Sales Lead and Opportunity. You can provide them as json files.

Instructions given to the code assistant

Use the code assistant to create the prompt that you can then pass to the assistant to build the agentic app. Here are the instructions used to generate the above prompt.
Use the /aistudio  skill to create a detailed prompt that I can use in codex to achieve the below
## Use Case
Build an agentic app called My Pipeline. 

## Purpose
- An agentic app that shows a sales rep their leads and opportunities and helps them progress both toward closure.
- Primary user: an individual sales rep. The app should scope to **that rep's own records** (see Record scope below).

## Questions
If you have any questions on the use case, feel free to ask.
## Data sources & authentication

Create two app-backed workflows and their corresponding business objects:

1. **Leads** — OpenAPI describe: `leads-describe.json`. This file can be found in the project folder.
2. **Opportunities** — OpenAPI describe: `opportunities-describe.json`. This file can also be found in the project folder.

Use the describe output as the source of truth for field names, resource operations, and any custom actions (do not assume field or action names).

**Authentication:** Use the authentication already setup in VS code project for this.

## Record scope

- Show only records **owned by the current rep**, and **open** records only.
- The current rep is the logged in user

## "Most important" definition

- **Lead importance** = deal size / deal amount. Higher amount = more important.
- **Opportunity importance** = a blend of amount and win probability (WinProb). Rank by **expected value = Amount × WinProb** so both dimensions count, unless the describe surfaces a better native ranking field.

## Summary section

Show a short text summary of the rep's pipeline at the top (e.g. count and total value of open leads and opportunities, and the single highest-priority item in each), then two panels.

### Panel 1 — Sales Lead summary

- Show the **top N (default 8)** most important open leads.
- Chart: a **ranked horizontal bar chart** of those leads by Amount. 

### Panel 2 — Opportunity summary

- Show the **top N (default 8)** most important open opportunities.
- Chart: a **bubble/scatter chart** — x = Win Probability, y = Amount, bubble size = Amount — so amount and probability are both visible in one view.
## Panel expansion

### Panel 1 expanded — Leads list

Columns: **Name, Primary Contact, Amount, Close Date, Score, Rank**

Actions on a lead (confirm the exact operation from the describe; these are likely custom actions, not plain field updates):
- **Qualify lead** — call the qualify operation. Ask for confirmation before writing.
- **Convert to opportunity** — call the convert operation. Ask for confirmation before writing, and state what happens to the source lead after conversion.

### Panel 2 expanded — Opportunities list

Columns: **Name, Account, Primary Contact, Amount, Win Probability, Status, Close Date**

Action on an opportunity:

- **Change win probability** — increment by **+10%** or decrement by **−10%**. Clamp the result to the **0–100** range. Confirm the write operation (likely a PATCH on the opportunity) and whether it needs confirmation before saving.

## Validation scenario

Prove the app works with this flow: `<<e.g. "On load, the rep sees their top 8 open opportunities by expected value. Nudging opportunity X from 40% to 50% persists on refresh. Qualifying lead Y changes its status, and converting lead Z creates an opportunity.">>`

## Build expectations

- Confirm the two business objects and the exact read/write operations from the describe endpoints before wiring anything.
- Present your structured pre-build checkpoint (data source, app goal/user, first-load behavior, panels, actions, side-effect handling, launch context, validation) and wait for my confirmation before creating artifacts.

## Before Creating the Prompt:
Before creating the prompt, confirm the business objects and API operations from the `/describe` endpoints, then present your prompt for my confirmation.