Domain 5 of 6 · Chapter 2 of 4

Configure observability for multi-agent behavior

Unlock the complete study guide.

Bundled into the existing Developing in Agentic AI Systems premium course — no separate purchase.

14-day money-back guarantee — no questions asked.

Included in this chapter:

  • What observability means once more than one agent is working
  • Produce artifacts a reviewer can actually use
  • Keep artifacts long enough for them to be evidence
  • Record handoffs with the events the platform already fires
  • Log every tool execution in a form your collector can parse
  • Correlate worker traces on a shared SDK stream
  • Reconstruct a session from VS Code's own records
  • Read run and task logs from the command line
  • Identify which task and revision a CLI record belongs to
  • Say what a worker must hand back
  • Exam reasoning: choosing the surface the question is asking for
The question in front of youThe surface that answers itWhat it actually containsThe tempting wrong pick
Which file did one named worker produce?actions/download-artifact with name setThat one artifact, extracted to the workspaceOmitting name, which pulls the whole run into per-artifact directories
What did every worker in the run produce?actions/download-artifact with name omittedEvery artifact, one directory per artifact nameAdding a download step per worker, which changes whenever the set of worker jobs does
Which worker ran, and what did it conclude?The subagentStop hook payloadagentId, agentName, transcriptPath, sessionId and the full final responseA sessionEnd or agentStop handler, which fires for the session or the coordinator's turn
Which worker was dispatched?The subagentStart hook payloadsessionId, timestamp, transcriptPath and agentName, before the worker runsExpecting the worker's answer, which does not exist yet at dispatch
What did the agent actually see and call?The VS Code Chat Debug viewRaw system prompt, user prompt, attached context and tool payloadsReading the conversational summary, which is the agent's account of itself — or reaching for an editor view when the run was a cloud agent task, whose own session log is the record
What did the session contain?Copy All when the record must show thinking steps and tool calls; Chat: Export Chat when prompts and responses must be stored as JSONCopy All: prompts, responses, thinking steps and tool calls (Markdown); Chat: Export Chat: prompts and responses (JSON) — the documented contents of eachCopy Final Response, which keeps only the closing section
Why did one job of an agent workflow fail?gh run view with --log-failed, plus --jobThe failed steps' part of the run log, narrowed to one jobThe full run log, where every other job's steps bury the failing ones
Which execution failed, before the reruns?gh run view with --attemptThat numbered attempt of the same run identifierThe default view, which reads the latest attempt
Which of four concurrent SDK workers does this subagent.started, completed or failed event belong to?toolCallId on the SDK subagent.* eventsOne worker execution, start paired with completed or failedagentName, which several workers of one agent share
Why is a review package missing?expires_at on the artifact REST record, then the run itselfThe scheduled deletion date; deleting the run removes all of its artifactsThe configured retention setting, which describes policy, not this artifact

Decision tree

What must you answer?Start from the question,not from the tool.What did a worker produce?Run artifacts, selected by nameWho ran, and what came back?Subagent hooks, or SDK eventsWhat happened along the way?In VS Code: Copy All, Chat DebugElse: postToolUse, agent-task logWhy did the job fail?gh run view: log-failed, job, attemptOn any branch: artifact gone?Check expires_at, then the runSDK stream, several at once?Correlate by toolCallId; attributeby the envelope agentId.Before you conclude:Deleting the run deletes itsartifacts, whatever retention said.
Cheat sheet

Cheat sheet

  • Artifact names distinguish a selected worker's evidence from the whole run's output
  • Revised outputs need distinct artifact names in the immutable artifact model
  • Artifact upload paths can collect selected files while excluding unrelated output
  • Artifact download verifies a digest but reports a mismatch as a warning
  • The subagentStart hook records dispatch before a worker begins
  • The subagentStop payload captures the worker's final output before its return
  • The general-purpose built-in worker is an exception to subagent lifecycle hook coverage
  • postToolUse records only successful tool calls; failures need postToolUseFailure
  • Hook parsers must match the configured event-name payload format
  • Chat export creates a reusable conversation record for review
  • Copy All preserves intermediate chat activity that Copy Final Response omits
  • Follow a selected agent task's logs rather than repeatedly listing tasks
  • Agent-task JSON links execution state to its pull request and repository
  • Use failed-step logs to narrow workflow-level failure analysis
  • Select the workflow attempt when comparing an original failure with a retry
  • Chat Debug reveals the actual prompts, context, and tool payloads used by an agent
  • Expanding a subagent tool call exposes its assignment, actions, and return
  • Workflow metadata supplies the code revision and operational result for an audit record
  • Per-artifact retention is bounded by repository, organization, or enterprise policy
  • Write access permits manual artifact deletion before expiration
  • Deleting a workflow run also deletes its artifacts
  • The artifact REST record exposes its scheduled expiration
  • Require worker returns to state changes, validation, and remaining blockers
  • Correlate SDK worker lifecycles by toolCallId and attribute traces by envelope agentId

Unlock with Premium — includes all practice exams and the complete study guide.

References

  1. Store and share data with workflow artifacts
  2. Downloading workflow artifacts
  3. Removing workflow artifacts
  4. REST API endpoints for GitHub Actions artifacts
  5. Customize agent workflows with hooks
  6. GitHub Copilot hooks reference
  7. Custom agents and sub-agent events in the Copilot SDK
  8. Fleet mode in the Copilot SDK
  9. Sessions and handoff
  10. Manage agent sessions
  11. Debug chat interactions
  12. Subagents in Visual Studio Code
  13. gh agent-task view
  14. gh run view
  15. gh agent-task list