---
title: "Summarise Jira Epics in LangGraph | EnConvert"
description: "Summarise Jira epics inside a LangGraph agent with EnConvert Distill, which returns schema-defined fields for up to 50 public epic page URLs in one call"
canonical: "https://www.enconvert.com/solutions/summarise-jira-epics-in-langgraph-enconvert"
locale: "en"
---

# How to Summarise Jira Epics with LangGraph

A developer building a LangGraph agent that tracks delivery progress or generates release notes needs structured content from Jira epics before the agent can reason over scope, status, or linked work. Jira epic pages mix the epic description, acceptance criteria, linked story list, sprint assignments, and comment threads in a layout that returns no clean structured text when fetched directly, and on a private instance the Jira REST API requires a service account with project-level permissions before an epic can be read as structured content. EnConvert Distill accepts the Jira epic URL, applies a schema the agent defines, and returns structured fields in one synchronous call. The agent gets schema-defined epic content ready for downstream reasoning with no Jira API credentials, for epics on instances that open without signing in.

## Example

```python
import os

import requests
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.graph import START, MessagesState, StateGraph
from langgraph.prebuilt import ToolNode, tools_condition

# ChatOpenAI reads OPENAI_API_KEY from the environment
JIRA_EPIC_URL = os.environ["JIRA_EPIC_URL"]  # a Jira epic page that opens without signing in

BASE_URL = "https://api.enconvert.com/v2"
headers = {
    "X-API-Key": os.environ["ENCONVERT_API_KEY"],
    "Content-Type": "application/json",
}

# The fields the agent receives. The response keys match these names exactly.
# Each description tells the extractor to leave a field empty rather than guess.
EPIC_SCHEMA = {
    "epic_title": "The epic summary line shown as the issue title",
    "summary": "A three sentence summary of the epic, using only the description text on the page",
    "acceptance_criteria": (
        "Acceptance criteria, only if the description lists them, as a list. "
        "Return an empty list if the page lists none."
    ),
    "linked_stories_count": (
        "The number of child issues or stories shown for this epic, as an integer, counted only "
        "from items listed on the page. Return null if the page does not list them."
    ),
    "status": "The status shown on the page, such as To Do, In Progress, or Done",
    "priority": "The priority shown on the page, such as High or Medium. Return an empty string if none is shown.",
}

def as_text(value) -> str:
    if isinstance(value, list):
        return "; ".join(str(item) for item in value) or "not stated"
    return str(value) if value not in (None, "") else "not stated"

@tool
def summarise_jira_epics(urls: list[str]) -> str:
    """Reads Jira epic pages that open without signing in and returns structured fields for
    each: title, summary, acceptance criteria, linked stories count, status, and priority.
    Accepts up to 50 URLs. Private Jira instances behind a login cannot be read."""
    if len(urls) > 50:
        return "Too many URLs. Distill accepts at most 50 per call."

    # One synchronous call: no job_id, no polling, no download step
    response = requests.post(
        f"{BASE_URL}/distill",
        headers=headers,
        json={"urls": urls, "schema": EPIC_SCHEMA},
        timeout=300,
    )

    # Distill runs on paid plans only, and the free tier returns 402
    if response.status_code == 402:
        return "Distill requires a paid plan."
    response.raise_for_status()

    epics = []
    for result in response.json()["results"]:
        if result["status"] != "completed":
            epics.append(f"Source: {result['url']}\nCould not be read ({result['status']}).")
            continue

        # A low render_quality means a login wall, which private Jira instances sit behind
        render_quality = result.get("render_quality", 1.0)
        if render_quality < 0.5:
            epics.append(
                f"Source: {result['url']}\nLow render quality ({render_quality}), "
                "likely a login page. Skipped."
            )
            continue

        data = result["data"]  # keys match EPIC_SCHEMA exactly

        # No title means the page was not a readable epic, so do not report an empty record
        if not data.get("epic_title"):
            epics.append(f"Source: {result['url']}\nNo epic content was found on the page.")
            continue

        epics.append(
            f"Source: {result['url']}\n"
            f"Epic: {data['epic_title']}\n"
            f"Status: {as_text(data['status'])}\n"
            f"Priority: {as_text(data['priority'])}\n"
            f"Linked stories: {as_text(data['linked_stories_count'])}\n"
            f"Acceptance criteria: {as_text(data['acceptance_criteria'])}\n"
            f"Summary: {data['summary']}"
        )
    return "\n\n---\n\n".join(epics)

tools = [summarise_jira_epics]
llm = ChatOpenAI(model="gpt-4.1").bind_tools(tools)

def agent_node(state: MessagesState):
    return {"messages": [llm.invoke(state["messages"])]}

# The graph: the agent calls the tool when it needs an epic, then writes its answer
builder = StateGraph(MessagesState)
builder.add_node("agent", agent_node)
builder.add_node("tools", ToolNode(tools))
builder.add_edge(START, "agent")
builder.add_conditional_edges("agent", tools_condition)  # routes to "tools" or ends
builder.add_edge("tools", "agent")
graph = builder.compile()

result = graph.invoke(
    {
        "messages": [
            (
                "system",
                "You summarise Jira epics for release planning. Use summarise_jira_epics to read "
                "the epics you need, report only what the tool returns, and cite the epic URL for "
                "every statement. If a field is not stated, say so and do not guess.",
            ),
            (
                "user",
                f"Read {JIRA_EPIC_URL} and summarise "
                "its scope, its status, and how many stories are linked to it.",
            ),
        ]
    }
)
print(result["messages"][-1].content)
```

## Output

Distill returns schema-defined fields inline as structured JSON in the data object, with no polling and no job_id. The render_quality score lets the agent detect a login wall before it reasons over incomplete content, and private Jira instances that need authentication come back with a low render quality and are skipped. Reading a Jira epic through the REST API on a private instance requires a service account with project permissions and separate endpoint calls for issue fields and linked stories, while Distill returns schema-defined fields from the epic URL in one call.

## Get started

[Get free API key — 500 ops per month, no card required. Note: Distill runs on paid plans. Free tier returns 402.](https://www.enconvert.com/auth?mode=signup)

## Related solutions

- [How to Summarise GitHub with Pydantic AI](https://www.enconvert.com/solutions/summarise-github-with-pydantic-ai-enconvert.md)
- [How to Summarise Google Docs with LangGraph](https://www.enconvert.com/solutions/summarise-google-docs-with-langgraph-enconvert.md)
- [How to Summarise GitHub with LlamaIndex](https://www.enconvert.com/solutions/summarise-github-with-llamaindex-enconvert.md)
- [How to Summarise Google Docs with Pydantic AI](https://www.enconvert.com/solutions/summarise-google-docs-with-pydantic-ai-enconvert.md)
- [How to Summarise YouTube Transcripts with LlamaIndex](https://www.enconvert.com/solutions/summarise-youtube-transcripts-with-llamaindex-enconvert.md)
- [How to Summarise GitHub Issues with CrewAI](https://www.enconvert.com/solutions/summarise-github-issues-with-crewai-enconvert.md)
