Input/Output Schemas

Decide which state properties are received and returned to the frontend

What is this?#

Not all state properties are relevant for frontend-backend sharing. This guide shows how to ensure only the right portion of state is communicated back and forth.

This guide is based on LangGraph's Input/Output Schema feature

When should I use this?#

Depending on your implementation, some properties are meant to be processed internally, while some others are the way for the UI to communicate user input. In addition, some state properties contain a lot of information. Syncing them back and forth between the agent and UI can be costly, while it might not have any practical benefit.

Implementation#

Examine our old state#

LangGraph is stateful. As you transition between nodes, that state is updated and passed to the next node. For this example, let's assume that the state our agent should be using, can be described like this:

agent.py

python

from copilotkit import CopilotKitState
from typing import Literal

class AgentState(CopilotKitState):
    question: str
    answer: str
    resources: List[str]

Divide state to Input and Output#

Our example case lists several state properties, which with its own purpose:

The question is being asked by the user, expecting the llm to answer
The answer is what the LLM returns
The resources list will be used by the LLM to answer the question, and should not be communicated to the user, or set by them.

agent.py

python

from copilotkit import CopilotKitState
from typing import Literal

# Divide the state to 3 parts

# Input schema for inputs you are willing to accept from the frontend
class InputState(CopilotKitState):
  question: str

# Output schema for output you are willing to pass to the frontend
class OutputState(CopilotKitState):
  answer: str

# The full schema, including the inputs, outputs and internal state ("resources" in our case)
class OverallState(InputState, OutputState):
  resources: List[str]

async def answer_node(state: OverallState, config: RunnableConfig):
  """
  Standard chat node, meant to answer general questions.
  """

  model = ChatOpenAI()

  # add the input question in the system prompt so it's passed to the LLM
  system_message = SystemMessage(
    content=f"You are a helpful assistant. Answer the question: {state.get('question')}"
  )

  response = await model.ainvoke([
    system_message,
    *state["messages"],
  ], config)

  # ...add the rest of the agent implementation

  # extract the answer, which will be assigned to the state soon
  answer = response.content

  return {
     "messages": response,
      # include the answer in the returned state
     "answer": answer
  }


# finally, before compiling the graph, we define the 3 state components
builder = StateGraph(OverallState, input=InputState, output=OutputState)

# add all the different nodes and edges and compile the graph
builder.add_node("answer_node", answer_node)
builder.add_edge(START, "answer_node")
builder.add_edge("answer_node", END)
graph = builder.compile()

Give it a try!#

Now that we know which state properties our agent emits, we can inspect the state and expect the following to happen:

While we are able to provide a question, we will not receive it back from the agent. If we are using it in our UI, we need to remember the UI is the source of truth for it
Answer will change once it's returned back from the agent
The UI has no access to resources.

import { useAgent } from "@copilotkit/react-core/v2"; // [!code highlight]

const { agent } = useAgent({
  agentId: "sample_agent",
});

const answer = agent.state.answer as string;

console.log(answer) // You can expect seeing "answer" change, while the others are not returned from the agent

Input/Output Schemas

Decide which state properties are received and returned to the frontend

What is this?#

Not all state properties are relevant for frontend-backend sharing. This guide shows how to ensure only the right portion of state is communicated back and forth.

This guide is based on LangGraph's Input/Output Schema feature

When should I use this?#

Implementation#

Examine our old state#

agent.py

python

from copilotkit import CopilotKitState
from typing import Literal

class AgentState(CopilotKitState):
    question: str
    answer: str
    resources: List[str]

Divide state to Input and Output#

Our example case lists several state properties, which with its own purpose:

The question is being asked by the user, expecting the llm to answer
The answer is what the LLM returns
The resources list will be used by the LLM to answer the question, and should not be communicated to the user, or set by them.

agent.py

python

from copilotkit import CopilotKitState
from typing import Literal

# Divide the state to 3 parts

# Input schema for inputs you are willing to accept from the frontend
class InputState(CopilotKitState):
  question: str

# Output schema for output you are willing to pass to the frontend
class OutputState(CopilotKitState):
  answer: str

# The full schema, including the inputs, outputs and internal state ("resources" in our case)
class OverallState(InputState, OutputState):
  resources: List[str]

async def answer_node(state: OverallState, config: RunnableConfig):
  """
  Standard chat node, meant to answer general questions.
  """

  model = ChatOpenAI()

  # add the input question in the system prompt so it's passed to the LLM
  system_message = SystemMessage(
    content=f"You are a helpful assistant. Answer the question: {state.get('question')}"
  )

  response = await model.ainvoke([
    system_message,
    *state["messages"],
  ], config)

  # ...add the rest of the agent implementation

  # extract the answer, which will be assigned to the state soon
  answer = response.content

  return {
     "messages": response,
      # include the answer in the returned state
     "answer": answer
  }


# finally, before compiling the graph, we define the 3 state components
builder = StateGraph(OverallState, input=InputState, output=OutputState)

# add all the different nodes and edges and compile the graph
builder.add_node("answer_node", answer_node)
builder.add_edge(START, "answer_node")
builder.add_edge("answer_node", END)
graph = builder.compile()

Give it a try!#

Now that we know which state properties our agent emits, we can inspect the state and expect the following to happen:

While we are able to provide a question, we will not receive it back from the agent. If we are using it in our UI, we need to remember the UI is the source of truth for it
Answer will change once it's returned back from the agent
The UI has no access to resources.

import { useAgent } from "@copilotkit/react-core/v2"; // [!code highlight]

const { agent } = useAgent({
  agentId: "sample_agent",
});

const answer = agent.state.answer as string;

console.log(answer) // You can expect seeing "answer" change, while the others are not returned from the agent