aws / aws/bedrock-agentcore-starter-toolkit

[Enhancement] Add background/daemon mode for `agentcore launch --local`

Open
#144 1 comment 0 reactions 0 assignees View on GitHub
invalid runtime
Dominant language
Python
Stars
508
Forks
155
Avg merge
8h 50m
Merged PRs (30d)
4

Description

## Summary
Add `--detach` and `--log-file` options to `agentcore launch --local` to enable background execution and log redirection, improving compatibility with AI IDEs like Kiro that need to reuse terminal sessions.

## Problem Description
Currently, `agentcore launch --local` always runs in the foreground, blocking the terminal until manually stopped with Ctrl+C. This creates usability issues for:

- **AI IDEs like Kiro**: Need to reuse the same terminal for multiple operations
- **Development workflows**: Developers want to run the agent locally while continuing to use the terminal
- **CI/CD pipelines**: Automated testing scenarios that need background agent execution
- **Multi-agent development**: Running multiple agents simultaneously in different terminals

**Current behavior:**
```bash
$ agentcore launch --local
Starting server at http://localhost:8080
Press Ctrl+C to stop

# Terminal is blocked here - cannot run other commands
```

## Proposed Solution

### 1. Add `--detach/-d` flag (Docker-style)
```bash
# Run in background (detached mode) - follows Docker convention
agentcore launch --local --detach
agentcore launch --local -d

# Output:
# Agent started in detached mode (PID: 12345)
# Server running at http://localhost:8080
# Agent running in background...
```

### 2. Add `--log-file` option (Docker-style)
```bash
# Redirect logs to file (like docker run --log-driver)
agentcore launch --local --detach --log-file agent.log

# Or with custom path
agentcore launch --local -d --log-file /tmp/my-agent.log
```

### 3. Process Management (Future Enhancement)
Process management commands will be added in future PRs:
```bash
# Future: List running local agents
agentcore ps --local

# Future: Stop local agents
agentcore stop --local AGENT_NAME
agentcore stop --local --all

# Future: View local agent logs
agentcore logs --local AGENT_NAME
agentcore logs --local -f AGENT_NAME
```

## Implementation Details

### Command Line Interface Changes

```python
def launch(
# ... existing parameters ...
detach: bool = typer.Option(
False, "--detach", "-d",
help="Run in detached mode (background) - only works with --local"
),
log_file: Optional[str] = typer.Option(
None, "--log-file",
help="Redirect logs to file (implies --detach for --local mode)"
),
):
```

### Process Management
- Use Python's `subprocess.Popen` for background process spawning
- Store PID in a state file (e.g., `.agentcore/local_agents.json`)
- Implement proper signal handling for graceful shutdown
- Basic process lifecycle management

### Log Management
- Default log location: `.agentcore/logs/{agent_name}.log`
- Custom log file paths supported via `--log-file`
- Structured logging with timestamps
- Log file creation and directory management

### State Tracking (Basic)
Store running agent information in `.agentcore/local_agents.json`:
```json
{
"agents": [
{
"name": "my-agent",
"pid": 12345,
"port": 8080,
"log_file": "/path/to/agent.log",
"started_at": "2025-08-29T20:00:00Z"
}
]
}
```

## Usage Examples

### Basic detached mode
```bash
# Start agent in background (detached)
agentcore launch --local --detach

# Continue using terminal for other tasks
agentcore invoke '{"message": "Hello"}'

# Agent runs in background until manually stopped
```

### Development workflow with custom logs
```bash
# Start agent with custom log file
agentcore launch --local --detach --log-file dev.log

# Or just specify log file (auto-detaches)
agentcore launch --local --log-file my-agent.log

# Continue development work in same terminal
agentcore invoke '{"message": "test"}'
```

### AI IDE Integration
```bash
# Perfect for IDEs like Kiro - no terminal blocking
agentcore launch --local --detach

# IDE can continue using terminal for other operations
# Agent runs independently in background
```

## Benefits

### For AI IDEs (Kiro, Cursor, etc.)
- **Terminal reuse**: Can run agent in background and continue using terminal
- **Automation**: Can start/stop agents programmatically
- **Multi-agent workflows**: Support multiple agents for complex scenarios

### For Developers
- **Improved DX**: No need to open multiple terminals
- **Persistent agents**: Agents survive terminal sessions
- **Better debugging**: Centralized log management
- **CI/CD friendly**: Scriptable background execution

### For Production-like Testing
- **Service simulation**: Run agents like system services
- **Load testing**: Multiple concurrent agents
- **Integration testing**: Background agents for test suites

## Alternative Solutions Considered

### 1. Manual backgrounding with `&`
```bash
agentcore launch --local &
```
**Issues**:
- No process management
- Logs mixed with terminal output
- No clean shutdown mechanism
- PID tracking is manual

### 2. External process managers (systemd, pm2)
**Issues**:
- Additional dependencies
- Platform-specific solutions
- Complex setup for simple use case

### 3. Docker Compose
**Issues**:
- Overkill for single agent development
- Additional configuration files
- Not integrated with agentcore CLI

## Docker Consistency

This proposal follows Docker's established conventions:

| Docker Command | AgentCore Equivalent | Purpose | Status |
|----------------|---------------------|---------|---------|
| `docker run -d nginx` | `agentcore launch --local -d` | Run in background | **This PR** |
| `docker ps` | `agentcore ps --local` | List running containers/agents | Future PR |
| `docker logs container` | `agentcore logs --local agent` | View logs | Future PR |
| `docker logs -f container` | `agentcore logs --local -f agent` | Follow logs | Future PR |
| `docker stop container` | `agentcore stop --local agent` | Stop container/agent | Future PR |
| `docker stop $(docker ps -q)` | `agentcore stop --local --all` | Stop all | Future PR |

### Why Docker-style is Better
- **Familiar**: Developers already know Docker conventions
- **Consistent**: Same patterns across container tools
- **Standard**: `-d/--detach` is the industry standard
- **Intuitive**: `ps`, `logs`, `stop` are universally understood

## Implementation Priority

### This PR (Core Detach Mode)
- [ ] `--detach/-d` flag for `agentcore launch --local`
- [ ] `--log-file` option with automatic detach
- [ ] Basic PID tracking and state file
- [ ] Process spawning and background execution
- [ ] Validation and error handling
- [ ] Backward compatibility

## Compatibility

- **Backward compatible**: Existing `agentcore launch --local` behavior unchanged
- **Cross-platform**: Works on macOS, Linux, and Windows
- **Docker agnostic**: Works with Docker, Finch, and Podman
- **IDE integration**: Designed for AI IDE workflows
- **Docker-consistent**: Follows established container management patterns

## Related Issues
- Improves developer experience for local agent development
- Enables better integration with AI IDEs like Kiro
- Supports advanced testing scenarios with multiple agents
- Aligns with modern development tool expectations (similar to `npm start`, `docker-compose up -d`)

---

**Impact**: This enhancement would significantly improve the developer experience for local AgentCore development, especially for users of AI IDEs who need flexible terminal management and background process execution.

Contributor guide

Open the contributing guide

Research direction

Start at the `agentcore launch` CLI entry point and its `--local` execution path; inspect how foreground output and shutdown are currently handled. Define the detached and `--log-file` behavior, including PID/state tracking, validation, signal handling, and cross-platform expectations. Done means the requested flags work without changing existing foreground behavior and satisfy the listed compatibility requirements.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli, developer-experience
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.