Get Typed Values from an Agent Step

Make an agent publish typed outputs that later steps and conditions can read. The example runs a review step only when the agent decides it is needed.

Use typed outputs when a later step needs a value from an agent. Typical values are a decision, a label, a number, or a short summary. The workflow reads a named value with a known type. You don't need to parse the agent's text answer.

The example below asks an agent if a release needs human review. To ask another question, keep the same structure and change the prompt and the output names.

Declare the outputs and read them

Create .shipfox/workflows/classify-release-risk.yml. This is a complete workflow:

# yaml-language-server: $schema=https://www.shipfox.io/docs/workflow.schema.json
name: Classify release risk
runner: shipfox

triggers:
  manual:
    source: manual

jobs:
  assess:
    steps:
      - key: assess
        prompt: |
          Review the repository for release risk.
          Set summary to one sentence that explains the main risk.
          Set needs_review to true when a person should review before release.
        outputs:
          summary: string
          needs_review: boolean

      - env:
          SUMMARY: "${{ steps.assess.outputs.summary }}"
        run: |
          printf 'Assessment: %s\n' "$SUMMARY"

      - if: '${{ steps.assess.outputs.needs_review == true }}'
        run: echo "Human review required"

To get any typed value from an agent, you need three things:

Declare the output. Give the agent step a key and list each output name and type under outputs. Shipfox gives the agent a set_output tool for each declared output.
Ask for the output in the prompt. Name each output in the prompt and say what value it must hold. The agent learns what needs_review means only from the prompt.
Read the output in a later step. Later steps read steps.<key>.outputs.<name>, the same way they read the output of a run step.

Commit and push the file to the project's default branch. Wait for Classify release risk to sync.

Adapt it to your workflow

To...	Change this
Run or skip a later step	Declare a `boolean` and read it in the step's `if`, as the example does.
Choose between more than two paths	Declare a `string` and list the allowed answers in the prompt. Compare the value in the `if` condition of each later step.
Return a list or an object, such as review findings	Declare a `json` output. Add a `schema` when later expressions need known fields. See Step outputs.
Use the value in another job	Publish it as a job output. See Pass values between jobs.
Use the text in a shell command	Put it in `env` and read the environment variable, as the example does with `summary`. The shell then treats the agent's text as text and doesn't run it as part of the command.

Keep each output small and specific. Use one output for each decision. Small outputs are easier to check than one large answer.

Verify the outputs

Start the workflow and open the job with the agent step.

Confirm that the agent sets every declared output.
Confirm that each later step received the value the agent set. In the example, the assessment line matches the summary output.
Confirm that each if condition gave the expected result. In the example, the final step runs when needs_review is true. When it is false, Shipfox marks the step as skipped.

If the agent doesn't set a required output, Shipfox asks it again a limited number of times. If the output is still missing, the step fails. See Step outputs for the exact behavior.

Was this page helpful?

Edit this page on GitHub

Get Typed Values from an Agent Step

Declare the outputs and read themCopy Anchor Link

Adapt it to your workflowCopy Anchor Link

Verify the outputsCopy Anchor Link

On this page

Declare the outputs and read them

Adapt it to your workflow

Verify the outputs