diff --git a/docs/index.rst b/docs/index.rst index 2f2affb..6fbd433 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -52,8 +52,6 @@ Internet of Agents Components pages/syntactic_sdk/connect pages/syntactic_sdk/agntcy_acp_sdk - pages/syntactic_sdk/agntcy_acp_reference - pages/syntactic_sdk/agntcy_acp_models pages/syntactic_sdk/api_bridge_agent pages/syntactic_sdk/hil diff --git a/docs/pages/syntactic_sdk/agntcy_acp_models.rst b/docs/pages/syntactic_sdk/agntcy_acp_models.rst index 0fe3921..823b26e 100644 --- a/docs/pages/syntactic_sdk/agntcy_acp_models.rst +++ b/docs/pages/syntactic_sdk/agntcy_acp_models.rst @@ -1,213 +1,126 @@ -API Models -=============== - -``Agent`` -*************************************** .. autopydantic_model:: agntcy_acp.models.Agent :members: -``AgentACPDescriptor`` -*************************************** .. autopydantic_model:: agntcy_acp.models.AgentACPDescriptor :members: -``AgentACPSpec`` -*************************************** .. autopydantic_model:: agntcy_acp.models.AgentACPSpec :members: -``AgentACPSpecInterruptsInner`` -*************************************** .. autopydantic_model:: agntcy_acp.models.AgentACPSpecInterruptsInner :members: -``AgentCapabilities`` -*************************************** .. autopydantic_model:: agntcy_acp.models.AgentCapabilities :members: -``AgentMetadata`` -*************************************** .. autopydantic_model:: agntcy_acp.models.AgentMetadata :members: -``AgentRef`` -*************************************** .. autopydantic_model:: agntcy_acp.models.AgentRef :members: -``AgentSearchRequest`` -*************************************** .. autopydantic_model:: agntcy_acp.models.AgentSearchRequest :members: -``Config`` -*************************************** .. autopydantic_model:: agntcy_acp.models.Config :members: -``Content`` -*************************************** .. autopydantic_model:: agntcy_acp.models.Content :members: -``ContentOneOfInner`` -*************************************** .. autopydantic_model:: agntcy_acp.models.ContentOneOfInner :members: -``CustomRunResultUpdate`` -*************************************** .. autopydantic_model:: agntcy_acp.models.CustomRunResultUpdate :members: -``Message`` -*************************************** .. autopydantic_model:: agntcy_acp.models.Message :members: -``MessageAnyBlock`` -*************************************** .. autopydantic_model:: agntcy_acp.models.MessageAnyBlock :members: -``MessageTextBlock`` -*************************************** .. autopydantic_model:: agntcy_acp.models.MessageTextBlock :members: -``Run`` -*************************************** .. autopydantic_model:: agntcy_acp.models.Run :members: -``RunCreate`` -*************************************** .. autopydantic_model:: agntcy_acp.models.RunCreate :members: -``RunCreateStateful`` -*************************************** .. autopydantic_model:: agntcy_acp.models.RunCreateStateful :members: -``RunCreateStateless`` -*************************************** .. autopydantic_model:: agntcy_acp.models.RunCreateStateless :members: -``RunError`` -*************************************** .. autopydantic_model:: agntcy_acp.models.RunError :members: -``RunInterrupt`` -*************************************** .. autopydantic_model:: agntcy_acp.models.RunInterrupt :members: -``RunOutput`` -*************************************** .. autopydantic_model:: agntcy_acp.models.RunOutput :members: -``RunOutputStream`` -*************************************** .. autopydantic_model:: agntcy_acp.models.RunOutputStream :members: -``RunResult`` -*************************************** .. autopydantic_model:: agntcy_acp.models.RunResult :members: -``RunSearchRequest`` -*************************************** .. autopydantic_model:: agntcy_acp.models.RunSearchRequest :members: -``RunStateful`` -*************************************** .. autopydantic_model:: agntcy_acp.models.RunStateful :members: -``RunStateless`` -*************************************** .. autopydantic_model:: agntcy_acp.models.RunStateless :members: -``RunStatus`` -*************************************** .. autoclass:: agntcy_acp.models.RunStatus :members: -``RunWaitResponseStateful`` -*************************************** .. autopydantic_model:: agntcy_acp.models.RunWaitResponseStateful :members: -``RunWaitResponseStateless`` -*************************************** .. autopydantic_model:: agntcy_acp.models.RunWaitResponseStateless :members: -``StreamEventPayload`` -*************************************** .. autopydantic_model:: agntcy_acp.models.StreamEventPayload :members: -``StreamMode`` -*************************************** .. autopydantic_model:: agntcy_acp.models.StreamMode :members: -``StreamingMode`` -*************************************** .. autoclass:: agntcy_acp.models.StreamingMode :members: -``StreamingModes`` -*************************************** .. autopydantic_model:: agntcy_acp.models.StreamingModes :members: -``Thread`` -*************************************** .. autopydantic_model:: agntcy_acp.models.Thread :members: -``ThreadCheckpoint`` -*************************************** .. autopydantic_model:: agntcy_acp.models.ThreadCheckpoint :members: -``ThreadCreate`` -*************************************** .. autopydantic_model:: agntcy_acp.models.ThreadCreate :members: -``ThreadPatch`` -*************************************** .. autopydantic_model:: agntcy_acp.models.ThreadPatch :members: -``ThreadSearchRequest`` -*************************************** .. autopydantic_model:: agntcy_acp.models.ThreadSearchRequest :members: -``ThreadState`` -*************************************** .. autopydantic_model:: agntcy_acp.models.ThreadState :members: -``ThreadStatus`` -*************************************** .. autoclass:: agntcy_acp.models.ThreadStatus :members: -``ValueRunResultUpdate`` -*************************************** .. autopydantic_model:: agntcy_acp.models.ValueRunResultUpdate :members: diff --git a/docs/pages/syntactic_sdk/agntcy_acp_reference.rst b/docs/pages/syntactic_sdk/agntcy_acp_reference.rst index 8d5b58f..c110c6a 100644 --- a/docs/pages/syntactic_sdk/agntcy_acp_reference.rst +++ b/docs/pages/syntactic_sdk/agntcy_acp_reference.rst @@ -1,165 +1,111 @@ -Client Reference API -============================= - +^^^^^^^^^^^ ACP Objects --------------- +^^^^^^^^^^^ -``ApiClientConfiguration`` -*************************************** .. autoclass:: agntcy_acp.ApiClientConfiguration :members: :inherited-members: -``ACPClient`` -***************************** .. autoclass:: agntcy_acp.ACPClient :members: :inherited-members: -``AsyncACPClient`` -***************************** .. autoclass:: agntcy_acp.AsyncACPClient :members: :inherited-members: -``ApiClient`` -***************************** .. autoclass:: agntcy_acp.ApiClient :members: :inherited-members: -``AsyncApiClient`` -***************************** .. autoclass:: agntcy_acp.AsyncApiClient :members: :inherited-members: -``ApiResponse`` -***************************** .. autopydantic_model:: agntcy_acp.ApiResponse :members: +^^^^^^^^^^^^^^^^^^ LangGraph Bindings ------------------------ +^^^^^^^^^^^^^^^^^^ -``ACPNode`` -***************************** .. autoclass:: agntcy_acp.langgraph.ACPNode :members: -``APIBridgeAgentNode`` -***************************** .. autoclass:: agntcy_acp.langgraph.APIBridgeAgentNode :members: :inherited-members: -``APIBridgeInput`` -***************************** .. autopydantic_model:: agntcy_acp.langgraph.APIBridgeInput :members: -``APIBridgeOutput`` -***************************** .. autopydantic_model:: agntcy_acp.langgraph.APIBridgeOutput :members: -``add_io_mapped_edge`` -***************************** .. autofunction:: agntcy_acp.langgraph.add_io_mapped_edge -``add_io_mapped_conditional_edge`` -**************************************** .. autofunction:: agntcy_acp.langgraph.add_io_mapped_conditional_edge +^^^^^^^^^^ Exceptions ------------- +^^^^^^^^^^ -``ACPDescriptorValidationException`` -******************************************** .. autoclass:: agntcy_acp.ACPDescriptorValidationException :members: :inherited-members: -``ACPRunException`` -***************************** .. autoclass:: agntcy_acp.ACPRunException :members: :inherited-members: -``ApiTypeError`` -***************************** .. autoclass:: agntcy_acp.ApiTypeError :members: :inherited-members: -``ApiValueError`` -***************************** .. autoclass:: agntcy_acp.ApiValueError :members: :inherited-members: -``ApiKeyError`` -***************************** .. autoclass:: agntcy_acp.ApiKeyError :members: :inherited-members: -``ApiAttributeError`` -***************************** .. autoclass:: agntcy_acp.ApiAttributeError :members: :inherited-members: -``ApiException`` -***************************** .. autoclass:: agntcy_acp.ApiException :members: :inherited-members: -``BadRequestException`` -***************************** .. autoclass:: agntcy_acp.BadRequestException :members: :inherited-members: -``NotFoundException`` -***************************** .. autoclass:: agntcy_acp.NotFoundException :members: :inherited-members: -``UnauthorizedException`` -***************************** .. autoclass:: agntcy_acp.UnauthorizedException :members: :inherited-members: -``ForbiddenException`` -***************************** .. autoclass:: agntcy_acp.ForbiddenException :members: :inherited-members: -``ServiceException`` -***************************** .. autoclass:: agntcy_acp.ServiceException :members: :inherited-members: -``ConflictException`` -************************************ .. autoclass:: agntcy_acp.ConflictException :members: :inherited-members: -``UnprocessableEntityException`` -************************************ .. autoclass:: agntcy_acp.UnprocessableEntityException :members: :inherited-members: -``OpenApiException`` -***************************** .. autoclass:: agntcy_acp.OpenApiException :members: :inherited-members: diff --git a/docs/pages/syntactic_sdk/agntcy_acp_sdk.md b/docs/pages/syntactic_sdk/agntcy_acp_sdk.md index 6fb9726..2793dbd 100644 --- a/docs/pages/syntactic_sdk/agntcy_acp_sdk.md +++ b/docs/pages/syntactic_sdk/agntcy_acp_sdk.md @@ -1,4 +1,4 @@ -# Agntcy ACP Client SDK +# Agntcy ACP Client ## Introduction @@ -26,7 +26,7 @@ pip install agntcy-acp ### Usage -```python +```{code-block} python from agntcy_acp import AsyncACPClient, AsyncApiClient, ApiException from agntcy_acp.models import RunCreate @@ -51,15 +51,158 @@ async with AsyncApiClient(config) as api_client: ### Documentation for API Endpoints -All URIs are relative to *http://localhost* +The complete documentation for all of the API Endpoints are +available in the reference documentation for the API clients: + + * [ApiClient](/pages/syntactic_sdk/agntcy_acp_reference.html#acpclient) + * [AsyncApiClient](/pages/syntactic_sdk/agntcy_acp_reference.html#asyncacpclient) ## Using ACP with LangGraph +The SDK provides integration with LangGraph with the {py:obj}`agntcy_acp.langgraph.ACPNode` class +that can be used as a graph node: + +```python +from enum import Enum +from typing import List, Optional + +from langgraph.graph import END, START, StateGraph +from pydantic import BaseModel, Field + +from agntcy_acp import ApiClientConfiguration +from agntcy_acp.langgraph.acp_node import ACPNode + + +class Type(Enum): + human = 'human' + assistant = 'assistant' + ai = 'ai' + +class Message(BaseModel): + type: Type = Field( + ..., + description='indicates the originator of the message, a human or an assistant', + ) + content: str = Field(..., description='the content of the message', title='Content') + +class InputSchema(BaseModel): + messages: Optional[List[Message]] = Field(None, title='Messages') + is_completed: Optional[bool] = Field(None, title='Is Completed') + +class OutputSchema(BaseModel): + messages: Optional[List[Message]] = Field(None, title='Messages') + is_completed: Optional[bool] = Field(None, title='Is Completed') + final_email: Optional[str] = Field( + None, + description='Final email produced by the mail composer', + title='Final Email', + ) + +class StateMeasures(BaseModel): + input: InputSchema + output: OutputSchema + +def main(): + # Instantiate the local ACP node for the remote agent + acp_node = ACPNode( + name="mailcomposer", + agent_id='50272dfd-4c77-4529-abbb-419bb1724230', + client_config=ApiClientConfiguration.fromEnvPrefix("COMPOSER_"), + input_path="input", + input_type=InputSchema, + output_path="output", + output_type=OutputSchema, + ) + + # Create the state graph + sg = StateGraph(StateMeasures) + + # Add edges + sg.add_edge(START, acp_node.get_name()) + sg.add_edge(acp_node.get_name(), END) + + graph = sg.compile() + output_state = graph.invoke({ + "input": InputSchema(content=input), + "output": OutputSchema(content="bad-output"), + }) +``` + +## Using the CLI to generate Agent-specific bindings + +The Client SDK includes a CLI tool to generate models or OpenAPI specs +specific to an agent using the manifest descriptor. With these models +the agent-specific data sent to ACP can be validated. By default, +only the ACP parameters are validated by the SDK client. + +The CLI also provides validators for the ACP descriptor and manifest +files. + +You can use the CLI easily: + * using [poetry](https://python-poetry.org/): `poetry run acp --help` + * with the package installed: `python3 -m agntcy_acp --help` + +Usage: `acp [OPTIONS] COMMAND [ARGS]...` + + Options: + + * `--help` Show this message and exit. + +Commands: + +* `generate-agent-models [OPTIONS] AGENT_DESCRIPTOR_PATH` + + Generate pydantic models from agent manifest or descriptor. + + Options: + + * `--output-dir TEXT` + + Pydantic models for specific agent based on provided + agent descriptor or agent manifest [required] + + * `--model-file-name TEXT` + + Filename containing the pydantic model of the agent + schemas + +* `generate-agent-oapi [OPTIONS] AGENT_DESCRIPTOR_PATH` + + Generate OpenAPI Spec from agent manifest or descriptor + + Options: + + * `--output TEXT` + + OpenAPI output file + +* `validate-acp-descriptor [OPTIONS] AGENT_DESCRIPTOR_PATH` + + Validate the Agent Descriptor contained in the file AGENT_DESCRIPTOR_PATH + against the ACP specification + +* `validate-acp-manifest [OPTIONS] AGENT_MANIFEST_PATH` + + Validate the Agent Manifest contained in the file AGENT_MANIFEST_PATH + against the Manifest specification + ## Testing -To test the package, run `make test`. +To run the various unit tests in the package, run `make test`. ## Roadmap -See the [open issues](https://github.com/agntcy/acp-sdk/issues) for a list of proposed features and known issues. \ No newline at end of file +See the [open issues](https://github.com/agntcy/acp-sdk/issues) for a list of proposed features and known issues. + +## Client Reference API + +```{eval-rst} +.. include:: ./agntcy_acp_reference.rst +``` + +## API Models + +```{eval-rst} +.. include:: ./agntcy_acp_models.rst +```