# Get Typed Values from an Agent Step (https://www.shipfox.io/docs/how-to/author-workflows/use-structured-agent-outputs)

Description: 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 [#declare-the-outputs-and-read-them]

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

```yaml
# 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:

1. **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.
2. **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.
3. **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 [#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](https://www.shipfox.io/docs/reference/workflow-schema#step-outputs).                                   |
| Use the value in another job                        | Publish it as a job output. See [Pass values between jobs](https://www.shipfox.io/docs/how-to/author-workflows/pass-outputs).                                                                               |
| 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 [#verify-the-outputs]

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

1. Confirm that the agent sets every declared output.
2. Confirm that each later step received the value the agent set. In the
   example, the assessment line matches the `summary` output.
3. 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](https://www.shipfox.io/docs/reference/workflow-schema#step-outputs) for the
exact behavior.