README.md

metadata

title: Process-Aware LangGraph Agent
emoji: 🤖
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.42.0
app_file: app.py
pinned: false
python_version: 3.12

Process-Aware LangGraph Agent

LangGraph Process Management Agent

A LangGraph agentic project for process management and execution guidance. The agent is a specialized Process Management Assistant whose behavior is defined through markdown files, including imperative process descriptions and normative constraints.

📁 Project Structure

langgraph_agent/
├── agents/              # Agent implementations
│   ├── __init__.py
│   └── process_aware_agent.py  # Process-aware agent logic
├── config/              # Configuration management
│   ├── __init__.py
│   └── settings.py      # Settings and environment variables
├── docs/                # Agent definitions (markdown)
│   ├── agent_definition.md      # Agent behavior and prompts
│   ├── graph_structure.md       # Graph architecture documentation
│   ├── process-description.md   # Imperative process description
│   └── process-constraints.md   # Normative process constraints
├── tools/               # Custom tools (empty for now)
├── utils/               # Utility functions
│   ├── __init__.py
│   └── markdown_loader.py     # Load agent definitions from markdown
├── .env.example         # Example environment variables
├── example.py           # Example usage scripts
├── main.py              # Main entry point for interactive mode
├── pyproject.toml       # Project metadata and dependencies
└── requirements.txt     # Python dependencies

🚀 Getting Started

Prerequisites

• Python 3.10 or higher
• OpenAI API key

Installation

1. Clone or navigate to the project directory:

   cd langgraph_agent
   

2. Create a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Set up environment variables:

   cp .env.example .env
   

   Edit .env and add your OpenAI API key:

   OPENAI_API_KEY=your_actual_api_key_here
   

💻 Usage

Interactive Mode

Run the agent in interactive chat mode:

cd langgraph_agent
python main.py

This starts an interactive session where you can chat with the agent. Type exit or quit to end.

Single Query Mode

Run a single query from the command line:

cd langgraph_agent
python main.py "Describe the business process you are managing."

Example Scripts

Run the example scripts to see different usage patterns:

cd langgraph_agent
python example.py

This demonstrates:

• Simple single-turn queries
• Multi-turn conversations with context
• Custom agent definitions
• Tool usage (text summarization)

📝 Customizing the Agent

Agent Role: Process Management Assistant

The agent is designed as a Process Management Assistant that:

• Provides information about business processes
• Guides users through process execution
• Ensures compliance with normative constraints
• Requests permission for deviations from standard flows
• Always adheres to mandatory process rules

Modify Agent Behavior

Edit docs/agent_definition.md to customize:

• Agent name and role
• System prompt
• Capabilities
• Behavior guidelines
• Example interactions

Define Your Process

1. Process Description (docs/process-description.md)

This file contains the imperative process description - the typical way the process should flow.

Current Process: Purchase-to-Pay / Procurement Exception-Handling Process

The process manages the complete lifecycle of procurement documents with integration to SRM (Supplier Relationship Management) and execution systems. It includes:

• 44 activities covering:

  • SRM status management (Created, Ordered, Complete, Awaiting Approval, Held, etc.)
  • Procurement creation and release (requisitions and purchase orders)
  • Logistics and fulfillment (goods receipts, service entry sheets, invoices)
  • Extensive change and correction activities (quantity, price, currency, payment terms, delivery, storage location)

• Main Flow:

  1. Start → SRM status handling
  2. Create Purchase Requisition Item → Release Purchase Requisition
  3. Create Purchase Order Item → Release Purchase Order
  4. Transfer to execution system
  5. Vendor confirmation and fulfillment (order confirmation, goods receipt, invoice)
  6. Change handling and reprocessing (supports post-order corrections)
  7. Completion and closure

• Decision Points: Extensive use of exclusive and parallel gateways for document state management, approval routing, transfer success/failure, and correction paths

The agent has autonomy to guide execution according to this description, as long as it conforms to the normative constraints.

2. Process Constraints (docs/process-constraints.md)

This file contains normative constraints - strict rules that must NEVER be violated.

Current Constraints: Declare Constraints for Purchase Order Process

Key constraints include:

• Existence Constraints:

  • Create Purchase Order Item must occur exactly once
  • Record Goods Receipt must occur exactly once

