OpenRouter

Note

You do not have to create an account to OpenRouter to complete this exercise but you may find useful its capability to call free LLMs for you.

You are free to choose other agentic frameworks in this assignment if you prefer - for those that haven’t used one yet, Pydantic AI is a good choice.

OpenRouter provides a unified API that gives you access to hundreds of AI models through a single endpoint, while automatically handling fallbacks and selecting the most cost-effective options. You are hired to help them enhance their ability to route input requests to the most appropriate model provider.

Ideally, you should be building a ReAct agent that will be responsible for the routing decisions. ReAct agents are a type of agent that can reason and act in a step-by-step manner. They can use tools, such as APIs, to perform actions and retrieve information. The ReAct agent is responsible for selecting the most appropriate model provider based on the input request.

Note

The complexity of such agents is such that in this assignment you will only build the feedforward path without any interaction with the environment (the OpenRouter API). The later is reserved for extra credit and you can contact the instructor for help if you want to try it after the course ends.

PDDL

The OpenRouter domain is characterized by:

• Multiple LLMs
• Multiple LLM providers.
• Each LLM has capabilities (e.g., coding, multilingual, safe for kids, long context).
• Each request has functional requirements (e.g., supports code, must be open-source, etc.)
• Each account has a upper limit on the number of dollars it can spend for prompt tokens and completion tokens.
• Each LLM has a limit on the number of tokens it can process as part of its context.
• Each provider has a cost associated with each LLM expressed in $/m (dollars/million) tokens.

This is not an exhaustive list and therefore you need to embark into an ontology engineering exercise to identify the relevant entities and relationships that will be used to build the PDDL domain and problem files. You can use a simple RAG Agent to help you with this task. You need to produce a structured output where the dictionary keys are the required PDDL specification keywords as shown below. For example the key types will contain all PDDL domain types.

PDDL Domain

Use a free LLM that will search over the OpenRouter documentation pages and extract all relevant types.

Write a PDDL domain file that includes the following:

• A set of types that represent the entities in the OpenRouter domain.
• A set of predicates that represent the relationships between the entities.
• A set of actions that represent the operations that can be performed in the OpenRouter domain. Each action should have preconditions and effects that are relevant to the OpenRouter domain.

PDDL Problem

Write a PDDL problem file that includes the following: * A set of objects that represent the specific instances of the types defined in the domain file. * A set of init predicates that represent the initial state of the OpenRouter domain. This should include the available LLMs, providers, and their capabilities. * A set of goal predicates that represent the desired state of the OpenRouter domain. This should include the successful routing of requests to the appropriate LLMs based on their capabilities and costs.

Solve the PDDL problem using an appropriate PDDL solver provided by the Unified Planning library and use its ability to read and write PDDL files.

Note

You are free to use relevant VSCode plugins to help you with the PDDL domain and problem statement as well as solver calls, however, the agent must be in its entirety implemented in Python.

ReAct Agent Implementation

The previous step showcased a feedforward apprach where LLMs where used to help you craft the PDDL domain and problem files. Here we are going to incorporate it into a ReAct agent that will be able to reason and act in a step-by-step manner, often reacting depending on the feedback we receive from the environment.

You must use the Model Context Protocol (MCP) servers to structure the tool calling component of the agent. Tools are external to the agent APIs that can help it achieve its goal. For example, the calls to the Unified Planning library may be considered a tool that the agent can call when it needs to.

Your agent should be able to interact with an environment that simulates the OpenRouter API and therefore provides the necessary information for the agent to make decisions such as deviating from its default routing policy. Alternatively, you may use the OpenRouter API directly if you prefer but limit yourselves to free models and include additional information that will necessitate routing policy change such as dynamic pricing.