Log Records

As of date, Agent Catalog supports 11 different types of log records (all varied by content). Agent Catalog maintains a collection of logs as a series of events.

Schema of Logs

pydantic model agentc_core.activity.models.log.Log

A Log instance represents a single log record that is bound to a part of the application versioned according to catalog_version.

Attention

Log instances are immutable and should not be instantiated directly. Only Content instances should be created directly, and then passed to a Span instance via the agentc.span.Span.log() method.

Show JSON schema

{
   "title": "Log",
   "description": "A :py:class:`Log` instance represents a single log record that is bound to a part of the application\n**versioned** according to :py:attr:`catalog_version`.\n\n.. attention::\n\n    :py:class:`Log` instances are **immutable** and should not be instantiated directly.\n    Only :py:class:`Content` instances should be created directly, and then passed to a :py:class:`Span` instance\n    via the :py:meth:`agentc.span.Span.log` method.",
   "type": "object",
   "properties": {
      "identifier": {
         "description": "A unique identifier for this record. This field is typically a UUID.",
         "title": "Identifier",
         "type": "string"
      },
      "span": {
         "$ref": "#/$defs/Span",
         "description": "The span (i.e., a list of names and a session ID) that this record is associated with."
      },
      "timestamp": {
         "description": "Timestamp of the generated record. This field must have a timezone attached as well.",
         "examples": [
            "2024-08-26T12:02:59.500Z",
            "2024-08-26T12:02:59.500+00:00"
         ],
         "format": "date-time",
         "title": "Timestamp",
         "type": "string"
      },
      "content": {
         "description": "The content of the record. This should be as close to the producer as possible.",
         "discriminator": {
            "mapping": {
               "assistant": "#/$defs/AssistantContent",
               "begin": "#/$defs/BeginContent",
               "chat-completion": "#/$defs/ChatCompletionContent",
               "edge": "#/$defs/EdgeContent",
               "end": "#/$defs/EndContent",
               "key-value": "#/$defs/KeyValueContent",
               "request-header": "#/$defs/RequestHeaderContent",
               "system": "#/$defs/SystemContent",
               "tool-call": "#/$defs/ToolCallContent",
               "tool-result": "#/$defs/ToolResultContent",
               "user": "#/$defs/UserContent"
            },
            "propertyName": "kind"
         },
         "oneOf": [
            {
               "$ref": "#/$defs/SystemContent"
            },
            {
               "$ref": "#/$defs/ToolCallContent"
            },
            {
               "$ref": "#/$defs/ToolResultContent"
            },
            {
               "$ref": "#/$defs/ChatCompletionContent"
            },
            {
               "$ref": "#/$defs/RequestHeaderContent"
            },
            {
               "$ref": "#/$defs/UserContent"
            },
            {
               "$ref": "#/$defs/AssistantContent"
            },
            {
               "$ref": "#/$defs/BeginContent"
            },
            {
               "$ref": "#/$defs/EndContent"
            },
            {
               "$ref": "#/$defs/EdgeContent"
            },
            {
               "$ref": "#/$defs/KeyValueContent"
            }
         ],
         "title": "Content"
      },
      "annotations": {
         "anyOf": [
            {
               "additionalProperties": true,
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Additional annotations that can be added to the message.",
         "title": "Annotations"
      },
      "catalog_version": {
         "$ref": "#/$defs/VersionDescriptor",
         "description": "A unique identifier that defines a catalog version / snapshot / commit."
      }
   },
   "$defs": {
      "AssistantContent": {
         "description": "Assistant refers to messages that are directly served back to the user.\n\n.. card:: Class Description\n\n    Assistant messages are used to capture the direct output of your application (i.e., the messages served back to\n    the user).\n    These messages are *not* strictly :py:class:`ChatCompletionContent` messages, as your application may utilize\n    multiple LLM calls before returning some message back to the user.\n\n    An assistant message has a single required field, ``value``, which contains the direct output back to the user.\n    If extra data is associated with the assistant message, it can be stored in the optional ``extra`` field.",
         "properties": {
            "extra": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Additional data that is associated with the content. This field is optional.",
               "title": "Extra"
            },
            "kind": {
               "const": "assistant",
               "default": "assistant",
               "title": "Kind",
               "type": "string"
            },
            "value": {
               "description": "The response served back to the user.",
               "title": "Value",
               "type": "string"
            }
         },
         "required": [
            "value"
         ],
         "title": "AssistantContent",
         "type": "object"
      },
      "BeginContent": {
         "description": "Begin refers to marker messages that are used to indicate the start of a span (e.g., a task, agent, state,\netc...).\n\n.. card:: Card Description\n\n    Begin messages denote the start of a span *and* (perhaps just as important) record the entrance state of a span.\n    In certain applications, log analysts are able to use this information to model how the state of an application\n    mutates over time.\n\n    Begin messages have two optional fields: i) the ``state`` field (used to record the starting state of a span)\n    and ii) ``extra`` (used to record any extra information pertaining to the start of a span).",
         "properties": {
            "extra": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Additional data that is associated with the content. This field is optional.",
               "title": "Extra"
            },
            "kind": {
               "const": "begin",
               "default": "begin",
               "title": "Kind",
               "type": "string"
            },
            "state": {
               "anyOf": [
                  {},
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The state logged on entering a span.",
               "title": "State"
            }
         },
         "title": "BeginContent",
         "type": "object"
      },
      "ChatCompletionContent": {
         "description": "ChatCompletion refers to messages that are generated using a language model.\n\n.. card:: Class Description\n\n    Chat completion messages refer to the output \"predicted\" text of a language model.\n    In the context of \"agentic\" applications, these messages are distinct from :py:class:`ToolCallContent` messages\n    (even though both are generated using LLMs).\n\n    A chat completion message has one required field: ``output``.\n    The ``output`` field refers to the unstructured generated text returned by the language model.\n\n    To capture the breadth of LLM-provider metadata, chat completion messages may also contain a ``meta`` field\n    (used to capture the raw response associated with the chat completion).\n    Finally, any extra data that exists outside the raw response can be stored in the optional ``extra`` field.",
         "properties": {
            "extra": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Additional data that is associated with the content. This field is optional.",
               "title": "Extra"
            },
            "kind": {
               "const": "chat-completion",
               "default": "chat-completion",
               "title": "Kind",
               "type": "string"
            },
            "output": {
               "description": "The output of the model.",
               "title": "Output",
               "type": "string"
            },
            "meta": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The raw response associated with the chat completion. This must be JSON-serializable.",
               "title": "Meta"
            }
         },
         "required": [
            "output"
         ],
         "title": "ChatCompletionContent",
         "type": "object"
      },
      "EdgeContent": {
         "description": "Edge refers to messages used to capture a caller's intent to 'handoff' some state to another span.\n\n.. card:: Card Description\n\n    Edge messages denote the explicit intent to invoke another unit of work.\n    In the case of multi-agent applications, this type of message can be used to capture how one agent might call\n    another agent.\n\n    Edge messages have two required fields: i) ``source``, the fully qualified name of the source :py:class:`Span`,\n    and ii) ``dest``, the fully qualified name of the destination :py:class:`Span`.\n    A ``payload`` field can optionally be recorded in an edge message to model spans as a functional unit of work\n    (which they are in most cases).\n    If extra data is associated with the edge message, it can be stored in the optional ``extra`` field.\n\n    There are two paradigms around span to span \"communication\": a) *horizontal* and b) *vertical*.\n    Horizontal communication refers to (span) graphs that are managed by some orchestrator (e.g., LangGraph, CrewAI,\n    etc...), while vertical communication refers to (span) graphs that are built by directly invoking other spans\n    (ultimately building a call stack).\n\n    .. note::\n\n        In the case of our :py:class:`agentc_langgraph.agent.ReActAgent` helper class, a ``previous_node`` field is\n        used to help build these edges for horizontal communication.",
         "properties": {
            "extra": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Additional data that is associated with the content. This field is optional.",
               "title": "Extra"
            },
            "kind": {
               "const": "edge",
               "default": "edge",
               "title": "Kind",
               "type": "string"
            },
            "source": {
               "description": "Name of the source span associated with this edge.",
               "items": {
                  "type": "string"
               },
               "title": "Source",
               "type": "array"
            },
            "dest": {
               "description": "Name of the destination span associated with this edge.",
               "items": {
                  "type": "string"
               },
               "title": "Dest",
               "type": "array"
            },
            "payload": {
               "anyOf": [
                  {},
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A (JSON-serializable) item being sent from the source span to the destination span.",
               "title": "Payload"
            }
         },
         "required": [
            "source",
            "dest"
         ],
         "title": "EdgeContent",
         "type": "object"
      },
      "EndContent": {
         "description": "End refers to marker messages that are used to indicate the end of a span (e.g., a task, agent, state, etc...).\n\n.. card:: Class Description\n\n    End messages denote the end of a span *and* (perhaps just as important) record the exit state of a span.\n    In certain applications, log analysts are able to use this information to model how the state of an application\n    mutates over time.\n\n    End messages have two optional fields: i) the ``state`` field (used to record the ending state of a span)\n    and ii) ``extra`` (used to record any extra information pertaining to the end of a span).",
         "properties": {
            "extra": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Additional data that is associated with the content. This field is optional.",
               "title": "Extra"
            },
            "kind": {
               "const": "end",
               "default": "end",
               "title": "Kind",
               "type": "string"
            },
            "state": {
               "anyOf": [
                  {},
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The state logged on exiting a span.",
               "title": "State"
            }
         },
         "title": "EndContent",
         "type": "object"
      },
      "KeyValueContent": {
         "description": "KeyValue refers to messages that contain user-specified data that are to be logged under some span.\n\n.. card:: Class Description\n\n    Key-value messages serve as the catch-all container for user-defined data that belong to some span.\n    We distinguish key-value messages from log-level *annotations*, which are used to attach information to a log\n    entry with existing content.\n\n    Key-value messages have two required fields: i) the ``key`` field (used to record the name of the entry)\n    and ii) ``value`` (used to record the value of the entry).\n    Extra data can also be passed in through the optional ``extra`` field (as with other messages).\n\n    Using the :python:`[]` syntax with a :py:class:`agentc.span.Span` instance generates one key-value entry per\n    call.\n    For example, the following code snippet generates two logs with the same key but different values:\n\n    .. code-block:: python\n\n        my_span = catalog.Span(name=\"my_span\")\n        my_span[\"alpha\"] = alpha_value_1\n        my_span[\"alpha\"] = alpha_value_2\n\n    These messages are commonly purposed for recording evaluation data, as seen in our example application\n    `here <https://github.com/couchbaselabs/agent-catalog/tree/master/examples/with_langgraph>`__.",
         "properties": {
            "extra": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Additional data that is associated with the content. This field is optional.",
               "title": "Extra"
            },
            "kind": {
               "const": "key-value",
               "default": "key-value",
               "title": "Kind",
               "type": "string"
            },
            "key": {
               "description": "The name of the key-value pair.",
               "title": "Key",
               "type": "string"
            },
            "value": {
               "description": "The value of the key-value pair. This value should be JSON-serializable.",
               "title": "Value"
            }
         },
         "required": [
            "key",
            "value"
         ],
         "title": "KeyValueContent",
         "type": "object"
      },
      "RequestHeaderContent": {
         "description": "RequestHeader refers to messages that *specifically* capture tools and output types used in a request to a\nlanguage model.\n\n.. card:: Class Description\n\n    Request header messages are used to record \"setup\" information for subsequent chat-completion and/or tool-call\n    events.\n    These primarily include tools (dictionaries of names, descriptions, and function schemas) and output types.\n\n    All fields of a request header message are optional: ``tools``, ``output``, ``meta``, and ``extra``.\n    The ``tools`` field is a list of :py:class:`RequestHeaderContent.Tool` instances made available to subsequent\n    LLM calls.\n    The ``output`` field refers to the output type that subsequent LLM calls must adhere to (most commonly expressed\n    in JSON schema).\n    The ``meta`` field refers to a JSON-serializable object containing the request information.\n    Finally, ``extra`` is used to capture any other data that does not belong in ``meta``.\n\n.. tip::\n\n    Pydantic enables the specification of their objects using dictionaries.\n    The code snippet below demonstrates two equivalent approaches to specifying the :py:attr:`tools` attribute:\n    First, users can create :py:class:`RequestHeaderContent.Tool` instances by referencing the subclass directly:\n\n    .. code-block:: python\n\n        from agentc.span import RequestHeaderContent\n\n        request_header_content = RequestHeaderContent(\n            tools=[\n                RequestHeaderContent.Tool(\n                    name=\"get_user_by_id\",\n                    description=\"Lookup a user by their ID field.\",\n                    args_schema={\"type\": \"object\", \"properties\": {\"id\": {\"type\": \"integer\"}}}\n                )\n            ]\n        )\n\n    Second, users can specify a dictionary:\n\n    .. code-block:: python\n\n        from agentc.span import RequestHeaderContent\n\n        request_header_content = RequestHeaderContent(\n            tools=[\n                {\n                    \"name\": \"get_user_by_id\",\n                    \"description\": \"Lookup a user by their ID field.\",\n                    \"args_schema\": {\"type\": \"object\", \"properties\": {\"id\": {\"type\": \"integer\"}}}\n                }\n            ]\n        )\n\n    For most cases though, we recommend the former (as this enables most IDEs to catch name errors before runtime).",
         "properties": {
            "extra": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Additional data that is associated with the content. This field is optional.",
               "title": "Extra"
            },
            "kind": {
               "const": "request-header",
               "default": "request-header",
               "title": "Kind",
               "type": "string"
            },
            "tools": {
               "anyOf": [
                  {
                     "items": {
                        "$ref": "#/$defs/Tool"
                     },
                     "type": "array"
                  },
                  {
                     "type": "null"
                  }
               ],
               "description": "The tools (name, description, schema) included in the request to a model. For tools indexed by Agent Catalog, this field should refer to the tool's 'name' field. This field is optional.",
               "title": "Tools"
            },
            "output": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The output type of the model (in JSON schema) response. This field is optional.",
               "title": "Output"
            },
            "meta": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "All request parameters associated with the model input. This must be JSON-serializable.",
               "title": "Meta"
            }
         },
         "title": "RequestHeaderContent",
         "type": "object"
      },
      "Span": {
         "properties": {
            "session": {
               "description": "The 'session' (a runtime identifier) that this span is associated with.",
               "title": "Session",
               "type": "string"
            },
            "name": {
               "description": "The name of the span. This is a list of names that represent the span hierarchy.",
               "examples": [
                  [
                     "my_application",
                     "my_agent",
                     "my_task"
                  ],
                  [
                     "my_application",
                     "my_agent"
                  ]
               ],
               "items": {
                  "type": "string"
               },
               "title": "Name",
               "type": "array"
            }
         },
         "required": [
            "name"
         ],
         "title": "Span",
         "type": "object"
      },
      "SystemContent": {
         "description": "System refers to messages that are generated by (none other than) the system or application.\n\n.. card:: Class Description\n\n    In agent frameworks, these messages are typically templated and instantiated with application-defined\n    objectives / instructions.\n    In our integration packages (e.g., :py:class:`agentc_langchain.chat.Callback`), system messages are commonly\n    used to record the contents used to generate a chat-completion or tool-call message.\n\n    A system message has a single required field, ``value``, which contains the content of the system message.\n    If extra data is associated with the system message (e.g., LangGraph's ``run_id`` fields), it can be stored in\n    the optional ``extra`` field.",
         "properties": {
            "extra": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Additional data that is associated with the content. This field is optional.",
               "title": "Extra"
            },
            "kind": {
               "const": "system",
               "default": "system",
               "title": "Kind",
               "type": "string"
            },
            "value": {
               "description": "The content of the system message.",
               "title": "Value",
               "type": "string"
            }
         },
         "required": [
            "value"
         ],
         "title": "SystemContent",
         "type": "object"
      },
      "Tool": {
         "properties": {
            "name": {
               "description": "The name of the tool.",
               "title": "Name",
               "type": "string"
            },
            "description": {
               "description": "A description of the tool.",
               "title": "Description",
               "type": "string"
            },
            "args_schema": {
               "additionalProperties": true,
               "description": "The (JSON) schema of the tool.",
               "title": "Args Schema",
               "type": "object"
            }
         },
         "required": [
            "name",
            "description",
            "args_schema"
         ],
         "title": "Tool",
         "type": "object"
      },
      "ToolCallContent": {
         "description": "ToolCall refers to messages that contain (typically LLM generated) arguments for invoking a tool.\n\n.. card:: Class Description\n\n    LLMs enable the invocation of standard Python functions (i.e., \"tools\") by a) \"selecting\" tools from some larger\n    tool-set and b) generating arguments to these tools.\n    This type of content is not to be confused with :py:class:`ToolResult` messages which contain the results of\n    invoking a tool (i.e., the output).\n\n    A tool call message has two required fields: ``tool_name`` and ``tool_args``.\n    The ``tool_name`` field refers to the name of the tool that is being called.\n    The ``tool_args`` field contains the arguments that are going to be passed to the tool (represented as a\n    dictionary keyed by parameter names whose entries are the parameter values).\n\n    Optional fields for a tool call message include ``tool_call_id``, ``status``, ``meta``, and ``extra``.\n    The ``tool_call_id`` field is an optional unique identifier associated with a tool call instance and is used\n    to correlate the call to the result of its execution (i.e., the :py:class:`ToolResult` message) by the\n    application.\n    The ``status`` field is an optional field that indicates the status of *generating* the tool call message\n    (e.g., the generated output does not adhere to the function signature).\n    To capture the breadth of LLM-provider metadata, tool call messages may also contain a ``meta`` field\n    (used to capture the raw response associated with the tool call message).\n    If extra data is associated with the tool call (e.g., the log-probabilities), it can be stored in the optional\n    ``extra`` field.\n\n.. tip::\n\n    If ``tool_call_id`` is not specified *but* your application calls and executes tools sequentially, you can still\n    link the tool call to the corresponding tool result by using the order of the messages in the log.\n    This is the approach taken by the :sql:`ToolInvocations` view (more information can be found\n    `here <analysis.html#toolinvocations-view>`__).",
         "properties": {
            "extra": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Additional data that is associated with the content. This field is optional.",
               "title": "Extra"
            },
            "kind": {
               "const": "tool-call",
               "default": "tool-call",
               "title": "Kind",
               "type": "string"
            },
            "tool_name": {
               "description": "The name of the tool that is being called. If this tool is indexed with Agent Catalog, this field should refer to the tool's 'name' field.",
               "title": "Tool Name",
               "type": "string"
            },
            "tool_args": {
               "additionalProperties": true,
               "description": "The arguments that are going to be passed to the tool. This field should be JSON-serializable.",
               "title": "Tool Args",
               "type": "object"
            },
            "tool_call_id": {
               "description": "The unique identifier associated with a tool call instance. This field is (typically) parsed from a LLM response and is used to correlate / JOIN this message with the corresponding ToolResult message.",
               "title": "Tool Call Id",
               "type": "string"
            },
            "status": {
               "anyOf": [
                  {
                     "enum": [
                        "success",
                        "error"
                     ],
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": "success",
               "title": "Status"
            },
            "meta": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The raw response associated with the tool call. This must be JSON-serializable.",
               "title": "Meta"
            }
         },
         "required": [
            "tool_name",
            "tool_args",
            "tool_call_id"
         ],
         "title": "ToolCallContent",
         "type": "object"
      },
      "ToolResultContent": {
         "description": "ToolResult refers to messages containing the results of invoking a tool.\n\n.. card:: Class Description\n\n    Tool result messages are used to capture the output of invoking a tool (i.e., the result of the tool call).\n    This type of content is not to be confused with :py:class:`ToolCall` messages which contain the arguments for\n    invoking a tool.\n\n    A tool result message has a single required field, ``tool_result``, which contains a JSON-serializable object\n    representing the result of executing the tool.\n\n    Optional fields for a tool result message include ``tool_call_id``, ``status``, and ``extra``.\n    The ``tool_call_id`` field is an optional unique identifier associated with a tool call instance and is used\n    here to correlate the execution of a tool to its call generation.\n    ``status`` is an optional field that indicates the status of the tool invocation (i.e., \"success\", or \"error\"\n    if the tool itself raised an exception).\n    Finally, if extra data is associated with the tool result (e.g., the error message on unsuccessful tool\n    invocations), it can be stored in the optional ``extra`` field.",
         "properties": {
            "extra": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Additional data that is associated with the content. This field is optional.",
               "title": "Extra"
            },
            "kind": {
               "const": "tool-result",
               "default": "tool-result",
               "title": "Kind",
               "type": "string"
            },
            "tool_call_id": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The unique identifier of the tool call. This field will be used to correlate / JOIN this message with the corresponding ToolCall message.",
               "title": "Tool Call Id"
            },
            "tool_result": {
               "description": "The result of invoking the tool. This field should be JSON-serializable.",
               "title": "Tool Result"
            },
            "status": {
               "anyOf": [
                  {
                     "enum": [
                        "success",
                        "error"
                     ],
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": "success",
               "description": "The status of the tool invocation. This field should be one of 'success' or 'error'.",
               "title": "Status"
            }
         },
         "required": [
            "tool_result"
         ],
         "title": "ToolResultContent",
         "type": "object"
      },
      "UserContent": {
         "description": "User refers to messages that are directly sent by (none other than) the user.\n\n.. card:: Class Description\n\n    User messages are used to capture a user's input into your application.\n    User messages exclude those generated by a prior LLM call for the purpose of \"mocking\" an intelligent actor\n    (e.g., multi-agent applications).\n\n    A user message has a single required field, ``value``, which contains the direct input given by the user.\n    If extra data is associated with the user message, it can be stored in the optional ``extra`` field.",
         "properties": {
            "extra": {
               "anyOf": [
                  {
                     "additionalProperties": true,
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "Additional data that is associated with the content. This field is optional.",
               "title": "Extra"
            },
            "kind": {
               "const": "user",
               "default": "user",
               "title": "Kind",
               "type": "string"
            },
            "value": {
               "description": "The captured user input.",
               "title": "Value",
               "type": "string"
            },
            "user_id": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "The unique identifier of the user. This field is optional.",
               "title": "User Id"
            }
         },
         "required": [
            "value"
         ],
         "title": "UserContent",
         "type": "object"
      },
      "VersionDescriptor": {
         "properties": {
            "timestamp": {
               "description": "Timestamp of the generated message. This field must have a timezone attached as well.",
               "examples": [
                  "2024-08-26T12:02:59.500Z",
                  "2024-08-26T12:02:59.500+00:00"
               ],
               "format": "date-time",
               "title": "Timestamp",
               "type": "string"
            },
            "identifier": {
               "anyOf": [
                  {
                     "type": "string"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A unique identifier that defines a catalog snapshot / version / commit. For git, this is the git repo commit SHA / HASH.",
               "examples": [
                  "g11223344"
               ],
               "title": "Identifier"
            },
            "is_dirty": {
               "anyOf": [
                  {
                     "type": "boolean"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": false,
               "description": "True if the item being described is 'dirty' (i.e., has diverged from the file captured with its identifier.).",
               "title": "Is Dirty"
            },
            "version_system": {
               "$ref": "#/$defs/VersionSystem",
               "default": "git",
               "description": "The kind of versioning system used with this \"snapshot\"."
            },
            "metadata": {
               "anyOf": [
                  {
                     "additionalProperties": {
                        "type": "string"
                     },
                     "type": "object"
                  },
                  {
                     "type": "null"
                  }
               ],
               "default": null,
               "description": "A set of system-defined annotations that are used to identify records.",
               "title": "Metadata"
            }
         },
         "required": [
            "timestamp"
         ],
         "title": "VersionDescriptor",
         "type": "object"
      },
      "VersionSystem": {
         "enum": [
            "git",
            "raw"
         ],
         "title": "VersionSystem",
         "type": "string"
      }
   },
   "required": [
      "span",
      "timestamp",
      "content",
      "catalog_version"
   ]
}

field annotations: Dict | None = None

Additional annotations that can be added to the message.

field catalog_version: VersionDescriptor [Required]

A unique identifier that defines a catalog version / snapshot / commit.

field content: SystemContent | ToolCallContent | ToolResultContent | ChatCompletionContent | RequestHeaderContent | UserContent | AssistantContent | BeginContent | EndContent | EdgeContent | KeyValueContent [Required]

The content of the record. This should be as close to the producer as possible.

field identifier: str [Optional]

A unique identifier for this record. This field is typically a UUID.

field span: Log.Span [Required]

The span (i.e., a list of names and a session ID) that this record is associated with.

field timestamp: AwareDatetime [Required]

Timestamp of the generated record. This field must have a timezone attached as well.

pydantic model Span

Show JSON schema

{
   "title": "Span",
   "type": "object",
   "properties": {
      "session": {
         "description": "The 'session' (a runtime identifier) that this span is associated with.",
         "title": "Session",
         "type": "string"
      },
      "name": {
         "description": "The name of the span. This is a list of names that represent the span hierarchy.",
         "examples": [
            [
               "my_application",
               "my_agent",
               "my_task"
            ],
            [
               "my_application",
               "my_agent"
            ]
         ],
         "items": {
            "type": "string"
         },
         "title": "Name",
         "type": "array"
      }
   },
   "required": [
      "name"
   ]
}

field name: list[str] [Required]

The name of the span. This is a list of names that represent the span hierarchy.

field session: str [Optional]

The 'session' (a runtime identifier) that this span is associated with.

Content in Logs

enum agentc_core.activity.models.content.Kind(value)

The different types of log content that are recognized.

Member Type:

str

Valid values are as follows:

System = <Kind.System: 'system'>

System refers to messages that are generated by (none other than) the system or application. In agent frameworks, these messages are typically templated and instantiated with application-defined objectives / instructions.

ToolCall = <Kind.ToolCall: 'tool-call'>

ToolCall refers to messages that contain (typically LLM generated) arguments for invoking a tool. These logs are not to be confused with ToolResult messages which contain the results of invoking a tool.

ToolResult = <Kind.ToolResult: 'tool-result'>

ToolResult refers to messages containing the results of invoking a tool. These logs are not to be confused with ToolCall messages which are (typically) generated by an LLM.

ChatCompletion = <Kind.ChatCompletion: 'chat-completion'>

ChatCompletion refers to messages that are generated using a language model. Ideally, these messages should be captured immediately after generation (without any post-processing).

RequestHeader = <Kind.RequestHeader: 'request-header'>

RequestHeader refers to messages that specifically capture tools and output types used in a request to a language model.

User = <Kind.User: 'user'>

User refers to messages that are directly sent by (none other than) the user. If the application uses prompt templates, these messages refer to the raw user input (not the templated text).

Assistant = <Kind.Assistant: 'assistant'>

Assistant refers to messages that are directly served back to the user. These messages exclude any ModelOutput or System messages that are used internally by the application.

Begin = <Kind.Begin: 'begin'>

Begin refers to marker messages that are used to indicate the start of a span (e.g., a task, agent, state, etc...). These messages are typically used to trace how one unit of work mutates some state, and are application specific.

End = <Kind.End: 'end'>

End refers to marker messages that are used to indicate the end of a span (e.g., a task, agent, state, etc...). These messages are typically used to trace how one unit of work mutates some state, and are application specific.

Edge = <Kind.Edge: 'edge'>

Edge refers to marker messages that are used to indicate one unit of work (essentially) invoking another unit of work. These messages can be used to trace 'handoffs' and 'agent-to-agent' communication.

KeyValue = <Kind.KeyValue: 'key-value'>

KeyValue refers to messages that contain user-specified data that are to be logged under some span.

pydantic model agentc_core.activity.models.content.SystemContent

System refers to messages that are generated by (none other than) the system or application.

Class Description

In agent frameworks, these messages are typically templated and instantiated with application-defined objectives / instructions. In our integration packages (e.g., agentc_langchain.chat.Callback), system messages are commonly used to record the contents used to generate a chat-completion or tool-call message.

A system message has a single required field, value, which contains the content of the system message. If extra data is associated with the system message (e.g., LangGraph's run_id fields), it can be stored in the optional extra field.

Show JSON schema

{
   "title": "SystemContent",
   "description": "System refers to messages that are generated by (none other than) the system or application.\n\n.. card:: Class Description\n\n    In agent frameworks, these messages are typically templated and instantiated with application-defined\n    objectives / instructions.\n    In our integration packages (e.g., :py:class:`agentc_langchain.chat.Callback`), system messages are commonly\n    used to record the contents used to generate a chat-completion or tool-call message.\n\n    A system message has a single required field, ``value``, which contains the content of the system message.\n    If extra data is associated with the system message (e.g., LangGraph's ``run_id`` fields), it can be stored in\n    the optional ``extra`` field.",
   "type": "object",
   "properties": {
      "extra": {
         "anyOf": [
            {
               "additionalProperties": true,
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Additional data that is associated with the content. This field is optional.",
         "title": "Extra"
      },
      "kind": {
         "const": "system",
         "default": "system",
         "title": "Kind",
         "type": "string"
      },
      "value": {
         "description": "The content of the system message.",
         "title": "Value",
         "type": "string"
      }
   },
   "required": [
      "value"
   ]
}

Config:

• frozen: bool = True

• use_enum_values: bool = True

Fields:

• extra (dict | None)

• kind (Literal[agentc_core.activity.models.content.Kind.System])

• value (str)

field extra: Optional[dict] = None

Additional data that is associated with the content. This field is optional.

field kind: Literal[Kind.System] = Kind.System

field value: str [Required]

The content of the system message.

pydantic model agentc_core.activity.models.content.ToolCallContent

ToolCall refers to messages that contain (typically LLM generated) arguments for invoking a tool.

Class Description

LLMs enable the invocation of standard Python functions (i.e., "tools") by a) "selecting" tools from some larger tool-set and b) generating arguments to these tools. This type of content is not to be confused with ToolResult messages which contain the results of invoking a tool (i.e., the output).

A tool call message has two required fields: tool_name and tool_args. The tool_name field refers to the name of the tool that is being called. The tool_args field contains the arguments that are going to be passed to the tool (represented as a dictionary keyed by parameter names whose entries are the parameter values).

Optional fields for a tool call message include tool_call_id, status, meta, and extra. The tool_call_id field is an optional unique identifier associated with a tool call instance and is used to correlate the call to the result of its execution (i.e., the ToolResult message) by the application. The status field is an optional field that indicates the status of generating the tool call message (e.g., the generated output does not adhere to the function signature). To capture the breadth of LLM-provider metadata, tool call messages may also contain a meta field (used to capture the raw response associated with the tool call message). If extra data is associated with the tool call (e.g., the log-probabilities), it can be stored in the optional extra field.

Tip

If tool_call_id is not specified but your application calls and executes tools sequentially, you can still link the tool call to the corresponding tool result by using the order of the messages in the log. This is the approach taken by the ToolInvocations view (more information can be found here).

Show JSON schema

{
   "title": "ToolCallContent",
   "description": "ToolCall refers to messages that contain (typically LLM generated) arguments for invoking a tool.\n\n.. card:: Class Description\n\n    LLMs enable the invocation of standard Python functions (i.e., \"tools\") by a) \"selecting\" tools from some larger\n    tool-set and b) generating arguments to these tools.\n    This type of content is not to be confused with :py:class:`ToolResult` messages which contain the results of\n    invoking a tool (i.e., the output).\n\n    A tool call message has two required fields: ``tool_name`` and ``tool_args``.\n    The ``tool_name`` field refers to the name of the tool that is being called.\n    The ``tool_args`` field contains the arguments that are going to be passed to the tool (represented as a\n    dictionary keyed by parameter names whose entries are the parameter values).\n\n    Optional fields for a tool call message include ``tool_call_id``, ``status``, ``meta``, and ``extra``.\n    The ``tool_call_id`` field is an optional unique identifier associated with a tool call instance and is used\n    to correlate the call to the result of its execution (i.e., the :py:class:`ToolResult` message) by the\n    application.\n    The ``status`` field is an optional field that indicates the status of *generating* the tool call message\n    (e.g., the generated output does not adhere to the function signature).\n    To capture the breadth of LLM-provider metadata, tool call messages may also contain a ``meta`` field\n    (used to capture the raw response associated with the tool call message).\n    If extra data is associated with the tool call (e.g., the log-probabilities), it can be stored in the optional\n    ``extra`` field.\n\n.. tip::\n\n    If ``tool_call_id`` is not specified *but* your application calls and executes tools sequentially, you can still\n    link the tool call to the corresponding tool result by using the order of the messages in the log.\n    This is the approach taken by the :sql:`ToolInvocations` view (more information can be found\n    `here <analysis.html#toolinvocations-view>`__).",
   "type": "object",
   "properties": {
      "extra": {
         "anyOf": [
            {
               "additionalProperties": true,
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Additional data that is associated with the content. This field is optional.",
         "title": "Extra"
      },
      "kind": {
         "const": "tool-call",
         "default": "tool-call",
         "title": "Kind",
         "type": "string"
      },
      "tool_name": {
         "description": "The name of the tool that is being called. If this tool is indexed with Agent Catalog, this field should refer to the tool's 'name' field.",
         "title": "Tool Name",
         "type": "string"
      },
      "tool_args": {
         "additionalProperties": true,
         "description": "The arguments that are going to be passed to the tool. This field should be JSON-serializable.",
         "title": "Tool Args",
         "type": "object"
      },
      "tool_call_id": {
         "description": "The unique identifier associated with a tool call instance. This field is (typically) parsed from a LLM response and is used to correlate / JOIN this message with the corresponding ToolResult message.",
         "title": "Tool Call Id",
         "type": "string"
      },
      "status": {
         "anyOf": [
            {
               "enum": [
                  "success",
                  "error"
               ],
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": "success",
         "title": "Status"
      },
      "meta": {
         "anyOf": [
            {
               "additionalProperties": true,
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The raw response associated with the tool call. This must be JSON-serializable.",
         "title": "Meta"
      }
   },
   "required": [
      "tool_name",
      "tool_args",
      "tool_call_id"
   ]
}

Config:

• frozen: bool = True

• use_enum_values: bool = True

Fields:

• extra (dict | None)

• kind (Literal[agentc_core.activity.models.content.Kind.ToolCall])

• meta (dict | None)

• status (Literal['success', 'error'] | None)

• tool_args (dict[str, Any])

• tool_call_id (str)

• tool_name (str)

field extra: Optional[dict] = None

Additional data that is associated with the content. This field is optional.

field kind: Literal[Kind.ToolCall] = Kind.ToolCall

field meta: dict | None = None

The raw response associated with the tool call. This must be JSON-serializable.

field status: Literal['success', 'error'] | None = 'success'

field tool_args: dict[str, Any] [Required]

The arguments that are going to be passed to the tool. This field should be JSON-serializable.

field tool_call_id: str [Required]

The unique identifier associated with a tool call instance. This field is (typically) parsed from a LLM response and is used to correlate / JOIN this message with the corresponding ToolResult message.

field tool_name: str [Required]

The name of the tool that is being called. If this tool is indexed with Agent Catalog, this field should refer to the tool's 'name' field.

pydantic model agentc_core.activity.models.content.ToolResultContent

ToolResult refers to messages containing the results of invoking a tool.

Class Description

Tool result messages are used to capture the output of invoking a tool (i.e., the result of the tool call). This type of content is not to be confused with ToolCall messages which contain the arguments for invoking a tool.

A tool result message has a single required field, tool_result, which contains a JSON-serializable object representing the result of executing the tool.

Optional fields for a tool result message include tool_call_id, status, and extra. The tool_call_id field is an optional unique identifier associated with a tool call instance and is used here to correlate the execution of a tool to its call generation. status is an optional field that indicates the status of the tool invocation (i.e., "success", or "error" if the tool itself raised an exception). Finally, if extra data is associated with the tool result (e.g., the error message on unsuccessful tool invocations), it can be stored in the optional extra field.

Show JSON schema

{
   "title": "ToolResultContent",
   "description": "ToolResult refers to messages containing the results of invoking a tool.\n\n.. card:: Class Description\n\n    Tool result messages are used to capture the output of invoking a tool (i.e., the result of the tool call).\n    This type of content is not to be confused with :py:class:`ToolCall` messages which contain the arguments for\n    invoking a tool.\n\n    A tool result message has a single required field, ``tool_result``, which contains a JSON-serializable object\n    representing the result of executing the tool.\n\n    Optional fields for a tool result message include ``tool_call_id``, ``status``, and ``extra``.\n    The ``tool_call_id`` field is an optional unique identifier associated with a tool call instance and is used\n    here to correlate the execution of a tool to its call generation.\n    ``status`` is an optional field that indicates the status of the tool invocation (i.e., \"success\", or \"error\"\n    if the tool itself raised an exception).\n    Finally, if extra data is associated with the tool result (e.g., the error message on unsuccessful tool\n    invocations), it can be stored in the optional ``extra`` field.",
   "type": "object",
   "properties": {
      "extra": {
         "anyOf": [
            {
               "additionalProperties": true,
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Additional data that is associated with the content. This field is optional.",
         "title": "Extra"
      },
      "kind": {
         "const": "tool-result",
         "default": "tool-result",
         "title": "Kind",
         "type": "string"
      },
      "tool_call_id": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The unique identifier of the tool call. This field will be used to correlate / JOIN this message with the corresponding ToolCall message.",
         "title": "Tool Call Id"
      },
      "tool_result": {
         "description": "The result of invoking the tool. This field should be JSON-serializable.",
         "title": "Tool Result"
      },
      "status": {
         "anyOf": [
            {
               "enum": [
                  "success",
                  "error"
               ],
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": "success",
         "description": "The status of the tool invocation. This field should be one of 'success' or 'error'.",
         "title": "Status"
      }
   },
   "required": [
      "tool_result"
   ]
}

Config:

• frozen: bool = True

• use_enum_values: bool = True

Fields:

• extra (dict | None)

• kind (Literal[agentc_core.activity.models.content.Kind.ToolResult])

• status (Literal['success', 'error'] | None)

• tool_call_id (str | None)

• tool_result (Any)

field extra: Optional[dict] = None

Additional data that is associated with the content. This field is optional.

field kind: Literal[Kind.ToolResult] = Kind.ToolResult

field status: Literal['success', 'error'] | None = 'success'

The status of the tool invocation. This field should be one of 'success' or 'error'.

field tool_call_id: str | None = None

The unique identifier of the tool call. This field will be used to correlate / JOIN this message with the corresponding ToolCall message.

field tool_result: Any [Required]

The result of invoking the tool. This field should be JSON-serializable.

pydantic model agentc_core.activity.models.content.ChatCompletionContent

ChatCompletion refers to messages that are generated using a language model.

Class Description

Chat completion messages refer to the output "predicted" text of a language model. In the context of "agentic" applications, these messages are distinct from ToolCallContent messages (even though both are generated using LLMs).

A chat completion message has one required field: output. The output field refers to the unstructured generated text returned by the language model.

To capture the breadth of LLM-provider metadata, chat completion messages may also contain a meta field (used to capture the raw response associated with the chat completion). Finally, any extra data that exists outside the raw response can be stored in the optional extra field.

Show JSON schema

{
   "title": "ChatCompletionContent",
   "description": "ChatCompletion refers to messages that are generated using a language model.\n\n.. card:: Class Description\n\n    Chat completion messages refer to the output \"predicted\" text of a language model.\n    In the context of \"agentic\" applications, these messages are distinct from :py:class:`ToolCallContent` messages\n    (even though both are generated using LLMs).\n\n    A chat completion message has one required field: ``output``.\n    The ``output`` field refers to the unstructured generated text returned by the language model.\n\n    To capture the breadth of LLM-provider metadata, chat completion messages may also contain a ``meta`` field\n    (used to capture the raw response associated with the chat completion).\n    Finally, any extra data that exists outside the raw response can be stored in the optional ``extra`` field.",
   "type": "object",
   "properties": {
      "extra": {
         "anyOf": [
            {
               "additionalProperties": true,
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Additional data that is associated with the content. This field is optional.",
         "title": "Extra"
      },
      "kind": {
         "const": "chat-completion",
         "default": "chat-completion",
         "title": "Kind",
         "type": "string"
      },
      "output": {
         "description": "The output of the model.",
         "title": "Output",
         "type": "string"
      },
      "meta": {
         "anyOf": [
            {
               "additionalProperties": true,
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The raw response associated with the chat completion. This must be JSON-serializable.",
         "title": "Meta"
      }
   },
   "required": [
      "output"
   ]
}

Config:

• frozen: bool = True

• use_enum_values: bool = True

Fields:

• extra (dict | None)

• kind (Literal[agentc_core.activity.models.content.Kind.ChatCompletion])

• meta (dict | None)

• output (str)

field extra: Optional[dict] = None

Additional data that is associated with the content. This field is optional.

field kind: Literal[Kind.ChatCompletion] = Kind.ChatCompletion

field meta: dict | None = None

The raw response associated with the chat completion. This must be JSON-serializable.

field output: str [Required]

The output of the model.

pydantic model agentc_core.activity.models.content.RequestHeaderContent

RequestHeader refers to messages that specifically capture tools and output types used in a request to a language model.

Class Description

Request header messages are used to record "setup" information for subsequent chat-completion and/or tool-call events. These primarily include tools (dictionaries of names, descriptions, and function schemas) and output types.

All fields of a request header message are optional: tools, output, meta, and extra. The tools field is a list of RequestHeaderContent.Tool instances made available to subsequent LLM calls. The output field refers to the output type that subsequent LLM calls must adhere to (most commonly expressed in JSON schema). The meta field refers to a JSON-serializable object containing the request information. Finally, extra is used to capture any other data that does not belong in meta.

Tip

Pydantic enables the specification of their objects using dictionaries. The code snippet below demonstrates two equivalent approaches to specifying the tools attribute: First, users can create RequestHeaderContent.Tool instances by referencing the subclass directly:

from agentc.span import RequestHeaderContent

request_header_content = RequestHeaderContent(
    tools=[
        RequestHeaderContent.Tool(
            name="get_user_by_id",
            description="Lookup a user by their ID field.",
            args_schema={"type": "object", "properties": {"id": {"type": "integer"}}}
        )
    ]
)

Second, users can specify a dictionary:

from agentc.span import RequestHeaderContent

request_header_content = RequestHeaderContent(
    tools=[
        {
            "name": "get_user_by_id",
            "description": "Lookup a user by their ID field.",
            "args_schema": {"type": "object", "properties": {"id": {"type": "integer"}}}
        }
    ]
)

For most cases though, we recommend the former (as this enables most IDEs to catch name errors before runtime).

Show JSON schema

{
   "title": "RequestHeaderContent",
   "description": "RequestHeader refers to messages that *specifically* capture tools and output types used in a request to a\nlanguage model.\n\n.. card:: Class Description\n\n    Request header messages are used to record \"setup\" information for subsequent chat-completion and/or tool-call\n    events.\n    These primarily include tools (dictionaries of names, descriptions, and function schemas) and output types.\n\n    All fields of a request header message are optional: ``tools``, ``output``, ``meta``, and ``extra``.\n    The ``tools`` field is a list of :py:class:`RequestHeaderContent.Tool` instances made available to subsequent\n    LLM calls.\n    The ``output`` field refers to the output type that subsequent LLM calls must adhere to (most commonly expressed\n    in JSON schema).\n    The ``meta`` field refers to a JSON-serializable object containing the request information.\n    Finally, ``extra`` is used to capture any other data that does not belong in ``meta``.\n\n.. tip::\n\n    Pydantic enables the specification of their objects using dictionaries.\n    The code snippet below demonstrates two equivalent approaches to specifying the :py:attr:`tools` attribute:\n    First, users can create :py:class:`RequestHeaderContent.Tool` instances by referencing the subclass directly:\n\n    .. code-block:: python\n\n        from agentc.span import RequestHeaderContent\n\n        request_header_content = RequestHeaderContent(\n            tools=[\n                RequestHeaderContent.Tool(\n                    name=\"get_user_by_id\",\n                    description=\"Lookup a user by their ID field.\",\n                    args_schema={\"type\": \"object\", \"properties\": {\"id\": {\"type\": \"integer\"}}}\n                )\n            ]\n        )\n\n    Second, users can specify a dictionary:\n\n    .. code-block:: python\n\n        from agentc.span import RequestHeaderContent\n\n        request_header_content = RequestHeaderContent(\n            tools=[\n                {\n                    \"name\": \"get_user_by_id\",\n                    \"description\": \"Lookup a user by their ID field.\",\n                    \"args_schema\": {\"type\": \"object\", \"properties\": {\"id\": {\"type\": \"integer\"}}}\n                }\n            ]\n        )\n\n    For most cases though, we recommend the former (as this enables most IDEs to catch name errors before runtime).",
   "type": "object",
   "properties": {
      "extra": {
         "anyOf": [
            {
               "additionalProperties": true,
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Additional data that is associated with the content. This field is optional.",
         "title": "Extra"
      },
      "kind": {
         "const": "request-header",
         "default": "request-header",
         "title": "Kind",
         "type": "string"
      },
      "tools": {
         "anyOf": [
            {
               "items": {
                  "$ref": "#/$defs/Tool"
               },
               "type": "array"
            },
            {
               "type": "null"
            }
         ],
         "description": "The tools (name, description, schema) included in the request to a model. For tools indexed by Agent Catalog, this field should refer to the tool's 'name' field. This field is optional.",
         "title": "Tools"
      },
      "output": {
         "anyOf": [
            {
               "additionalProperties": true,
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The output type of the model (in JSON schema) response. This field is optional.",
         "title": "Output"
      },
      "meta": {
         "anyOf": [
            {
               "additionalProperties": true,
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "All request parameters associated with the model input. This must be JSON-serializable.",
         "title": "Meta"
      }
   },
   "$defs": {
      "Tool": {
         "properties": {
            "name": {
               "description": "The name of the tool.",
               "title": "Name",
               "type": "string"
            },
            "description": {
               "description": "A description of the tool.",
               "title": "Description",
               "type": "string"
            },
            "args_schema": {
               "additionalProperties": true,
               "description": "The (JSON) schema of the tool.",
               "title": "Args Schema",
               "type": "object"
            }
         },
         "required": [
            "name",
            "description",
            "args_schema"
         ],
         "title": "Tool",
         "type": "object"
      }
   }
}

Config:

• frozen: bool = True

• use_enum_values: bool = True

Fields:

• extra (dict | None)

• kind (Literal[agentc_core.activity.models.content.Kind.RequestHeader])

• meta (dict | None)

• output (dict | None)

• tools (list[agentc_core.activity.models.content.RequestHeaderContent.Tool] | None)

field extra: Optional[dict] = None

Additional data that is associated with the content. This field is optional.

field kind: Literal[Kind.RequestHeader] = Kind.RequestHeader

field meta: dict | None = None

All request parameters associated with the model input. This must be JSON-serializable.

field output: dict | None = None

The output type of the model (in JSON schema) response. This field is optional.

field tools: list[Tool] | None = <class 'list'>

The tools (name, description, schema) included in the request to a model. For tools indexed by Agent Catalog, this field should refer to the tool's 'name' field. This field is optional.

pydantic model Tool

Show JSON schema

{
   "title": "Tool",
   "type": "object",
   "properties": {
      "name": {
         "description": "The name of the tool.",
         "title": "Name",
         "type": "string"
      },
      "description": {
         "description": "A description of the tool.",
         "title": "Description",
         "type": "string"
      },
      "args_schema": {
         "additionalProperties": true,
         "description": "The (JSON) schema of the tool.",
         "title": "Args Schema",
         "type": "object"
      }
   },
   "required": [
      "name",
      "description",
      "args_schema"
   ]
}

Fields:

• args_schema (dict)

• description (str)

• name (str)

field args_schema: dict [Required]

The (JSON) schema of the tool.

field description: str [Required]

A description of the tool.

field name: str [Required]

The name of the tool.

pydantic model agentc_core.activity.models.content.UserContent

User refers to messages that are directly sent by (none other than) the user.

Class Description

User messages are used to capture a user's input into your application. User messages exclude those generated by a prior LLM call for the purpose of "mocking" an intelligent actor (e.g., multi-agent applications).

A user message has a single required field, value, which contains the direct input given by the user. If extra data is associated with the user message, it can be stored in the optional extra field.

Show JSON schema

{
   "title": "UserContent",
   "description": "User refers to messages that are directly sent by (none other than) the user.\n\n.. card:: Class Description\n\n    User messages are used to capture a user's input into your application.\n    User messages exclude those generated by a prior LLM call for the purpose of \"mocking\" an intelligent actor\n    (e.g., multi-agent applications).\n\n    A user message has a single required field, ``value``, which contains the direct input given by the user.\n    If extra data is associated with the user message, it can be stored in the optional ``extra`` field.",
   "type": "object",
   "properties": {
      "extra": {
         "anyOf": [
            {
               "additionalProperties": true,
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Additional data that is associated with the content. This field is optional.",
         "title": "Extra"
      },
      "kind": {
         "const": "user",
         "default": "user",
         "title": "Kind",
         "type": "string"
      },
      "value": {
         "description": "The captured user input.",
         "title": "Value",
         "type": "string"
      },
      "user_id": {
         "anyOf": [
            {
               "type": "string"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The unique identifier of the user. This field is optional.",
         "title": "User Id"
      }
   },
   "required": [
      "value"
   ]
}

Config:

• frozen: bool = True

• use_enum_values: bool = True

Fields:

• extra (dict | None)

• kind (Literal[agentc_core.activity.models.content.Kind.User])

• user_id (str | None)

• value (str)

field extra: Optional[dict] = None

Additional data that is associated with the content. This field is optional.

field kind: Literal[Kind.User] = Kind.User

field user_id: str | None = None

The unique identifier of the user. This field is optional.

field value: str [Required]

The captured user input.

pydantic model agentc_core.activity.models.content.AssistantContent

Assistant refers to messages that are directly served back to the user.

Class Description

Assistant messages are used to capture the direct output of your application (i.e., the messages served back to the user). These messages are not strictly ChatCompletionContent messages, as your application may utilize multiple LLM calls before returning some message back to the user.

An assistant message has a single required field, value, which contains the direct output back to the user. If extra data is associated with the assistant message, it can be stored in the optional extra field.

Show JSON schema

{
   "title": "AssistantContent",
   "description": "Assistant refers to messages that are directly served back to the user.\n\n.. card:: Class Description\n\n    Assistant messages are used to capture the direct output of your application (i.e., the messages served back to\n    the user).\n    These messages are *not* strictly :py:class:`ChatCompletionContent` messages, as your application may utilize\n    multiple LLM calls before returning some message back to the user.\n\n    An assistant message has a single required field, ``value``, which contains the direct output back to the user.\n    If extra data is associated with the assistant message, it can be stored in the optional ``extra`` field.",
   "type": "object",
   "properties": {
      "extra": {
         "anyOf": [
            {
               "additionalProperties": true,
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Additional data that is associated with the content. This field is optional.",
         "title": "Extra"
      },
      "kind": {
         "const": "assistant",
         "default": "assistant",
         "title": "Kind",
         "type": "string"
      },
      "value": {
         "description": "The response served back to the user.",
         "title": "Value",
         "type": "string"
      }
   },
   "required": [
      "value"
   ]
}

Config:

• frozen: bool = True

• use_enum_values: bool = True

Fields:

• extra (dict | None)

• kind (Literal[agentc_core.activity.models.content.Kind.Assistant])

• value (str)

field extra: Optional[dict] = None

Additional data that is associated with the content. This field is optional.

field kind: Literal[Kind.Assistant] = Kind.Assistant

field value: str [Required]

The response served back to the user.

pydantic model agentc_core.activity.models.content.BeginContent

Begin refers to marker messages that are used to indicate the start of a span (e.g., a task, agent, state, etc...).

Card Description

Begin messages denote the start of a span and (perhaps just as important) record the entrance state of a span. In certain applications, log analysts are able to use this information to model how the state of an application mutates over time.

Begin messages have two optional fields: i) the state field (used to record the starting state of a span) and ii) extra (used to record any extra information pertaining to the start of a span).

Show JSON schema

{
   "title": "BeginContent",
   "description": "Begin refers to marker messages that are used to indicate the start of a span (e.g., a task, agent, state,\netc...).\n\n.. card:: Card Description\n\n    Begin messages denote the start of a span *and* (perhaps just as important) record the entrance state of a span.\n    In certain applications, log analysts are able to use this information to model how the state of an application\n    mutates over time.\n\n    Begin messages have two optional fields: i) the ``state`` field (used to record the starting state of a span)\n    and ii) ``extra`` (used to record any extra information pertaining to the start of a span).",
   "type": "object",
   "properties": {
      "extra": {
         "anyOf": [
            {
               "additionalProperties": true,
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Additional data that is associated with the content. This field is optional.",
         "title": "Extra"
      },
      "kind": {
         "const": "begin",
         "default": "begin",
         "title": "Kind",
         "type": "string"
      },
      "state": {
         "anyOf": [
            {},
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The state logged on entering a span.",
         "title": "State"
      }
   }
}

Config:

• frozen: bool = True

• use_enum_values: bool = True

Fields:

• extra (dict | None)

• kind (Literal[agentc_core.activity.models.content.Kind.Begin])

• state (Any | None)

field extra: Optional[dict] = None

Additional data that is associated with the content. This field is optional.

field kind: Literal[Kind.Begin] = Kind.Begin

field state: Any | None = None

The state logged on entering a span.

pydantic model agentc_core.activity.models.content.EndContent

End refers to marker messages that are used to indicate the end of a span (e.g., a task, agent, state, etc...).

Class Description

End messages denote the end of a span and (perhaps just as important) record the exit state of a span. In certain applications, log analysts are able to use this information to model how the state of an application mutates over time.

End messages have two optional fields: i) the state field (used to record the ending state of a span) and ii) extra (used to record any extra information pertaining to the end of a span).

Show JSON schema

{
   "title": "EndContent",
   "description": "End refers to marker messages that are used to indicate the end of a span (e.g., a task, agent, state, etc...).\n\n.. card:: Class Description\n\n    End messages denote the end of a span *and* (perhaps just as important) record the exit state of a span.\n    In certain applications, log analysts are able to use this information to model how the state of an application\n    mutates over time.\n\n    End messages have two optional fields: i) the ``state`` field (used to record the ending state of a span)\n    and ii) ``extra`` (used to record any extra information pertaining to the end of a span).",
   "type": "object",
   "properties": {
      "extra": {
         "anyOf": [
            {
               "additionalProperties": true,
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Additional data that is associated with the content. This field is optional.",
         "title": "Extra"
      },
      "kind": {
         "const": "end",
         "default": "end",
         "title": "Kind",
         "type": "string"
      },
      "state": {
         "anyOf": [
            {},
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "The state logged on exiting a span.",
         "title": "State"
      }
   }
}

Config:

• frozen: bool = True

• use_enum_values: bool = True

Fields:

• extra (dict | None)

• kind (Literal[agentc_core.activity.models.content.Kind.End])

• state (Any | None)

field extra: Optional[dict] = None

Additional data that is associated with the content. This field is optional.

field kind: Literal[Kind.End] = Kind.End

field state: Any | None = None

The state logged on exiting a span.

pydantic model agentc_core.activity.models.content.EdgeContent

Edge refers to messages used to capture a caller's intent to 'handoff' some state to another span.

Card Description

Edge messages denote the explicit intent to invoke another unit of work. In the case of multi-agent applications, this type of message can be used to capture how one agent might call another agent.

Edge messages have two required fields: i) source, the fully qualified name of the source Span, and ii) dest, the fully qualified name of the destination Span. A payload field can optionally be recorded in an edge message to model spans as a functional unit of work (which they are in most cases). If extra data is associated with the edge message, it can be stored in the optional extra field.

There are two paradigms around span to span "communication": a) horizontal and b) vertical. Horizontal communication refers to (span) graphs that are managed by some orchestrator (e.g., LangGraph, CrewAI, etc...), while vertical communication refers to (span) graphs that are built by directly invoking other spans (ultimately building a call stack).

Note

In the case of our agentc_langgraph.agent.ReActAgent helper class, a previous_node field is used to help build these edges for horizontal communication.

Show JSON schema

{
   "title": "EdgeContent",
   "description": "Edge refers to messages used to capture a caller's intent to 'handoff' some state to another span.\n\n.. card:: Card Description\n\n    Edge messages denote the explicit intent to invoke another unit of work.\n    In the case of multi-agent applications, this type of message can be used to capture how one agent might call\n    another agent.\n\n    Edge messages have two required fields: i) ``source``, the fully qualified name of the source :py:class:`Span`,\n    and ii) ``dest``, the fully qualified name of the destination :py:class:`Span`.\n    A ``payload`` field can optionally be recorded in an edge message to model spans as a functional unit of work\n    (which they are in most cases).\n    If extra data is associated with the edge message, it can be stored in the optional ``extra`` field.\n\n    There are two paradigms around span to span \"communication\": a) *horizontal* and b) *vertical*.\n    Horizontal communication refers to (span) graphs that are managed by some orchestrator (e.g., LangGraph, CrewAI,\n    etc...), while vertical communication refers to (span) graphs that are built by directly invoking other spans\n    (ultimately building a call stack).\n\n    .. note::\n\n        In the case of our :py:class:`agentc_langgraph.agent.ReActAgent` helper class, a ``previous_node`` field is\n        used to help build these edges for horizontal communication.",
   "type": "object",
   "properties": {
      "extra": {
         "anyOf": [
            {
               "additionalProperties": true,
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Additional data that is associated with the content. This field is optional.",
         "title": "Extra"
      },
      "kind": {
         "const": "edge",
         "default": "edge",
         "title": "Kind",
         "type": "string"
      },
      "source": {
         "description": "Name of the source span associated with this edge.",
         "items": {
            "type": "string"
         },
         "title": "Source",
         "type": "array"
      },
      "dest": {
         "description": "Name of the destination span associated with this edge.",
         "items": {
            "type": "string"
         },
         "title": "Dest",
         "type": "array"
      },
      "payload": {
         "anyOf": [
            {},
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "A (JSON-serializable) item being sent from the source span to the destination span.",
         "title": "Payload"
      }
   },
   "required": [
      "source",
      "dest"
   ]
}

Config:

• frozen: bool = True

• use_enum_values: bool = True

Fields:

• dest (list[str])

• extra (dict | None)

• kind (Literal[agentc_core.activity.models.content.Kind.Edge])

• payload (Any | None)

• source (list[str])

field dest: list[str] [Required]

Name of the destination span associated with this edge.

field extra: Optional[dict] = None

Additional data that is associated with the content. This field is optional.

field kind: Literal[Kind.Edge] = Kind.Edge

field payload: Any | None = None

A (JSON-serializable) item being sent from the source span to the destination span.

field source: list[str] [Required]

Name of the source span associated with this edge.

pydantic model agentc_core.activity.models.content.KeyValueContent

KeyValue refers to messages that contain user-specified data that are to be logged under some span.

Class Description

Key-value messages serve as the catch-all container for user-defined data that belong to some span. We distinguish key-value messages from log-level annotations, which are used to attach information to a log entry with existing content.

Key-value messages have two required fields: i) the key field (used to record the name of the entry) and ii) value (used to record the value of the entry). Extra data can also be passed in through the optional extra field (as with other messages).

Using the [] syntax with a agentc.span.Span instance generates one key-value entry per call. For example, the following code snippet generates two logs with the same key but different values:

my_span = catalog.Span(name="my_span")
my_span["alpha"] = alpha_value_1
my_span["alpha"] = alpha_value_2

These messages are commonly purposed for recording evaluation data, as seen in our example application here.

Show JSON schema

{
   "title": "KeyValueContent",
   "description": "KeyValue refers to messages that contain user-specified data that are to be logged under some span.\n\n.. card:: Class Description\n\n    Key-value messages serve as the catch-all container for user-defined data that belong to some span.\n    We distinguish key-value messages from log-level *annotations*, which are used to attach information to a log\n    entry with existing content.\n\n    Key-value messages have two required fields: i) the ``key`` field (used to record the name of the entry)\n    and ii) ``value`` (used to record the value of the entry).\n    Extra data can also be passed in through the optional ``extra`` field (as with other messages).\n\n    Using the :python:`[]` syntax with a :py:class:`agentc.span.Span` instance generates one key-value entry per\n    call.\n    For example, the following code snippet generates two logs with the same key but different values:\n\n    .. code-block:: python\n\n        my_span = catalog.Span(name=\"my_span\")\n        my_span[\"alpha\"] = alpha_value_1\n        my_span[\"alpha\"] = alpha_value_2\n\n    These messages are commonly purposed for recording evaluation data, as seen in our example application\n    `here <https://github.com/couchbaselabs/agent-catalog/tree/master/examples/with_langgraph>`__.",
   "type": "object",
   "properties": {
      "extra": {
         "anyOf": [
            {
               "additionalProperties": true,
               "type": "object"
            },
            {
               "type": "null"
            }
         ],
         "default": null,
         "description": "Additional data that is associated with the content. This field is optional.",
         "title": "Extra"
      },
      "kind": {
         "const": "key-value",
         "default": "key-value",
         "title": "Kind",
         "type": "string"
      },
      "key": {
         "description": "The name of the key-value pair.",
         "title": "Key",
         "type": "string"
      },
      "value": {
         "description": "The value of the key-value pair. This value should be JSON-serializable.",
         "title": "Value"
      }
   },
   "required": [
      "key",
      "value"
   ]
}

Config:

• frozen: bool = True

• use_enum_values: bool = True

Fields:

• extra (dict | None)

• key (str)

• kind (Literal[agentc_core.activity.models.content.Kind.KeyValue])

• value (Any)

field extra: Optional[dict] = None

Additional data that is associated with the content. This field is optional.

field key: str [Required]

The name of the key-value pair.

field kind: Literal[Kind.KeyValue] = Kind.KeyValue

field value: Any [Required]

The value of the key-value pair. This value should be JSON-serializable.