inspect-ai 0.3.82__py3-none-any.whl → 0.3.84__py3-none-any.whl

inspect_ai/_view/www/src/workspace/navbar/ScoreGrid.tsx

@@ -0,0 +1,117 @@
+import clsx from "clsx";
+import { FC, ReactNode } from "react";
+import { formatPrettyDecimal } from "../../utils/format";
+import { ResultsScorer } from "./ResultsPanel";
+
+import styles from "./ScoreGrid.module.css";
+
+interface ScoreGridProps {
+  scoreGroups: ResultsScorer[][];
+  showReducer?: boolean;
+  className?: string | string[];
+  striped?: boolean;
+}
+
+export const ScoreGrid: FC<ScoreGridProps> = ({
+  scoreGroups,
+  showReducer,
+  className,
+  striped,
+}) => {
+  const columnCount = scoreGroups.reduce((prev, group) => {
+    return Math.max(prev, group[0].metrics.length);
+  }, 0);
+
+  const subTables: ReactNode[] = [];
+
+  let index = 0;
+  for (const scoreGroup of scoreGroups) {
+    const metrics = scoreGroup[0].metrics;
+
+    // Add header row
+
+    const cells: ReactNode[] = [];
+    for (let i = 0; i < columnCount; i++) {
+      if (metrics.length > i) {
+        cells.push(
+          <th
+            className={clsx(
+              "text-style-label",
+              "text-style-secondary",
+              "text-size-small",
+              styles.label,
+            )}
+          >
+            {metrics[i].name}
+          </th>,
+        );
+      } else {
+        cells.push(<td></td>);
+      }
+    }
+
+    const headerRow = (
+      <tr className={clsx(styles.headerRow)}>
+        <td></td>
+        {cells}
+      </tr>
+    );
+    const rows: ReactNode[] = [];
+    scoreGroup.forEach((g) => {
+      const cells: ReactNode[] = [];
+      for (let i = 0; i < columnCount; i++) {
+        if (metrics.length > i) {
+          cells.push(
+            <td className={clsx(styles.value, "text-size-small")}>
+              {formatPrettyDecimal(g.metrics[i].value)}
+            </td>,
+          );
+        } else {
+          cells.push(<td className={clsx(styles.value)}></td>);
+        }
+      }
+
+      rows.push(
+        <tr>
+          <th className={clsx(styles.scorer, "text-size-small")}>
+            {g.scorer} {showReducer && g.reducer ? `(${g.reducer})` : undefined}
+          </th>
+          {cells}
+        </tr>,
+      );
+    });
+
+    subTables.push(
+      <>
+        {index > 0 ? (
+          <tr>
+            <td
+              colSpan={columnCount + 1}
+              className={clsx(styles.groupSeparator)}
+            ></td>
+          </tr>
+        ) : undefined}
+        {headerRow}
+        <tbody className={clsx("table-group-divider", styles.tableBody)}>
+          {rows}
+        </tbody>
+      </>,
+    );
+
+    index++;
+  }
+
+  return (
+    <table
+      className={clsx(
+        className,
+        "table",
+        striped ? "table-striped" : undefined,
+        styles.table,
+        "table-bordered",
+      )}
+    >
+      {subTables}
+    </table>
+  );
+};

inspect_ai/_view/www/src/workspace/navbar/SecondaryBar.tsx

