by concierge-hq
Universal Agent Interactive Protocol (UAIP) is an open standard for ordered and verifiable interactions between autonomous services and AI agents.
# Add to your Claude Code skills
git clone https://github.com/concierge-hq/uaipUAIP defines how autonomous agents interact with applications through explicit stages, workflows, and tasks. It guarantees invocation order and reliable execution, replacing ad-hoc prompting with verifiable contracts. UAIP is 78% more token efficient than existing protocols, eliminating context overflow and semantic loss.
# Install UAIP SDK
pip install uaip
# Initialize a new workflow project
uaip init my-store
# Run the workflow server
cd my-store
python main.py
This starts a UAIP server at specified port that agents can interact with via /initialize and /execute.
You control agent autonomy by specifying legal tasks at each stage and valid transitions between stages. For example: agents cannot checkout before adding items to cart. UAIP enforces these rules, validates prerequisites before task execution, and ensures agents follow your defined path through the application.
Tasks are the smallest granularity of callable business logic. Several tasks can be defined within 1 stage. Ensuring these tasks are avialable or callable at the stage.
@task(description="Add product to shopping cart")
def add_to_cart(self, state: State, product_id: str, quantity: int) -> dict:
"""Adds item to cart and updates state"""
cart_items = state.get("cart.items", [])
cart_items.append({"product_id": product_id, "quantity": quantity})
state.set("cart.items", cart_items)
return {"success": True, "cart_size": len(cart_items)}
A stage is a logical sub-step towards a goal, Stage can have several tasks grouped together, that an agent can call at a given point.
@stage(name="product")
class ProductStage:
@task(description="Add product to shopping cart")
def add_to_cart(self, state: State, product_id: str, quantity: int) -> dict:
"""Adds item to cart"""
@task(description="Save product to wishlist")
def add_to_wishlist(self, state: State, product_id: str) -> dict:
"""Saves item for later"""
No comments yet. Be the first to share your thoughts!
A state is a global context that is maintained by the protocol, parts of which can get propagated to other stages as the agent transitions and navigates through stages.
# State persists across stages and tasks
state.set("cart.items", [{"product_id": "123", "quantity": 2}])
state.set("user.email", "user@example.com")
state.set("cart.total", 99.99)
# Retrieve state values
items = state.get("cart.items", [])
user_email = state.get("user.email")
A workflow is a logic grouping of several stages, you can define graphs of stages which represent legal moves to other stages within workflow.
@workflow(name="shopping")
class ShoppingWorkflow:
discovery = DiscoveryStage # Search and filter products
product = ProductStage # View product details
selection = SelectionStage # Add to cart/wishlist
cart = CartStage # Manage cart items
checkout = CheckoutStage # Complete purchase
transitions = {
discovery: [product, selection],
product: [selection, discovery],
selection: [cart, discovery, product],
cart: [checkout, selection, discovery],
checkout: []
}
@workflow(name="amazon_shopping")
class AmazonShoppingWorkflow:
browse = BrowseStage # Search and filter products
select = SelectStage # Add items to cart
checkout = CheckoutStage # Complete transaction
transitions = {
browse: [select],
select: [browse, checkout],
checkout: []
}
@stage(name="browse")
class BrowseStage:
@task(description="Search for products by keyword")
def search_products(self, state: State, query: str) -> dict:
"""Returns matching products"""
@task(description="Filter products by price range")
def filter_by_price(self, state: State, min_price: float, max_price: float) -> dict:
"""Filters current results by price"""
@task(description="Sort products by rating or price")
def sort_products(self, state: State, sort_by: str) -> dict:
"""Sorts: 'rating', 'price_low', 'price_high'"""
@stage(name="select")
class SelectStage:
@task(description="Add product to shopping cart")
def add_to_cart(self, state: State, product_id: str, quantity: int) -> dict:
"""Adds item to cart"""
@task(description="Save product to wishlist")
def add_to_wishlist(self, state: State, product_id: str) -> dict:
"""Saves item for later"""
@task(description="Star product for quick access")
def star_product(self, state: State, product_id: str) -> dict:
"""Stars item as favorite"""
@task(description="View product details")
def view_details(self, state: State, product_id: str) -> dict:
"""Shows full product information"""
@stage(name="checkout", prerequisites=["cart.items", "user.payment_method"])
class CheckoutStage:
@task(description="Apply discount code")
def apply_discount(self, state: State, code: str) -> dict:
"""Validates and applies discount"""
@task(description="Complete purchase")
def complete_purchase(self, state: State) -> dict:
"""Processes payment and creates order"""
We are building the agentic web. Come join us.
Interested in contributing or building with UAIP? Reach out.
Interested in building apps that render in ChatGPT? Check out Concierge AI.
Contributions are welcome. Please open an issue or submit a pull request.