`agentHints`: Teaching CLIs to Talk to Agents

This is a 10-part series sharing how Apidog developed Apidog CLI, a command-line tool for API testing and API lifecycle management. Read in order or jump to any post that interests you:

Traditional CLI output is for humans. Agents need structured results, failure reasons, and next-step suggestions. agentHints turns product experience into machine-readable guidance.

The CLI Output Gap

Traditional CLI output is designed for humans.

This works for people. Humans can:

• Interpret vague messages
• Decide what to do next
• Remember context from earlier commands
• Apply domain knowledge to proceed

But Agents work differently.

What Agents Actually Need

Agents don't just read results. They need to connect results to the next task chain.

A human sees "Resource created successfully" and knows: "I should probably check what was created, then maybe run some tests."

An Agent sees "Resource created successfully" and... has no idea what to do next.

agentHints: The Solution

Apidog CLI adds agentHints to its output.

Here's what a typical response looks like:

{
  "success": true,
  "data": {
    "id": "12345",
    "name": "Health Check Test Case"
  },
  "agentHints": {
    "summary": "Test case created successfully.",
    "nextSteps": [
      "Read the created test case back to confirm structure.",
      "Add assertions if the test case needs response validation.",
      "Add the test case to a test scenario for integration testing.",
      "Run related tests after adding to scenario."
    ]
  }
}

Three components:

The Execution Inertia Problem

Here's a real problem we observed:

After successfully creating a resource, the model often continues directly to generate the next write.

Example:

Agent: Creates test case
CLI: Returns success
Agent: Immediately creates test scenario (without reading back)
Agent: Immediately runs tests
Result: Scenario has wrong structure, tests fail

In complex business processes, mechanical continuous execution is not appropriate.

The most correct approach is often:

1. Create resource
2. Read back first
3. Confirm structure
4. Then proceed

Why Read-Back Matters

Skipping read-back causes real problems:

If the real structure is not read back, the Agent easily continues writing based on its own guess—not on actual data.

agentHints as Navigator

agentHints turns product experience into machine-readable next-step suggestions.

It appears exactly where the Agent needs to make decisions.

Example after creating a test case:

{
  "agentHints": {
    "nextSteps": [
      "Read back the created test case with --with-case-detail flag.",
      "Validate any updates with cli-schema before writing.",
      "Run tests after completing test scenario."
    ]
  }
}

The Agent:

1. Reads the output
2. Parses agentHints
3. Follows nextSteps[0]: reads back the test case
4. Confirms the actual structure
5. Then proceeds with accurate information

CLI Role Transformation

This changes what CLI means in the Agent workflow.

CLI becomes a lightweight state navigator.

Built-In Workflow Trees

Apidog CLI has built-in thousands of tree-structured workflows.

These aren't just hard-coded suggestions. They're:

Example after successful test scenario update:

{
  "agentHints": {
    "summary": "Test scenario updated successfully.",
    "nextSteps": [
      "Run the test scenario to verify changes.",
      "Check the test report for any failures.",
      "If failures occur, read back scenario steps for debugging."
    ]
  }
}

Example after validation failure:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Field 'comparator' has invalid value",
    "details": [...]
  },
  "agentHints": {
    "summary": "Validation failed. Fix the errors and re-validate.",
    "nextSteps": [
      "Review the error details in the output.",
      "Adjust the JSON file based on error suggestions.",
      "Re-run cli-schema validate before writing."
    ]
  }
}

Even failures become navigable.

The Safer Loop With agentHints

Let's trace a complete workflow with agentHints:

Step 1: Agent creates test case
        ↓
CLI Output: success + agentHints
        ↓
agentHints.nextSteps[0]: "Read back the created test case"
        ↓
Step 2: Agent reads back (with actual structure)
        ↓
CLI Output: test case structure + agentHints
        ↓
agentHints.nextSteps[0]: "Add assertions if needed"
        ↓
Step 3: Agent adds assertions (based on actual structure)
        ↓
CLI Output: success + agentHints
        ↓
agentHints.nextSteps[0]: "Run tests"
        ↓
Step 4: Agent runs tests
        ↓
CLI Output: test report

Every step is guided. No blind jumps. No assumptions.

Comparison: With and Without agentHints

What's Next

Now that CLI can guide Agents through next steps, the remaining question is:

How do Agents know which workflow to follow in the first place?

In Part 5, SKILL: Shipping Operational Experience as Code, we'll explore how SKILL packages workflow knowledge—when to use commands, what sequence to follow, and what fields shouldn't be guessed.

Key Takeaways

• Traditional CLI output is human-oriented; Agents need structured guidance
• agentHints provides summary + next-step suggestions in JSON output
• Execution inertia causes Agents to skip read-back; agentHints prevents this
• CLI transforms from executor to navigator
• Built-in workflow trees make every step navigable
• Even failures become actionable with agentHints

Download Apidog to design, mock, test, and document APIs in one workspace. Learn more about Apidog CLI for command-line API testing, CI automation, and AI Agent workflows.