microsoft / microsoft/conductor

Add a native `type: http` step for calling HTTP APIs from workflows

Open
#222 2 comments 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

area:config area:executor enhancement idea
Dominant language
Python
Stars
448
Forks
65
Avg merge
1d 18h
Merged PRs (30d)
39

Description

Summary

Add a first-class HTTP step type so workflows can call REST APIs without shelling out through type: script + curl and parsing the response by hand.

Motivation

Lots of workflows need to fetch from or push to an HTTP endpoint between agent calls — pulling issue lists, posting comments, hitting a webhook, calling an internal service for ground-truth data. Today the only options are:

  1. type: script + curl — works but is verbose, has to manually parse JSON in a downstream Jinja2 expression, and loses type information.
  2. Wrap it in a tool — overkill for simple GET/POST.

A native HTTP step would be deterministic, fast (no subprocess fork), and put typed response data straight into context for routing and downstream prompts.

Proposed shape

agents:
  - name: fetch_issue
    type: http
    method: GET
    url: "https://api.github.com/repos/{{ workflow.input.repo }}/issues/{{ workflow.input.number }}"
    headers:
      Authorization: "Bearer {{ env.GITHUB_TOKEN }}"
      Accept: "application/vnd.github+json"
    timeout_seconds: 30
    retry:
      max_attempts: 3
      backoff: exponential
    routes:
      - when: "fetch_issue.output.status_code == 404"
        to: $end
      - when: "fetch_issue.output.status_code >= 500"
        to: notify_oncall
      - to: triage_agent

The step's output in context should expose:

  • status_code: int
  • headers: dict[str, str]
  • body: str (raw)
  • json_body: Any | None (parsed if Content-Type is JSON, else None)
  • elapsed_ms: float

Optional fields on the step: body / json_body (request body, mutually exclusive), params (query string), follow_redirects: bool, verify_ssl: bool.

Why now

  • We already have the surrounding machinery: retry:, routes:, output:, Jinja2 templating, context accumulation, event emission. The HTTP step plugs into all of it.
  • Lives next to ScriptExecutor in executor/ and uses the same dispatch path in the engine — no engine core changes.

Open questions

  • Should output: schema validation apply to json_body? (Probably yes when present.)
  • Default timeout? Suggest 60s to match common HTTP client defaults.
  • Do we ship with httpx (already async-native) or add another dependency? httpx is the obvious choice.
  • Auth helpers — start with header-based and let users template in tokens, or add typed auth: bearer | basic | none upfront?
  • Body templating: support both body: "raw {{ template }}" and json_body: { key: "{{ value }}" }, with the latter auto-serialized.

Acceptance criteria

  • type: http accepted by the YAML schema with the fields above
  • Validator rejects conflicting fields (e.g. body + json_body, missing url)
  • HTTP executor returns the documented output shape
  • Integrates with existing retry: policy (transient 5xx and timeouts retry)
  • Routes can match on status_code, headers, and json_body.*
  • Example added under examples/
  • Tests for: success path, 4xx/5xx routing, retry on transient failure, timeout enforcement, template rendering of url/headers/body

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in executor/ beside ScriptExecutor and trace the existing dispatch path, then inspect the YAML schema and validator handling for step types. Add the documented HTTP fields, output shape, retry and routing behavior, an example under examples/, and tests covering the listed acceptance criteria; resolve the open questions before implementation.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
api, backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
50/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.