You do not need everything on day one.
Start with the app. Add one model, then add evidence and controls. Cloud hosting comes last.
Local setup checklist
- Get the reviewed workshop revision from the published repository. Open a terminal at the repository root.
- Check Python 3.12+ and uv are installed. Run
uv sync --frozen --extra studio. - For an API-only or locally hosted model, obtain the exact alias and confirm native streaming/tool support. A coding-assistant subscription is separate from runtime API entitlement.
- Copy the example TOML from
workshops/local-ai-studio/studio.example.tomlinto an ignored private directory. Set file mode 0600. Edit only your own endpoint/alias and environment references. - Start with telemetry disabled. Prove one real tool-call task, then enable your own Langfuse destination. Never copy the trainer’s credentials.
- Use a fresh output directory for each server launch. If port 8770 is occupied, identify its owner and choose another port; do not kill an unknown process.
Mac, Linux and Windows with WSL can follow the terminal commands. Browser-only participants can complete the product sketch and architecture exercises but cannot claim runtime acceptance.
What should I keep after each part?
Keep source changes, the exact command, synthetic input, actual outcome and an evidence reference. Raw answers, traces, recordings, endpoints and secrets stay private by default. Use the workbook for a sanitized summary; task checkboxes do not prove execution.
What can the supplied code do today?
The local Studio supports real streaming model/tool calls, session-scoped JSON ticket actions, bounded registered synthetic tools and explicit Langfuse OTel export. Its model and backend acceptance still depend on your configuration. The static product sketch has no AI. The hosted OCI coordinator and its telemetry integration use a separate protocol/configuration; Part 6 makes that adapter work explicit.
The course pages and local tests are supplied. Cloud accounts, model credits, recorded course videos, production authentication and a running learner sandbox are not bundled.
Stuck? Start with the symptom.
What should I build first?
One operator, one ticket inbox and one read-only investigation. You do not need a database or cloud account to explore the product sketch.
Try asking: “Which information would let an operator decide their next safe check?” Write that down before choosing a model.
My preview looks good. Am I done?
Create a new synthetic ticket, search for its title, filter it out, clear the filter and select it again. A screenshot alone cannot prove these controls work.
If a control is decorative, ask the builder to implement only that interaction and retest it. Keep the AI panel disconnected until the controls work.
Why does Analyze safely fail?
Check whether the request reaches your own server, then inspect its sanitized error. Confirm the exact configured model alias, authentication binding and native tool support.
Start with one ordinary greeting, then one health question. Change one setting at a time; never substitute a canned answer for a failed model call.
The answer arrived, but where is the trace?
Separate local recording, exporter delivery and backend readback. Check the exporter destination and auth without printing keys; then search the exact trace ID in your own project.
A missing trace is a telemetry failure, not proof that the model failed. Do not repeat paid inference just to repair a collector.
Why can’t the model approve the change?
Approval is an application control. The change intent is stopped before model construction, even if a prompt asks it to ignore policy.
Run the policy exercise and inspect its zero-generation result. Then compare an allowed read-only question with an unavailable write-tool request.
Do I need OCI to complete the first hour?
No. You can finish the local app and explain its target architecture. A live hosted invocation needs your own scoped tenancy, identity, image and network path.
Use the deployment-preparation prompt to produce a reviewable packet. Keep a source walkthrough labelled as such until a hosted invocation and its trace are verified.
The words we use
Agent
A program that can ask a model what to do next, execute a permitted tool and use the observation to continue.
Model
The component that produces text or proposes a tool call. It does not own application permissions.
Harness
The surrounding program that manages messages, tools, authorization, state, budgets and observation.
Tool
A registered function with a bounded input schema and a reviewed handler. It is not an arbitrary shell command.
Observation
The result returned by a tool, including an explicit error. It is untrusted data for the next step.
Session
The server-owned conversation context that can group several turns. It is not automatically an authenticated enterprise user.
Trace and span
A trace follows one action; spans describe individual operations and their parent/child relationships.
Token usage
The input/output counts reported by the provider. Missing usage is unknown, not zero.
Estimated cost
A calculation using reported usage and matching configured rates. It is not a billing invoice.
OTel
OpenTelemetry: libraries and protocols for recording and exporting operational signals.
Langfuse
A destination for analyzing configured agent/model observations, usage and evaluation data.
APM and logs
APM helps follow application requests; operational logs record events. Each destination needs its own delivery and readback checks.
Ask your coding assistant for a useful explanation
Explain the current task using one OpsDesk ticket. Show what runs in the browser, what runs on the server and what the model proposes. Help me inspect the actual failure without printing keys or changing permissions. Give me one next check and its expected result. Do not invent a successful output.