feat(bidirectional): Add agent.run

[mkmeral]

Description

Added a run() method to BidirectionalAgent that manages send/receive event loops internally. This provides a cleaner API for integrating the agent with WebSocket or other bidirectional communication channels.

Before:

async def receive_from_agent(agent, websocket):
    async for event in agent.receive():
        await websocket.send_json(event)

async def send_to_agent(agent, websocket):
    while True:
        event = await websocket.receive_json()
        await agent.send(event)

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    agent = BidirectionalAgent(model=model, tools=[calculator])
    await agent.start()
    await asyncio.gather(
        receive_from_agent(agent, websocket),
        send_to_agent(agent, websocket),
        return_exceptions=True
    )
    await agent.end()

After:

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    agent = BidirectionalAgent(model=model, tools=[calculator])
    await agent.run(sender=websocket.send_json, receiver=websocket.receive_json)

The run() method:

• Accepts keyword-only async callables for send/receive (not limited to WebSocket)
• Uses clear parameter names (sender and receiver) to avoid confusion about order
• Automatically calls start() and end() for session lifecycle management
• Manages both event loops concurrently using asyncio.gather()
• Handles cleanup in a finally block to ensure proper resource cleanup

Related Issues

Documentation PR

Type of Change

New feature

Testing

How have you tested the change? Verify that the changes do not break functionality or introduce warnings in consuming repositories: agents-docs, agents-tools, agents-cli

• I ran hatch run prepare

Checklist

• I have read the CONTRIBUTING document
• I have added any necessary tests that prove my fix is effective or my feature works
• I have updated the documentation accordingly
• I have added an appropriate example to the documentation to outline the feature, or no new docs are needed
• My changes generate no new warnings
• Any dependent changes have been merged and published

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.