A programming framework for agentic AI
Add API documentation (#4798)
peterychang9c8877ed664e
diff --git a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/agent-identity-and-lifecycle.md b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/agent-identity-and-lifecycle.mdindex 4a4439500..0dae41e78 100644--- a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/agent-identity-and-lifecycle.md+++ b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/agent-identity-and-lifecycle.md@@ -1,3 +1,4 @@+(agentid_and_lifecycle)=# Agent Identity and LifecycleThe agent runtime manages agents' identitiesdiff --git a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/topic-and-subscription.md b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/topic-and-subscription.mdindex 340ad96b8..7af198f00 100644--- a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/topic-and-subscription.md+++ b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/core-concepts/topic-and-subscription.md@@ -12,6 +12,7 @@ will handle their messages, and a workflow can be composed of agentswith no inter-dependencies.This section focuses on the core concepts in broadcast: topic and subscription.+(topic_and_subscription_topic)=## TopicA topic defines the scope of a broadcast message.diff --git a/python/packages/autogen-core/src/autogen_core/_agent_id.py b/python/packages/autogen-core/src/autogen_core/_agent_id.pyindex 9aae843eb..de046592c 100644--- a/python/packages/autogen-core/src/autogen_core/_agent_id.py+++ b/python/packages/autogen-core/src/autogen_core/_agent_id.py@@ -10,6 +10,12 @@ def is_valid_agent_type(value: str) -> bool:class AgentId:+ """+ Agent ID uniquely identifies an agent instance within an agent runtime - including distributed runtime. It is the 'address' of the agent instance for receiving messages.++ See here for more information: :ref:`agentid_and_lifecycle`+ """+def __init__(self, type: str | AgentType, key: str) -> None:if isinstance(type, AgentType):type = type.type@@ -36,6 +42,7 @@ class AgentId:@classmethoddef from_str(cls, agent_id: str) -> Self:+ """Convert a string of the format ``type/key`` into an AgentId"""items = agent_id.split("/", maxsplit=1)if len(items) != 2:raise ValueError(f"Invalid agent id: {agent_id}")@@ -44,8 +51,18 @@ class AgentId:@propertydef type(self) -> str:+ """+ An identifier that associates an agent with a specific factory function.++ Strings may only be composed of alphanumeric letters (a-z) and (0-9), or underscores (_).+ """return self._type@propertydef key(self) -> str:+ """+ Agent instance identifier.++ Strings may only be composed of alphanumeric letters (a-z) and (0-9), or underscores (_).+ """return self._keydiff --git a/python/packages/autogen-core/src/autogen_core/_agent_proxy.py b/python/packages/autogen-core/src/autogen_core/_agent_proxy.pyindex f3eb70f28..09cf3c1de 100644--- a/python/packages/autogen-core/src/autogen_core/_agent_proxy.py+++ b/python/packages/autogen-core/src/autogen_core/_agent_proxy.py@@ -11,6 +11,8 @@ if TYPE_CHECKING:class AgentProxy:+ """A helper class that allows you to use an :class:`~autogen_core.AgentId` in place of its associated :class:`~autogen_core.Agent`"""+def __init__(self, agent: AgentId, runtime: AgentRuntime):self._agent = agentself._runtime = runtimediff --git a/python/packages/autogen-core/src/autogen_core/_cancellation_token.py b/python/packages/autogen-core/src/autogen_core/_cancellation_token.pyindex 5aa449039..06e037e53 100644--- a/python/packages/autogen-core/src/autogen_core/_cancellation_token.py+++ b/python/packages/autogen-core/src/autogen_core/_cancellation_token.py@@ -4,12 +4,15 @@ from typing import Any, Callable, Listclass CancellationToken:+ """A token used to cancel pending async calls"""+def __init__(self) -> None:self._cancelled: bool = Falseself._lock: threading.Lock = threading.Lock()self._callbacks: List[Callable[[], None]] = []def cancel(self) -> None:+ """Cancel pending async calls linked to this cancellation token."""with self._lock:if not self._cancelled:self._cancelled = True@@ -17,10 +20,12 @@ class CancellationToken:callback()def is_cancelled(self) -> bool:+ """Check if the CancellationToken has been used"""with self._lock:return self._cancelleddef add_callback(self, callback: Callable[[], None]) -> None:+ """Attach a callback that will be called when cancel is invoked"""with self._lock:if self._cancelled:callback()@@ -28,6 +33,7 @@ class CancellationToken:self._callbacks.append(callback)def link_future(self, future: Future[Any]) -> Future[Any]:+ """Link a pending async call to a token to allow its cancellation"""with self._lock:if self._cancelled:future.cancel()diff --git a/python/packages/autogen-core/src/autogen_core/_topic.py b/python/packages/autogen-core/src/autogen_core/_topic.pyindex c8965a7da..67d4a246f 100644--- a/python/packages/autogen-core/src/autogen_core/_topic.py+++ b/python/packages/autogen-core/src/autogen_core/_topic.py@@ -10,6 +10,12 @@ def is_valid_topic_type(value: str) -> bool:@dataclass(eq=True, frozen=True)class TopicId:+ """+ TopicId defines the scope of a broadcast message. In essence, agent runtime implements a publish-subscribe model through its broadcast API: when publishing a message, the topic must be specified.++ See here for more information: :ref:`topic_and_subscription_topic`+ """+type: str"""Type of the event that this topic_id contains. Adhere's to the cloud event spec.@@ -33,6 +39,7 @@ class TopicId:@classmethoddef from_str(cls, topic_id: str) -> Self:+ """Convert a string of the format ``type/source`` into a TopicId"""items = topic_id.split("/", maxsplit=1)if len(items) != 2:raise ValueError(f"Invalid topic id: {topic_id}")