@@ -124,7 +124,7 @@ export const SecondaryBar: FC<SecondaryBarProps> = ({
       id={"secondary-nav-bar"}
       className={clsx(styles.container, "text-size-small")}
       collapse={true}
-      lines={4}
+      lines={5}
     >
       <div
         className={styles.valueGrid}

inspect_ai/_view/www/src/workspace/sidebar/Sidebar.module.css

@@ -54,8 +54,9 @@
 
 .backdrop {
   position: fixed;
-  inset: 0; /* top: 0; left: 0; right: 0; bottom: 0; */
-  background-color: rgba(0, 0, 0, 0.5);
+  inset: 0;
+  background-color: var(--inspect-glass-color);
+  opacity: var(--inspect-glass-opacity);
   z-index: 9998;
 }
 

inspect_ai/_view/www/src/workspace/tabs/SamplesTab.tsx

@@ -38,6 +38,23 @@ export const SamplesTab: FC<SamplesTabProps> = ({ running }) => {
 
   const sampleSummaries = useFilteredSamples();
   const selectedLogSummary = useStore((state) => state.log.selectedLogSummary);
+
+  // Compute the limit to apply to the sample count (this is so)
+  // we can provide a total expected sample count for this evaluation
+  const evalSampleCount = useMemo(() => {
+    const limit = selectedLogSummary?.eval.config.limit;
+    const limitCount =
+      limit === null || limit === undefined
+        ? undefined
+        : typeof limit === "number"
+          ? limit
+          : (limit[1] as number) - (limit[0] as number);
+    return (
+      (limitCount || selectedLogSummary?.eval.dataset.samples || 0) *
+      (selectedLogSummary?.eval.config.epochs || 0)
+    );
+  }, [selectedLogSummary?.eval.config.limit]);
+
   const totalSampleCount = useTotalSampleCount();
 
   const samplesDescriptor = useSampleDescriptor();
@@ -176,6 +193,7 @@ export const SamplesTab: FC<SamplesTabProps> = ({ running }) => {
           <SampleList
             listHandle={sampleListHandle}
             items={items}
+            totalItemCount={evalSampleCount}
             running={running}
             nextSample={nextSample}
             prevSample={previousSample}

inspect_ai/_view/www/yarn.lock

@@ -10,6 +10,15 @@
     "@jridgewell/gen-mapping" "^0.3.5"
     "@jridgewell/trace-mapping" "^0.3.24"
 
+"@apidevtools/json-schema-ref-parser@^11.5.5":
+  version "11.9.3"
+  resolved "https://registry.yarnpkg.com/@apidevtools/json-schema-ref-parser/-/json-schema-ref-parser-11.9.3.tgz#0e0c9061fc41cf03737d499a4e6a8299fdd2bfa7"
+  integrity sha512-60vepv88RwcJtSHrD6MjIL6Ta3SOYbgfnkHb+ppAVK+o9mXprRtulx7VlRl3lN3bbvysAfCS7WMVfhUYemB0IQ==
+  dependencies:
+    "@jsdevtools/ono" "^7.1.3"
+    "@types/json-schema" "^7.0.15"
+    js-yaml "^4.1.0"
+
 "@babel/code-frame@^7.26.2":
   version "7.26.2"
   resolved "https://registry.yarnpkg.com/@babel/code-frame/-/code-frame-7.26.2.tgz#4b5fab97d33338eff916235055f0ebc21e573a85"
@@ -477,6 +486,11 @@
     "@jridgewell/resolve-uri" "^3.1.0"
     "@jridgewell/sourcemap-codec" "^1.4.14"
 
+"@jsdevtools/ono@^7.1.3":
+  version "7.1.3"
+  resolved "https://registry.yarnpkg.com/@jsdevtools/ono/-/ono-7.1.3.tgz#9df03bbd7c696a5c58885c34aa06da41c8543796"
+  integrity sha512-4JQNk+3mVzK3xh2rqd6RB4J46qUR19azEHBneZyTZM+c456qOrbbM/5xcR8huNCCcbVt7+UmizG6GuUvPvKUYg==
+
 "@lezer/common@^1.0.0", "@lezer/common@^1.1.0":
   version "1.2.3"
   resolved "https://registry.yarnpkg.com/@lezer/common/-/common-1.2.3.tgz#138fcddab157d83da557554851017c6c1e5667fd"
@@ -701,6 +715,11 @@
   resolved "https://registry.yarnpkg.com/@types/linkify-it/-/linkify-it-5.0.0.tgz#21413001973106cda1c3a9b91eedd4ccd5469d76"
   integrity sha512-sVDA58zAw4eWAffKOaQH5/5j3XeayukzDk+ewSsnv3p4yJEZHCCzMDiZM8e0OUrRvmpGZ85jf4yDHkHsgBNr9Q==
 
+"@types/lodash@^4.17.7":
+  version "4.17.16"
+  resolved "https://registry.yarnpkg.com/@types/lodash/-/lodash-4.17.16.tgz#94ae78fab4a38d73086e962d0b65c30d816bfb0a"
+  integrity sha512-HX7Em5NYQAXKW+1T+FiuG27NGwzJfCX3s1GjOa7ujxZa52kjJLOr4FUxT+giF6Tgxv1e+/czV/iTtBw27WTU9g==
+
 "@types/markdown-it@^14.1.2":
   version "14.1.2"
   resolved "https://registry.yarnpkg.com/@types/markdown-it/-/markdown-it-14.1.2.tgz#57f2532a0800067d9b934f3521429a2e8bfb4c61"
@@ -984,6 +1003,11 @@ color-name@~1.1.4:
   resolved "https://registry.yarnpkg.com/color-name/-/color-name-1.1.4.tgz#c2a09a87acbde69543de6f63fa3995c826c536a2"
   integrity sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==
 
+commander@^8.3.0:
+  version "8.3.0"
+  resolved "https://registry.yarnpkg.com/commander/-/commander-8.3.0.tgz#4837ea1b2da67b9c616a67afbb0fafee567bca66"
+  integrity sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==
+
 concat-map@0.0.1:
   version "0.0.1"
   resolved "https://registry.yarnpkg.com/concat-map/-/concat-map-0.0.1.tgz#d8a96bd77fd68df7793a73036a3ba0d5405d477b"
@@ -1231,6 +1255,11 @@ fastq@^1.6.0:
   dependencies:
     reusify "^1.0.4"
 
+fdir@^6.4.3:
+  version "6.4.3"
+  resolved "https://registry.yarnpkg.com/fdir/-/fdir-6.4.3.tgz#011cdacf837eca9b811c89dbb902df714273db72"
+  integrity sha512-PMXmW2y1hDDfTSRc9gaXIuCCRpuoz3Kaz8cUelp3smouvfT632ozg2vrT6lJsHKKOF59YLbOGfAWGUcKEfRMQw==
+
 fflate@^0.8.2:
   version "0.8.2"
   resolved "https://registry.yarnpkg.com/fflate/-/fflate-0.8.2.tgz#fc8631f5347812ad6028bbe4a2308b2792aa1dea"
@@ -1404,6 +1433,21 @@ json-buffer@3.0.1:
   resolved "https://registry.yarnpkg.com/json-buffer/-/json-buffer-3.0.1.tgz#9338802a30d3b6605fbe0613e094008ca8c05a13"
   integrity sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ==
 
+json-schema-to-typescript@^15.0.4:
+  version "15.0.4"
+  resolved "https://registry.yarnpkg.com/json-schema-to-typescript/-/json-schema-to-typescript-15.0.4.tgz#a530c7f17312503b262ae12233749732171840f3"
+  integrity sha512-Su9oK8DR4xCmDsLlyvadkXzX6+GGXJpbhwoLtOGArAG61dvbW4YQmSEno2y66ahpIdmLMg6YUf/QHLgiwvkrHQ==
+  dependencies:
+    "@apidevtools/json-schema-ref-parser" "^11.5.5"
+    "@types/json-schema" "^7.0.15"
+    "@types/lodash" "^4.17.7"
+    is-glob "^4.0.3"
+    js-yaml "^4.1.0"
+    lodash "^4.17.21"
+    minimist "^1.2.8"
+    prettier "^3.2.5"
+    tinyglobby "^0.2.9"
+
 json-schema-traverse@^0.4.1:
   version "0.4.1"
   resolved "https://registry.yarnpkg.com/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz#69f6a87d9513ab8bb8fe63bdb0979c448e684660"
@@ -1433,6 +1477,20 @@ jsondiffpatch@^0.6.0:
     chalk "^5.3.0"
     diff-match-patch "^1.0.5"
 
+katex@^0.16.21:
+  version "0.16.21"
+  resolved "https://registry.yarnpkg.com/katex/-/katex-0.16.21.tgz#8f63c659e931b210139691f2cc7bb35166b792a3"
+  integrity sha512-XvqR7FgOHtWupfMiigNzmh+MgUVmDGU2kXZm899ZkPfcuoPuFxyHmXsgATDpFZDAXCI8tvinaVcDo8PIIJSo4A==
+  dependencies:
+    commander "^8.3.0"
+
+katex@^0.6.0:
+  version "0.6.0"
+  resolved "https://registry.yarnpkg.com/katex/-/katex-0.6.0.tgz#12418e09121c05c92041b6b3b9fb6bab213cb6f3"
+  integrity sha512-rS4mY3SvHYg5LtQV6RBcK0if7ur6plyEukAOV+jGGPqFImuzu8fHL6M752iBmRGoUyF0bhZbAPoezehn7xYksA==
+  dependencies:
+    match-at "^0.1.0"
+
 keyv@^4.5.4:
   version "4.5.4"
   resolved "https://registry.yarnpkg.com/keyv/-/keyv-4.5.4.tgz#a879a99e29452f942439f2a405e3af8b31d4de93"
@@ -1467,6 +1525,11 @@ lodash.merge@^4.6.2:
   resolved "https://registry.yarnpkg.com/lodash.merge/-/lodash.merge-4.6.2.tgz#558aa53b43b661e1925a0afdfa36a9a1085fe57a"
   integrity sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==
 
+lodash@^4.17.21:
+  version "4.17.21"
+  resolved "https://registry.yarnpkg.com/lodash/-/lodash-4.17.21.tgz#679591c564c3bffaae8454cf0b3df370c3d6911c"
+  integrity sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==
+
 lru-cache@^5.1.1:
   version "5.1.1"
   resolved "https://registry.yarnpkg.com/lru-cache/-/lru-cache-5.1.1.tgz#1da27e6710271947695daf6848e847f01d84b920"
@@ -1481,6 +1544,13 @@ make-dir@~3.1.0:
   dependencies:
     semver "^6.0.0"
 
+markdown-it-katex@^2.0.3:
+  version "2.0.3"
+  resolved "https://registry.yarnpkg.com/markdown-it-katex/-/markdown-it-katex-2.0.3.tgz#d7b86a1aea0b9d6496fab4e7919a18fdef589c39"
+  integrity sha512-nUkkMtRWeg7OpdflamflE/Ho/pWl64Lk9wNBKOmaj33XkQdumhXAIYhI0WO03GeiycPCsxbmX536V5NEXpC3Ng==
+  dependencies:
+    katex "^0.6.0"
+
 markdown-it@^14.1.0:
   version "14.1.0"
   resolved "https://registry.yarnpkg.com/markdown-it/-/markdown-it-14.1.0.tgz#3c3c5992883c633db4714ccb4d7b5935d98b7d45"
@@ -1493,6 +1563,11 @@ markdown-it@^14.1.0:
     punycode.js "^2.3.1"
     uc.micro "^2.1.0"
 
+match-at@^0.1.0:
+  version "0.1.1"
+  resolved "https://registry.yarnpkg.com/match-at/-/match-at-0.1.1.tgz#25d040d291777704d5e6556bbb79230ec2de0540"
+  integrity sha512-h4Yd392z9mST+dzc+yjuybOGFNOZjmXIPKWjxBd1Bb23r4SmDOsk2NYCU2BMUBGbSpZqwVsZYNq26QS3xfaT3Q==
+
 mdurl@^2.0.0:
   version "2.0.0"
   resolved "https://registry.yarnpkg.com/mdurl/-/mdurl-2.0.0.tgz#80676ec0433025dd3e17ee983d0fe8de5a2237e0"
@@ -1537,6 +1612,11 @@ minimatch@~3.0.4:
   dependencies:
     brace-expansion "^1.1.7"
 
+minimist@^1.2.8:
+  version "1.2.8"
+  resolved "https://registry.yarnpkg.com/minimist/-/minimist-1.2.8.tgz#c1a464e7693302e082a075cee0c057741ac4772c"
+  integrity sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==
+
 ms@^2.1.3:
   version "2.1.3"
   resolved "https://registry.yarnpkg.com/ms/-/ms-2.1.3.tgz#574c8138ce1d2b5861f0b44579dbadd60c6615b2"
@@ -1615,6 +1695,11 @@ picomatch@^2.3.1:
   resolved "https://registry.yarnpkg.com/picomatch/-/picomatch-2.3.1.tgz#3ba3833733646d9d3e4995946c1365a67fb07a42"
   integrity sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==
 
+picomatch@^4.0.2:
+  version "4.0.2"
+  resolved "https://registry.yarnpkg.com/picomatch/-/picomatch-4.0.2.tgz#77c742931e8f3b8820946c76cd0c1f13730d1dab"
+  integrity sha512-M7BAV6Rlcy5u+m6oPhAPFgJTzAioX/6B0DxyvDlo9l8+T3nLKbrczg2WLUyzd45L8RqfUMyGPzekbMvX2Ldkwg==
+
 postcss-url@^10.1.3:
   version "10.1.3"
   resolved "https://registry.yarnpkg.com/postcss-url/-/postcss-url-10.1.3.tgz#54120cc910309e2475ec05c2cfa8f8a2deafdf1e"
@@ -1639,7 +1724,7 @@ prelude-ls@^1.2.1:
   resolved "https://registry.yarnpkg.com/prelude-ls/-/prelude-ls-1.2.1.tgz#debc6489d7a6e6b0e7611888cec880337d316396"
   integrity sha512-vkcDPrRZo1QZLbn5RLGPpg/WmIQ65qoWWhcGKf/b5eplkkarX0m9z8ppCat4mlOqUsWpyNuYgO3VRyrYHSzX5g==
 
-prettier@^3.3.3:
+prettier@^3.2.5, prettier@^3.3.3:
   version "3.5.3"
   resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.5.3.tgz#4fc2ce0d657e7a02e602549f053b239cb7dfe1b5"
   integrity sha512-QQtaxnoDJeAkDvDKWCLiwIXkTgRhwYDEQCghU9Z6q03iyek/rxRh/2lC3HB7P8sWT2xC/y5JDctPLBIGzHKbhw==
@@ -1814,6 +1899,14 @@ tiny-emitter@^2.0.0:
   resolved "https://registry.yarnpkg.com/tiny-emitter/-/tiny-emitter-2.1.0.tgz#1d1a56edfc51c43e863cbb5382a72330e3555423"
   integrity sha512-NB6Dk1A9xgQPMoGqC5CVXn123gWyte215ONT5Pp5a0yt4nlEoO1ZWeCwpncaekPHXO60i47ihFnZPiRPjRMq4Q==
 
+tinyglobby@^0.2.9:
+  version "0.2.12"
+  resolved "https://registry.yarnpkg.com/tinyglobby/-/tinyglobby-0.2.12.tgz#ac941a42e0c5773bd0b5d08f32de82e74a1a61b5"
+  integrity sha512-qkf4trmKSIiMTs/E63cxH+ojC2unam7rJ0WrauAzpT3ECNTxGRMlaXxVbfxMUC/w0LaYk6jQ4y/nGR9uBO3tww==
+  dependencies:
+    fdir "^6.4.3"
+    picomatch "^4.0.2"
+
 to-regex-range@^5.0.1:
   version "5.0.1"
   resolved "https://registry.yarnpkg.com/to-regex-range/-/to-regex-range-5.0.1.tgz#1648c44aae7c8d988a326018ed72f5b4dd0392e4"

inspect_ai/agent/__init__.py

@@ -0,0 +1,36 @@
+from ._agent import Agent, AgentState, agent, agent_with
+from ._as_solver import as_solver
+from ._as_tool import as_tool
+from ._bridge.bridge import bridge
+from ._filter import MessageFilter, last_message, remove_tools
+from ._handoff import handoff
+from ._human.agent import human_cli
+from ._react import react
+from ._run import run
+from ._types import (
+    AgentAttempts,
+    AgentContinue,
+    AgentPrompt,
+    AgentSubmit,
+)
+
+__all__ = [
+    "react",
+    "bridge",
+    "human_cli",
+    "run",
+    "handoff",
+    "as_tool",
+    "as_solver",
+    "last_message",
+    "remove_tools",
+    "MessageFilter",
+    "Agent",
+    "AgentState",
+    "agent",
+    "agent_with",
+    "AgentPrompt",
+    "AgentAttempts",
+    "AgentContinue",
+    "AgentSubmit",
+]

inspect_ai/agent/_agent.py

@@ -0,0 +1,268 @@
+from copy import copy, deepcopy
+from functools import wraps
+from typing import (
+    Any,
+    Callable,
+    ParamSpec,
+    Protocol,
+    TypeGuard,
+    cast,
+    overload,
+    runtime_checkable,
+)
+
+from inspect_ai._util.registry import (
+    RegistryInfo,
+    is_registry_object,
+    registry_add,
+    registry_info,
+    registry_name,
+    registry_tag,
+    set_registry_info,
+)
+from inspect_ai.model._chat_message import (
+    ChatMessage,
+    ChatMessageAssistant,
+)
+from inspect_ai.model._model_output import ChatCompletionChoice, ModelOutput
+
+
+class AgentState:
+    """Agent state."""
+
+    def __init__(self, *, messages: list[ChatMessage]) -> None:
+        self._messages = messages
+        self._output: ModelOutput | None = None
+
+    @property
+    def messages(self) -> list[ChatMessage]:
+        """Conversation history."""
+        return self._messages
+
+    @messages.setter
+    def messages(self, messages: list[ChatMessage]) -> None:
+        """Set the conversation history."""
+        self._messages = messages
+
+    @property
+    def output(self) -> ModelOutput:
+        """Model output."""
+        # if there is no output yet then synthesize it from the last assistant message
+        if self._output is None:
+            # look for the last assistant message
+            for message in reversed(self.messages):
+                if isinstance(message, ChatMessageAssistant):
+                    self._output = ModelOutput(
+                        model=message.model or "",
+                        choices=[
+                            ChatCompletionChoice(
+                                message=message.model_copy(),
+                                stop_reason="stop",
+                            )
+                        ],
+                    )
+
+            # no assistant message, so generate an empty model output
+            if self._output is None:
+                self._output = ModelOutput()
+
+        return self._output
+
+    @output.setter
+    def output(self, output: ModelOutput) -> None:
+        """Set the model output."""
+        self._output = output
+
+    def __copy__(self) -> "AgentState":
+        state = AgentState(messages=copy(self.messages))
+        state.output = self.output.model_copy()
+        return state
+
+    def __deepcopy__(self, memo: dict[int, Any]) -> "AgentState":
+        state = AgentState(messages=deepcopy(self.messages, memo))
+        state.output = self.output.model_copy(deep=True)
+        return state
+
+
+@runtime_checkable
+class Agent(Protocol):
+    async def __call__(
+        self,
+        state: AgentState,
+        *args: Any,
+        **kwargs: Any,
+    ) -> AgentState:
+        """Agents perform tasks and participate in conversations.
+
+        Agents are similar to tools however they are participants
+        in conversation history and can optionally append messages
+        and model output to the current conversation state.
+
+        You can give the model a tool that enables handoff to
+        your agent using the `handoff()` function.
+
+        You can create a simple tool (that receives a string as
+        input) from an agent using `as_tool()`.
+
+        Args:
+            state: Agent state (conversation history and last model output)
+            *args: Arguments for the agent.
+            **kwargs: Keyword arguments for the agent.
+
+        Returns:
+            AgentState: Updated agent state.
+        """
+        ...
+
+
+P = ParamSpec("P")
+
+
+@overload
+def agent(func: Callable[P, Agent]) -> Callable[P, Agent]: ...
+
+
+@overload
+def agent() -> Callable[[Callable[P, Agent]], Callable[P, Agent]]: ...
+
+
+@overload
+def agent(
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> Callable[[Callable[P, Agent]], Callable[P, Agent]]: ...
+
+
+def agent(
+    func: Callable[P, Agent] | None = None,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> Callable[P, Agent] | Callable[[Callable[P, Agent]], Callable[P, Agent]]:
+    r"""Decorator for registering agents.
+
+    Args:
+        func: Agent function
+        name: Optional name for agent. If the decorator has no name
+            argument then the name of the agent creation function
+            will be used as the name of the agent.
+        description: Description for the agent when used as
+            an ordinary tool or handoff tool.
+
+    Returns:
+        Agent with registry attributes.
+    """
+
+    def create_agent_wrapper(agent_type: Callable[P, Agent]) -> Callable[P, Agent]:
+        # determine the name (explicit or implicit from object)
+        agent_name = registry_name(
+            agent_type, name if name else getattr(agent_type, "__name__")
+        )
+
+        # wrap instantiations of agent so they carry registry info and metrics
+        @wraps(agent_type)
+        def agent_wrapper(*args: P.args, **kwargs: P.kwargs) -> Agent:
+            # create agent
+            agent = agent_type(*args, **kwargs)
+
+            # this might already have registry info, if so capture that
+            # and use it as default
+            if is_registry_object(agent):
+                info = registry_info(agent)
+                registry_name = info.name
+                registry_description = info.metadata.get(AGENT_DESCRIPTION, None)
+            else:
+                registry_name = None
+                registry_description = None
+
+            registry_tag(
+                agent_type,
+                agent,
+                RegistryInfo(
+                    type="agent",
+                    name=registry_name or agent_name,
+                    metadata={AGENT_DESCRIPTION: registry_description or description},
+                ),
+                *args,
+                **kwargs,
+            )
+            return agent
+
+        # register
+        return agent_register(cast(Callable[P, Agent], agent_wrapper), agent_name)
+
+    if func is not None:
+        return create_agent_wrapper(func)
+    else:
+        return create_agent_wrapper
+
+
+def agent_with(
+    agent: Agent,
+    *,
+    name: str | None = None,
+    description: str | None = None,
+) -> Agent:
+    """Agent with modifications to name and/or description
+
+    This function modifies the passed agent in place and
+    returns it. If you want to create multiple variations
+    of a single agent using `agent_with()` you should create
+    the underlying agent multiple times.
+
+    Args:
+       agent: Agent instance to modify.
+       name: Agent name (optional).
+       description: Agent description (optional).
+
+    Returns:
+       The passed agent with the requested modifications.
+    """
+    # resolve name and description
+    if is_registry_object(agent):
+        info = registry_info(agent)
+        name = name or info.name
+        description = description or info.metadata.get(AGENT_DESCRIPTION, None)
+
+    # if the name is null then raise
+    if name is None:
+        raise ValueError("You must provide a name to agent_with")
+
+    # now set registry info
+    set_registry_info(
+        agent,
+        RegistryInfo(
+            type="agent",
+            name=name,
+            metadata={AGENT_DESCRIPTION: description}
+            if description is not None
+            else {},
+        ),
+    )
+
+    return agent
+
+
+def agent_register(agent: Callable[P, Agent], name: str) -> Callable[P, Agent]:
+    r"""Register a function or class as an agent.
+
+    Args:
+        agent: Agent function or a class derived from Agent.
+        name (str): Name of agent (Optional, defaults to object name)
+
+    Returns:
+        Agent with registry attributes.
+    """
+    registry_add(
+        agent,
+        RegistryInfo(type="agent", name=name),
+    )
+    return agent
+
+
+def is_agent(obj: Any) -> TypeGuard[Agent]:
+    return is_registry_object(obj, type="agent")
+
+
+AGENT_DESCRIPTION = "description"