• Initialization:

  • Create Purchase Order Item must be the first activity

• Response Constraints:

  • Creating a purchase order triggers eventual goods receipt recording
  • Purchase order creation must be followed by goods receipt

• Precedence Constraints:

  • Goods receipt can only occur after purchase order creation
  • Purchase order must always precede goods receipt

• Negative Constraints (Forbidden Patterns):

  • Cannot create purchase order after goods receipt
  • Cannot have direct succession of goods receipt → purchase order creation
  • Purchase order creation must NOT follow goods receipt recording

Important: The agent will ALWAYS conform to these constraints. When execution needs to deviate from the typical flow in process-description.md, the agent will ask for permission, but only in ways that still satisfy all constraints in process-constraints.md.

How the Agent Uses Process Specifications

1. Process Knowledge: The agent has complete knowledge of both the process description and constraints
2. Execution Guidance: It guides users through the process according to the typical flow
3. Constraint Adherence: It NEVER violates normative constraints
4. Deviation Management: When deviations from the typical flow are needed, it asks permission first
5. Compliance First: All suggestions and actions must conform to the normative constraints

The agent will automatically load these process specifications on startup and integrate them into its decision-making.

Create Multiple Agents

1. Create a new markdown file in docs/ (e.g., docs/specialist_agent.md)
2. Define the agent's behavior using the same structure as agent_definition.md
3. Load it in your code:

from pathlib import Path
from agents.process_aware_agent import run_agent

response = run_agent(
    "Your query here",
    agent_definition_path=Path("docs/specialist_agent.md")
)

🏗️ Architecture

LangGraph Structure

The agent uses a graph with conditional tool execution:

START → Agent Node → [Tool Node] → Agent Node → END
                ↓
               END

The agent can:

1. Respond directly for simple queries
2. Call tools when needed (e.g., summarization)
3. Process tool results and provide final response

Available Tools

summarize_text: Summarizes long text into concise summaries

• Takes text input and optional max_sentences parameter
• Returns a brief summary of the input
• Automatically invoked when user requests summarization

State Management

The graph maintains:

• messages: Conversation history
• agent_name: Active agent identifier
• metadata: Additional context

🔧 Configuration

Configuration is managed through environment variables and config/settings.py:

• OPENAI_API_KEY: Your OpenAI API key (required)
• OPENAI_MODEL: Model to use (default: gpt-4o-mini)
• TEMPERATURE: LLM temperature (default: 0.7)
• MAX_TOKENS: Maximum response tokens (default: 1000)

Optional LangSmith tracing:

• LANGCHAIN_TRACING_V2: Enable tracing (default: false)
• LANGCHAIN_API_KEY: LangSmith API key
• LANGCHAIN_PROJECT: Project name

📚 Key Components

Agent Definition Loader (utils/markdown_loader.py)

Parses markdown files to extract:

• Agent name and role
• System prompts
• Behavior guidelines
• Example interactions

Process-Aware Agent (agents/process_aware_agent.py)

Core agent implementation:

• create_agent_graph(): Creates a LangGraph instance with process specifications
• run_agent(): Convenience function for single queries
• Automatically loads process description and constraints
• Integrates process context into system prompt

Settings (config/settings.py)

Manages configuration using Pydantic settings:

• Environment variable loading
• Type validation
• Default values

🛠️ Development

Adding Tools

The project includes a text summarization tool. To add more tools:

1. Create tool functions in tools/ using the @tool decorator:

   from langchain_core.tools import tool
   
   @tool
   def your_tool(param: str) -> str:
       """Tool description."""
       # Implementation
       return result
   

2. Import and add to the tools list in agents/process_aware_agent.py:

   from tools.your_tool import your_tool
   tools = [summarize_text, your_tool]
   

3. Update docs/agent_definition.md to document the new tool

Extending the Graph

To add more complex workflows:

1. Define additional nodes in your agent file
2. Add conditional edges for routing logic
3. Update docs/graph_structure.md to document changes

📖 Further Reading

• LangGraph Documentation
• LangChain Documentation
• OpenAI API Documentation

📄 License

This project is provided as-is for educational and development purposes.

🤝 Contributing

Feel free to extend and modify this project structure for your needs!