introduce redpanda.runtime

Taskfile.yaml

@@ -68,3 +68,17 @@ tasks:
     desc: "Deploy documentation to GitHub Pages with mkdocs"
     cmds:
       - uv run mkdocs gh-deploy --force --verbose
+
+  protogen:
+    desc: "Generate protobuf"
+    vars:
+      OUT_DIR: src
+    cmds:
+      - >
+        uv run -m grpc_tools.protoc \
+          --python_out={{.OUT_DIR}} \
+          --mypy_out={{.OUT_DIR}} \
+          --grpc_python_out={{.OUT_DIR}} \
+          --mypy_grpc_out={{.OUT_DIR}} \
+          -I proto
+          proto/redpanda/runtime/proto/runtime.proto

examples/weather_agent_repl/agents/weather.py

@@ -0,0 +1,46 @@
+import asyncio
+import logging
+from typing import Any, override
+
+import redpanda.runtime
+from redpanda.agents import Agent, AgentHooks, Tool
+
+
+class MyHooks(AgentHooks):
+    @override
+    async def on_start(self, agent: Agent) -> None:
+        logging.debug("Agent started")
+
+    @override
+    async def on_end(self, agent: Agent, output: Any) -> None:
+        logging.debug("Agent ended")
+
+    @override
+    async def on_tool_start(
+        self,
+        agent: Agent,
+        tool: Tool,
+        args: str,
+    ) -> None:
+        logging.debug(f"Agent calling tool {tool.name} with args: {args}")
+
+    @override
+    async def on_tool_end(
+        self,
+        agent: Agent,
+        tool: Tool,
+        result: str,
+    ) -> None:
+        logging.debug(f"Agent tool {tool.name} resulted in: {result}")
+
+
+my_agent = Agent(
+    name="WeatherAgent",
+    model="openai/gpt-4o",
+    instructions="""
+    You are a helpful AI agent for finding out about the weather.
+    """.strip(),
+    hooks=MyHooks(),
+)
+
+asyncio.run(redpanda.runtime.serve(my_agent))

examples/weather_agent_repl/redpanda_agents.yaml

@@ -0,0 +1,8 @@
+agents:
+  weather:
+    input:
+      stdin: {}
+    tools:
+      - check_weather
+    output:
+      stdout: {}

proto/redpanda/runtime/proto/runtime.proto

@@ -0,0 +1,74 @@
+// Copyright 2025 Redpanda Data, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+syntax = "proto3";
+
+package redpanda.runtime.v1alpha1;
+
+import "google/protobuf/timestamp.proto";
+
+// `NullValue` is a representation of a null value.
+enum NullValue { NULL_VALUE = 0; }
+
+// `StructValue` represents a struct value which can be used to represent a
+// structured data value.
+message StructValue {
+  map<string, Value> fields = 1;
+}
+
+// `ListValue` represents a list value which can be used to represent a list of
+// values.
+message ListValue {
+  repeated Value values = 1;
+}
+
+// `Value` represents a dynamically typed value which can be used to represent
+// a value passed to an agent.
+message Value {
+  oneof kind {
+    NullValue null_value = 1;
+    string string_value = 2;
+    int64 integer_value = 3;
+    double double_value = 4;
+    bool bool_value = 5;
+    google.protobuf.Timestamp timestamp_value = 6;
+    bytes bytes_value = 7;
+    StructValue struct_value = 8;
+    ListValue list_value = 9;
+  }
+}
+
+// Message represents a piece of structured data that flows through the runtime.
+message Message {
+  oneof payload {
+    bytes serialized = 1;
+    Value structured = 2;
+  }
+  StructValue metadata = 3;
+}
+
+// InvokeAgentRequest is the request message for the `InvokeAgent` method.
+message InvokeAgentRequest {
+  Message message = 1;
+}
+
+// InvokeAgentResponse is the response message for the `InvokeAgent` method.
+message InvokeAgentResponse {
+  Message message = 1;
+}
+
+// `Runtime` is the service that provides the ability to invoke an agent.
+service Runtime {
+  rpc InvokeAgent(InvokeAgentRequest) returns (InvokeAgentResponse);
+}

pyproject.toml

@@ -1,5 +1,5 @@
 [project]
-name = "redpanda-agent"
+name = "redpanda-agents"
 version = "0.1.0"
 description = "the best way to vibe code enterprise agents"
 readme = "README.md"
@@ -8,10 +8,13 @@ authors = [
 ]
 requires-python = ">=3.13"
 dependencies = [
+    "aiohttp>=3.11.16",
+    "grpcio>=1.71.0",
+    "grpcio-health-checking>=1.71.0",
     "litellm>=1.63.14",
     "mcp>=1.5.0",
+    "protobuf>=5.29.4",
     "pydantic>=2.10.6",
-    "pyright>=1.1.397",
     "websockets>=15.0.1",
 ]
 license = "Apache-2.0"
@@ -27,17 +30,19 @@ dev = [
     "mkdocs",
     "mkdocs-material",
     "mkdocstrings[python]",
+    "grpcio-tools>=1.71.0",
+    "mypy-protobuf>=3.6.0",
 ]
 [tool.uv.workspace]
-members = ["agents"]
+members = ["redpanda"]
 
 [tool.uv.sources]
-agents = { workspace = true }
-
+redpanda = { workspace = true }
 
 [tool.ruff]
 line-length = 100
 target-version = "py39"
+exclude = ["proto"]
 
 [tool.ruff.lint]
 select = [
@@ -49,7 +54,7 @@ select = [
     "C4", # flake8-comprehensions
     "UP", # pyupgrade
 ]
-isort = { combine-as-imports = true, known-first-party = ["agents"] }
+isort = { combine-as-imports = true, known-first-party = ["redpanda"] }
 
 [tool.ruff.lint.pydocstyle]
 convention = "google"
@@ -59,12 +64,17 @@ requires = ["hatchling"]
 build-backend = "hatchling.build"
 
 [tool.hatch.build.targets.wheel]
-packages = ["src/agents"]
+packages = ["src/redpanda"]
 
 [tool.ruff.lint.per-file-ignores]
 "examples/**/*.py" = ["E501"]
 
 [tool.pyright]
+exclude = [
+  "src/redpanda/runtime/proto/**",
+  "**/__pycache__",
+  "**/.*",
+]
 reportUnusedCallResult = false
 reportExplicitAny = false
 reportAny = false